README.md 7.32 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
12
13
14
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
15

Jake Read's avatar
Jake Read committed
16
17
18
19
20
21
22
23
24
25
26
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
27

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

## The Endpoints 

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

Jake Read's avatar
Jake Read committed
41
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
42

Jake Read's avatar
Jake Read committed
43
## Interfacing with Mods
Jake Read's avatar
1st  
Jake Read committed
44

Jake Read's avatar
Jake Read committed
45
46
47
48
49
50
51
52
53
[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
54

Jake Read's avatar
Jake Read committed
55
Once this application is open, it should maintain a connection to mods and the serial hardware.
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
66
67
68
69
70
71
72
73
74
75
... 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
76
77
78
79
80
81
82
83
84
## 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)


Jake Read's avatar
Jake Read committed
85
86
87
88
89
90
# 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
91

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