add some notes on firmware

README.md

@@ -8,7 +8,7 @@ It uses a Distributed Dataflow Programming paradigm: hardware and software objec
 
 ![atkapi](images/machine-with-atkapi.jpg)
 
-# Examples 
+# Machines Made with These Controllers
 
  - [Mother Mother: a Machine Generalist](https://gitlab.cba.mit.edu/jakeread/reich)
  - [*A Machine* for playing *Music for Pieces of Wood* by Steve Reich by Jake Read](https://gitlab.cba.mit.edu/jakeread/reich)
@@ -16,7 +16,7 @@ It uses a Distributed Dataflow Programming paradigm: hardware and software objec
  - [SmallGantries](https://gitlab.cba.mit.edu/jakeread/smallgantries)
  - [ClayStacker](https://gitlab.cba.mit.edu/jakeread/claystack)
 
-## The Network
+# 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.
 
@@ -36,7 +36,7 @@ Bytes between the Length Byte and the *Packet Header End Delimiter* define the r
 
 ![packet typ](/images/apa-networking-diagrams-traversal.png)
 
-## The Endpoints 
+# 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. 
 
@@ -46,6 +46,20 @@ Endpoints are designed to be very simple: they receive minimum viable commands a
  - [ATKBreadBoardBoard](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard)
  - [ATKBLDCDriver](https://gitlab.cba.mit.edu/jakeread/atkbldcdriver)
 
+# The Firmware
+
+So far, the endpoints all have xmega microcontrollers at their heart. In particular, the ```XMEGA256A3U``` : the biggest, baddest xmega. We clock it at 48MHz. That said, this isn't a requirement - any microcontroller with a UART port can play.
+
+Firmware can be found in each board's repository under the ```embedded/``` directory. Build, run and debug via the instructions [here](reproduction/firmware.md), or roll your own toolchain.
+
+[typical main.c](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/main.c)
+
+Packet handling is like this: [uartports](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/uartport.c) handle interrupts that pull incoming data into [ringbuffers](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/ringbuffer.c). These are scanned [with this structure](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/atkport.c) and then handled [with this one](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/atkhandler.c). Global things are kept in [this include file](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard/blob/master/embedded/atkbbb/atkbbb/hardware.h). 
+
+All in, probably there is too much pointing->through->things, as I understand this takes a cycle on each link. 
+
+As for DMA, the XMEGA has only four channels (if I understand correctly) so unless I get my hands dirty doing channel-management, the router isn't going to work (it has 6 ports, plus a usb link). 
+
 # Usage
 
 ## Wiring