README.md 7.64 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
10
11
# Examples 

 - [*A Machine* for playing *Music for Pieces of Wood* by Steve Reich by Jake Read](https://gitlab.cba.mit.edu/jakeread/reich)
12
13
14
15
 - [Modular, Networked Stepper Motor Control](https://gitlab.cba.mit.edu/jakeread/netsteppers)
  - [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
16

Jake Read's avatar
Jake Read committed
17
## The Network
Jake Read's avatar
1st  
Jake Read committed
18

Jake Read's avatar
Jake Read committed
19
20
21
22
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
23

Jake Read's avatar
Jake Read committed
24
25
26
27
28
29
30
31
32
33
34
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
35

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

## The Endpoints 

Jake Read's avatar
Jake Read committed
40
41
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
42
43
44
45
46
 - [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
47
# Interfacing with AutomataKit
Jake Read's avatar
1st  
Jake Read committed
48

Jake Read's avatar
Jake Read committed
49
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
50

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

Jake Read's avatar
Jake Read committed
53
54
55
56
57
58
59
60
61
[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
62

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

Jake Read's avatar
Jake Read committed
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
... 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
84
85
86
87
88
89
90
91
## 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)

92
93
94
95
96
97
- Power Pins 12mm Separation ... gnd towards interior of board 

## Next ATK Notes

 - final rev change rj12 conn ? change on mkbbb ... 

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

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