README.md

# AutomataKit

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. 

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.

!DOC - threeset: hardware objects, network topology, software

## The Network

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. 

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.

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

## The Endpoints 

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)
 - [ATKBLDCDriver](https://gitlab.cba.mit.edu/jakeread/atkbldcdriver)

# Interfacing with AutomataKit

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. 

## Interfacing with Mods

[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.  

Once this application is open, it should maintain a connection to mods and the serial hardware.

... 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

To reproduce Automatakit Circuits and software, see the [automatakit reproduction guide](reproduction)