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

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

Jake Read's avatar
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.
Jake Read's avatar
1st  
Jake Read committed
6

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

![atkapi](images/atkapi.png)

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

Jake Read's avatar
Jake Read committed
13
14
# Examples 

Jake Read's avatar
Jake Read committed
15
 - [Mother Mother: a Machine Generalist](https://gitlab.cba.mit.edu/jakeread/reich)
Jake Read's avatar
Jake Read committed
16
 - [*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
17
18
19
 - [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
20

Jake Read's avatar
Jake Read committed
21
## The Network
Jake Read's avatar
1st  
Jake Read committed
22

Jake Read's avatar
Jake Read committed
23
24
25
26
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
27

Jake Read's avatar
Jake Read committed
28
29
30
31
32
33
34
35
36
37
38
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
39

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

## The Endpoints 

Jake Read's avatar
Jake Read committed
44
45
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. 

Jake Read's avatar
1st  
Jake Read committed
46
47
48
49
50
 - [ATKRouter](https://gitlab.cba.mit.edu/jakeread/atkrouter)
 - [ATKStepper17](https://gitlab.cba.mit.edu/jakeread/atkstepper17)
 - [ATKStepper23](https://gitlab.cba.mit.edu/jakeread/atkstepper23)
 - [ATKBLDCDriver](https://gitlab.cba.mit.edu/jakeread/atkbldcdriver)

Jake Read's avatar
Jake Read committed
51
# Interfacing with AutomataKit
Jake Read's avatar
1st  
Jake Read committed
52

Jake Read's avatar
Jake Read committed
53
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. 
Jake Read's avatar
1st  
Jake Read committed
54

Jake Read's avatar
Jake Read committed
55
## Interfacing with Mods
Jake Read's avatar
1st  
Jake Read committed
56

Jake Read's avatar
Jake Read committed
57
58
59
60
61
62
63
64
65
[mods](mods.cba.mit.edu) is a browser-side system for composing software workflows. A development version for mods that includes modules for use with AutomataKit lives on a branch at [/jake](https://gitlab.cba.mit.edu/pub/mods/tree/jake).

To run this branch locally, clone the repository and use ``git checkout jake`` when in the mods directory. Now you can run a local webserver, one of which is included in node - which you can install using [this guide](/reproduction/installing-node-sp-ws.md). From the mods directory, use ``http-server`` and you should see the IP address and port you can type into your browser to begin.

Because mods is browser-side, it needs some help to access hardware on your machine (i.e. the USB-to-UART bridge). To do this, we use a websocket server and an interface module.

The interface module can be opened in mods under /modules/hardware/network, or by searching for **atkbridge**. 

The websocket server is a small node.js application, similar to ATKTerminal, and is located at mods/js/atkserialserver.js. To use this application, you will want to clone the mods repository, navigate to the /js folder and open atkserialserver with ``node atkserialserver <client address> <server port> <com port>`` where **client address** and **server port** are specified in the reflecting module, and the **com port** that your USB-to-UART bridge is located on, which you can find using ``serialport-list`` from the same command line.  
Jake Read's avatar
1st  
Jake Read committed
66

Jake Read's avatar
Jake Read committed
67
Once this application is open, it should maintain a connection to mods and the serial hardware.
Jake Read's avatar
1st  
Jake Read committed
68

Jake Read's avatar
Jake Read committed
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
... how to format packets for mdos 


## Interfacing with ATKTerminal

``atkterminal.js`` is a small command-line type program I wrote to quickly interface with AutomataKit firmware, mostly for debugging and testing network hardware.

ATKTerminal uses node's ``readline`` module to parse input from whatever terminal interface you're using (I use MINGW64, which installs with git on windows). It also uses the ``SerialPort`` module to chat over a suitable USB-to-UART bridge (probably the bridge that's integrated in the [atkrouter](https://gitlab.cba.mit.edu/jakeread/atkrouter)). 

To run atkterminal, you'll need to [install node, and then install node's SerialPort module](/reproduction/installing-node-sp-ws.md). To check that the USB-to-UART bridge is running, you can use the ``serialport-list`` command. You should see the port enumerated with **Silicon Labs** somewhere in the name. You can then boot atkterminal with:

``node atkterminal <portname>``

Where ``<portname>`` is the name you found using ``serialport-list`` - on windows this will look something like **COM11** or on unix systems, ``tty/dev1`` etc. 

To use atkterminal, try using the ``help`` command while it's running for a brief cheat sheet. The ``packet`` command is largely what you're after, and is structured like ``packet byte,byte,byte,etc..`` where the second argument is a comma-separated list of 'words' to insert into the packet. 

For example, to write a Step Trapezoid command, I would write ``packet 0,1,ptr,end,trapezoid,1000,100,5000,500,550`` - this will issue a packet with the route of 0,1 and with the key for a trapezoid command, with 1000 steps to make, starting at 100 steps/s, accelerating with 5000 steps/s^2, accelerating for 500 steps and decelerating after 500 steps.

Jake Read's avatar
Jake Read committed
88
89
90
91
92
93
94
95
## Circuit Reference

![sch01](images/atk-phy-schematic-01.png)
![sch01](images/atk-phy-schematic-02.png)

![cir01](images/atk-phy-circuit-01.png)
![cir02](images/atk-phy-circuit-02.png)

96
97
98
99
- Power Pins 12mm Separation ... gnd towards interior of board 

## Next ATK Notes

Jake Read's avatar
Jake Read committed
100
101
102
103
104

## ATK C API

 - pin_init doesn't need PINx_bm field, just use the number, ferchrissake
 - DMA, lights ? speed test ? 
105

Jake Read's avatar
Jake Read committed
106
# Reproducing and Extending Automatakit Work
Jake Read's avatar
1st  
Jake Read committed
107

Jake Read's avatar
Jake Read committed
108
To reproduce Automatakit Circuits and software, see the [automatakit reproduction guide](reproduction)