README.md 9.05 KB
Newer Older
Jake Read's avatar
1st  
Jake Read committed
1
2
# AutomataKit

Jake Read's avatar
doc    
Jake Read committed
3
AutomataKit is a collection of reconfigurable open hardware and software for machine-building, process development, and robotics projects. 
Jake Read's avatar
1st  
Jake Read committed
4

Jake Read's avatar
doc    
Jake Read committed
5
It uses a Distributed Dataflow Programming paradigm: hardware and software objects are all nodes in a graph, executing computing and physical tasks, together!
Jake Read's avatar
1st  
Jake Read committed
6

Jake Read's avatar
doc    
Jake Read committed
7
[RuNDMC](https://gitlab.cba.mit.edu/jakeread/rndmc) serves a development environment for those graphs.
Jake Read's avatar
Jake Read committed
8
9

![atkapi](images/machine-with-atkapi.jpg)
Jake Read's avatar
1st  
Jake Read committed
10

Jake Read's avatar
Jake Read committed
11
# Machines Made with These Controllers
Jake Read's avatar
Jake Read committed
12

Jake Read's avatar
Jake Read committed
13
 - [Mother Mother: a Machine Generalist](https://gitlab.cba.mit.edu/jakeread/reich)
Jake Read's avatar
Jake Read committed
14
 - [*A Machine* for playing *Music for Pieces of Wood* by Steve Reich by Jake Read](https://gitlab.cba.mit.edu/jakeread/reich)
Jake Read's avatar
Jake Read committed
15
16
17
 - [MPVMachine](https://gitlab.cba.mit.edu/jakeread/mpvmachine)
 - [SmallGantries](https://gitlab.cba.mit.edu/jakeread/smallgantries)
 - [ClayStacker](https://gitlab.cba.mit.edu/jakeread/claystack)
Jake Read's avatar
Jake Read committed
18

Jake Read's avatar
Jake Read committed
19
20
21
22
23
24
25
26
27
28
29
30
31
# The Endpoints

![endpoints](images/endpoints.jpg)

Endpoints are designed to be very simple: they receive minimum viable commands and keep minimal state required for operation. This way, system complexity can be organized in the particular application, not distributed throughout the system. For example, steppers receive very simple trapezoid motion segements to execute, and don't do much math except for counting steps. 

 - [ATKRouter](https://gitlab.cba.mit.edu/jakeread/atkrouter)
 - [ATKStepper17](https://gitlab.cba.mit.edu/jakeread/atkstepper17)
 - [ATKStepper23](https://gitlab.cba.mit.edu/jakeread/atkstepper23)
 - [ATKBreadBoardBoard](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard)
 - [ATKBLDCDriver](https://gitlab.cba.mit.edu/jakeread/atkbldcdriver)


Jake Read's avatar
Jake Read committed
32
# The Network
Jake Read's avatar
1st  
Jake Read committed
33

Jake Read's avatar
Jake Read committed
34
35
36
To make individual motors and sensors modular, AutomataKit endpoints use a port-forwarding, source-routed network. This is *not a bus* and can be connected in a complete graph. All connections are full-duplex and include support for hardware clock synchronization.

Packets typically originate on the network over a usb-to-serial bridge, so you can interface with networked endpoints using any piece of software you can successfully use to open a COM port with: JavaScript, Python etc. The [AutomataKit Router](https://gitlab.cba.mit.edu/jakeread/atkrouter) includes one UBS-to-UART Bridge, which is treated as the 6th port on the router. 
Jake Read's avatar
1st  
Jake Read committed
37

Jake Read's avatar
Jake Read committed
38
39
40
41
42
43
44
45
46
47
48
The hardware (or 'PHY' layer) of the network is simple UART. That means that all the network is, is a few UART links between microcontrollers, and some C code that listens for incoming packets and forward messages according to the instructions in the packet. Critically, there are not *addresses* in the network, instead, packets themseleves carry routes: this is 'source routing' in network nomenclature. 

### The Packet

Because our UART hardwares typically operate on bytes, our packets are sets of bytes. Packets are structured like this:

![packet typ](/images/apa-networking-diagrams-packet.png)

### Port Forwarding and Route Shifting

Bytes between the Length Byte and the *Packet Header End Delimiter* define the route. As the packet moves through the network, it is forwarded on the ports in the list, in order. To keep track of the current position of the packet (which port is next in the list) we shift the list of ports along at each forwarding instance, such that the 2nd byte in the packet is always denoting the next port to forward on. We append to the end of the header the port which the packet arrived on, and that way we keep a return route in the packet. When the packet arrives on a port and the *Packet Pointer* is the next byte, the recipient knows the packet has been sent to them, and they handle it.
Jake Read's avatar
1st  
Jake Read committed
49

Jake Read's avatar
Jake Read committed
50
![packet typ](/images/apa-networking-diagrams-traversal.png)
Jake Read's avatar
1st  
Jake Read committed
51

Jake Read's avatar
Jake Read committed
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# The Firmware

So far, the endpoints all have xmega microcontrollers at their heart. In particular, the ```XMEGA256A3U``` : the biggest, baddest xmega. We clock it at 48MHz. That said, this isn't a requirement - any microcontroller with a UART port can play.

Firmware can be found in each board's repository under the ```embedded/``` directory. Build, run and debug via the instructions [here](reproduction/firmware.md), or roll your own toolchain.

[typical main.c](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/main.c)

Packet handling is like this: [uartports](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/uartport.c) handle interrupts that pull incoming data into [ringbuffers](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/ringbuffer.c). These are scanned [with this structure](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/atkport.c) and then handled [with this one](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/atkhandler.c). Global things are kept in [this include file](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/hardware.h). 

All in, probably there is too much pointing->through->things, as I understand this takes a cycle on each link. 

As for DMA, the XMEGA has only four channels (if I understand correctly) so unless I get my hands dirty doing channel-management, the router isn't going to work (it has 6 ports, plus a usb link). 

Jake Read's avatar
doc    
Jake Read committed
66
# Usage
Jake Read's avatar
Jake Read committed
67

Jake Read's avatar
doc    
Jake Read committed
68
69
## Wiring

Jake Read's avatar
Jake Read committed
70
71
72
73
74
75
76
77
78
79
80
81
#### Powering Boards

The network cables don't carry any power, just four pairs of differential signals. So each board needs a power connection as well.

The boards should all share a ground, but can run on different voltages of input power. Most will take 24v on two M3 screw-mounts - I use eye terminals soldered to 18ga wire to deliver power. 

The router can also accept power from a USB device. If you're powering it over USB, *do not* also power it via 24v. 

Last thing, don't power your supply on before you go to screw power connections onto the boards. Wire them up, and then switch on.

#### Network Cables 

Jake Read's avatar
doc    
Jake Read committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
At a bare minimum, you're going to be hooking these things up to power, and to each other (network). 

 - network cables can be made two ways: only one is correct - *rj45 tabs should be on the same side of the ribbon cable* i.e. the cable is a 'straight through' type, not a crossover. this means that tx meets rx, etc. 
 - the transmit / receive ports are RS-485 Differential Driven, meaning there is no common gnd connection between boards besides the power bus. 

The connectors I use are called 'RJ45' Jacks and Plugs. These are standard for Ethernet, but also 'generally useful'. This is not ethernet, but these *are* RJ45. It's 8 wires, and in our case that's four differential pairs - two duplex lines on each side.

One cool thing about RJ45 is the modularity of the cables. We can use commodity crimping tools to make our own lengths:
 - one side cuts, one side strips. use both at the same time to get the right length of stripped wire
 - use the '8p' crimp, note the tab direction in the crimp
 - pinch! the plug has a plastic tab inside that should come down to meet the wire jacket 

![rj45 video](images/rj45-assembly.mp4)

```make sure those tabs are on the same side of the flat cable```

![rj45](images/rj45-tabs.jpg)

To power the boards, I put M3 'studs' on each PCB. These can handle lots of current, and have a good mechanical connection. To hookup, I solder or crimp eye-terminals onto ~ 18ga - 14ga wire, then screw them down with short M3 Socket Head Screws. 

Power can be bussed - i.e. we can screw two terminals onto the same stud to make the circuit a 'drop' on the line. 

Jake Read's avatar
doc    
Jake Read committed
104
## Network Interface
105

Jake Read's avatar
doc    
Jake Read committed
106
Once you understand the packet structure, any program you can imagine to write that has access to a USB or Serial Port, can issue and receieve packets. For us, this means [RNDMC](https://gitlab.cba.mit.edu/jakeread/rndmc) - a Reconfigurable Numeric Dataflow Machine Controller. For you, it might mean some other Node.js program (some exaple code for a simple version of which is available [here](atkterminal.js)), or Python, etc. 
107

Jake Read's avatar
doc    
Jake Read committed
108
## [Firmware -> XMEGAs](reproduction/firmware.md)
Jake Read's avatar
Jake Read committed
109

Jake Read's avatar
doc    
Jake Read committed
110
Once you've gotten your hands on / or built some ATK Hardware, you'll need to load some C Code (firmware!) onto each chip. The link above is a guide for this.
Jake Read's avatar
Jake Read committed
111

Jake Read's avatar
doc    
Jake Read committed
112
## [Circuit Reference](reproduction/circuits.md)
113

Jake Read's avatar
doc    
Jake Read committed
114
If you'd like to make your own hardware for the network, I recommend using the [ATKBreadBoardBoard](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard) whose documentation also includes a 'daughter' board starter - this will let you plug some new circuitry right onto the available XMEGA pinouts, and use known-to-work programming, voltage regulation, and network interface hardware. 
Jake Read's avatar
1st  
Jake Read committed
115

Jake Read's avatar
Jake Read committed
116
117
118
119
Along with this note, there's more detailed explanation in the link above.

# Development Notes

Jake Read's avatar
Jake Read committed
120
121
122
123
 - the push now is to find backpressure in the network, and go for a four wire 
 - also / in that case, a router board with dma access (x usb on each chip) and maybe a rethink of the headboard / daughter lookout ... face-to-face so that single sided PNP is possible (usb on same side ... nice to port-in wherever) ... port on the 'other side' then ? or also on same side and SMD ? 
 - do big value bleed resistor on capacitor board 
 - do an ODB / CP2102n link