README.md 6.98 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
Typically, designing and engineering complex systems requires knowledge across the disciplines of electrical engineering, embedded programming, mechanical design, controls engineering, and interface design. By breaking these components into reconfigurable [software and hardware objects](!/nadya-phd), AutomataKit aims to allow non-experts (and experts) to jump in to higher-level systems design.
Jake Read's avatar
1st  
Jake Read committed
6

Jake Read's avatar
Jake Read committed
7
!DOC - threeset: hardware objects, network topology, software
Jake Read's avatar
1st  
Jake Read committed
8

Jake Read's avatar
Jake Read committed
9
## The Network
Jake Read's avatar
1st  
Jake Read committed
10

Jake Read's avatar
Jake Read committed
11
To make individual motors and sensors modular, AutomataKit endpoints use a port-forwarding, source-routed network. 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
12

Jake Read's avatar
Jake Read committed
13
14
15
16
17
18
19
20
21
22
23
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
24

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

## The Endpoints 

Jake Read's avatar
Jake Read committed
29
30
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
31
32
33
34
35
 - [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
36
# Interfacing with AutomataKit
Jake Read's avatar
1st  
Jake Read committed
37

Jake Read's avatar
Jake Read committed
38
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
39

Jake Read's avatar
Jake Read committed
40
## Interfacing with Mods
Jake Read's avatar
1st  
Jake Read committed
41

Jake Read's avatar
Jake Read committed
42
43
44
45
46
47
48
49
50
[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
51

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

Jake Read's avatar
Jake Read committed
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
... 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.

# Examples 

 - [*A Machine* for playing *Music for Pieces of Wood* by Steve Reich by Jake Read](https://gitlab.cba.mit.edu/jakeread/reich)
 - [Modular, Networked Stepper Motor Controller](https://gitlab.cba.mit.edu/jakeread/netsteppers)

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

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