Commit 5d06c533 authored by Jake Read's avatar Jake Read
Browse files

doc

parent 1025e06e
......@@ -18,11 +18,23 @@ 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)
# Wiring
At a bare minimum, you're going to be hooking these things up to power, and to each other (network).
- don't forget to check polarity before you power up
- network cables can be made two ways: only one is correct - *rj45 tabs should be on the same side of the ribbon cable* i.e. the cable is a 'straight through' type, not a crossover. this means that tx meets rx, etc.
![rj45](images/rj45-tabs.jpg)
To power the boards, I put M3 'studs' on each PCB. These can handle lots of current, and have a good mechanical connection. To hookup, I solder or crimp eye-terminals onto ~ 18ga - 14ga wire, then screw them down with short M3 Socket Head Screws.
Power can be bussed - i.e. we can screw two terminals onto the same stud to make the circuit a 'drop' on the line.
## 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.
......@@ -46,63 +58,21 @@ Endpoints are designed to be very simple: they receive minimum viable commands a
- [ATKRouter](https://gitlab.cba.mit.edu/jakeread/atkrouter)
- [ATKStepper17](https://gitlab.cba.mit.edu/jakeread/atkstepper17)
- [ATKStepper23](https://gitlab.cba.mit.edu/jakeread/atkstepper23)
- [ATKBreadBoardBoard](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard)
- [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.
## 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)
# Usage
- Power Pins 12mm Separation ... gnd towards interior of board
## Network Interface
## Next ATK Notes
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. For us, this means [RNDMC](https://gitlab.cba.mit.edu/jakeread/rndmc) - a Reconfigurable Numeric Dataflow Machine Controller. For you, it might mean some other Node.js program (some exaple code for a simple version of which is available [here](atkterminal.js)), or Python, etc.
## [Firmware -> XMEGAs](reproduction/firmware.md)
## ATK C API
Once you've gotten your hands on / or built some ATK Hardware, you'll need to load some C Code (firmware!) onto each chip. The link above is a guide for this.
- pin_init doesn't need PINx_bm field, just use the number, ferchrissake
- DMA, lights ? speed test ?
## [Circuit Reference](reproduction/circuits.md)
# Reproducing and Extending Automatakit Work
If you'd like to make your own hardware for the network, I recommend using the [ATKBreadBoardBoard](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard) whose documentation also includes a 'daughter' board starter - this will let you plug some new circuitry right onto the available XMEGA pinouts, and use known-to-work programming, voltage regulation, and network interface hardware.
To reproduce Automatakit Circuits and software, see the [automatakit reproduction guide](reproduction)
\ No newline at end of file
Along with this note, there's more detailed explanation in the link above.
\ No newline at end of file
# AutomataKit Reproduction / Circuit Design and Manufacturing
If you'd like to make your own hardware for the network, I recommend using the [ATKBreadBoardBoard](https://gitlab.cba.mit.edu/jakeread/atkbreadboardboard) whose documentation also includes a 'daughter' board starter - this will let you plug some new circuitry right onto the available XMEGA pinouts, and use known-to-work programming, voltage regulation, and network interface hardware.
![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)
Each AutomataKit project includes circuit schematic and board files, as well as some notes (if I've been feeling verbose) under the /circuit directory, and should include a BOM.
## Manufacturing SMT Boards
Circuit Manufacturing is practically a commodity these days. I use [JLCPCB](https://jlcpcb.com/) in Shenzhen, and [OHS Park](https://oshpark.com/) is popular among the open source community. On both of these websites, you can drop the .zip folder from a projects' /circuit folder into their quoting system and get an estimate for cost. Normally, you can get 5 boards for $10 or so, OHS Park may be more expensive (also more awesome, and purple). Boards typically arrive in one week. I highly recommend also ordering a solder stencil.
To assemble circuits, you'll have to order parts as well, I use [DigiKey](https://www.digikey.com/), which is easy for you because I'll include DigiKey Part Numbers on my BOMs.
For final assembly, I recommend a readthrough of [sparkfun's documentation](https://learn.sparkfun.com/tutorials/electronics-assembly) or [adafruit's documentation](https://learn.adafruit.com/smt-manufacturing?view=all#overview)
Essentially, when boards arrive with a stencil, you can solder-paste squeegee paste onto the boards. While some people use a jig for this, in small volumes it's totally reasonable to do by hand (make sure you get a stencil with a 'framework'). Of course, you can also use a syringe of paste and dot each component off individually, but stencils seem like the way to go.
Then, find an old microscope (or don't, and squint!) and tweezer the components into place. This isn't as hard as you'd think, as the melting solder paste surface-tensions everything into the right alignment.
Now, you'll also need (or want) a reflow oven. I used the [controleo](http://www.whizoo.com/) to convert a toaster oven into a reflow oven. If you or your fab-community is not stoked about investing too much time into this, you can also do some [frying-pan reflow](https://www.youtube.com/watch?v=3drirgNktQg).
# AutomataKit Reproduction
# AutomataKit Reproduction / Firmware Programming
All automatakit works are open source, and while we cannot sell you boards, if you have an interesting application, get in touch to ask about collaborating.
## Circuit Building
Each AutomataKit project includes circuit schematic and board files, as well as some notes (if I've been feeling verbose) under the /circuit directory, and should include a BOM.
Circuit Manufacturing is practically a commodity these days. I use [JLCPCB](https://jlcpcb.com/) in Shenzhen, and [OHS Park](https://oshpark.com/) is popular among the open source community. On both of these websites, you can drop the .zip folder from a projects' /circuit folder into their quoting system and get an estimate for cost. Normally, you can get 5 boards for $10 or so, OHS Park may be more expensive (also more awesome, and purple). Boards typically arrive in one week. I highly recommend also ordering a solder stencil.
To assemble circuits, you'll have to order parts as well, I use [DigiKey](https://www.digikey.com/), which is easy for you because I'll include DigiKey Part Numbers on my BOMs.
For final assembly, I recommend a readthrough of [sparkfun's documentation](https://learn.sparkfun.com/tutorials/electronics-assembly) or [adafruit's documentation](https://learn.adafruit.com/smt-manufacturing?view=all#overview)
Essentially, when boards arrive with a stencil, you can solder-paste squeegee paste onto the boards. While some people use a jig for this, in small volumes it's totally reasonable to do by hand (make sure you get a stencil with a 'framework'). Of course, you can also use a syringe of paste and dot each component off individually, but stencils seem like the way to go.
Then, find an old microscope (or don't, and squint!) and tweezer the components into place. This isn't as hard as you'd think, as the melting solder paste surface-tensions everything into the right alignment.
Now, you'll also need (or want) a reflow oven. I used the [controleo](http://www.whizoo.com/) to convert a toaster oven into a reflow oven. If you or your fab-community is not stoked about investing too much time into this, you can also do some [frying-pan reflow](https://www.youtube.com/watch?v=3drirgNktQg).
## Firmware
## Building Firmware
To build, program and debug firmware, I use Atmel Studio 7. Code for all of the endpoints is kept in their respective repositories, under the embedded/ directory.
......@@ -28,7 +10,7 @@ In Atmel Studio, start a new project, select 'GCC Executable Project' and set th
![atsuo-1](/images/atstudio-01.png)
On the next page, select the Device to be an ATSAMD51J19 (or J18) - this is the microcontroller most of the Machine Kit endpoints run. A J19 is the 512kB version, the J18 is the 256kB version.
On the next page, select the Device to be an ATXMEGA263A3U - this is the microcontroller most of the ATK endpoints run. This image shows a different micro, no worries. **ATXMEGA263A3U**
![atsuo-2](/images/atstudio-02.png)
......@@ -50,6 +32,32 @@ Now we should be ready to build the example:
![atsuo-6](/images/atstudio-06.png)
## Loading Firmware
Now that we're building in ATSUO, we can program the boards. The headers are for the 'PDI' interface, - Programming Data Interface. This is ATMEL Proprietary, boo!
![img](/images/programming.jpg)
We need to power the board up before we can program it. One LED on each board (labelled, if they are, pwr) is just a straight shot connection between +3v3 and GND, so if power on the board is OK, this will light up.
To load a program onto the device, connect the programmer (in this case, I'm using an Atmel ICE) and do Ctrl + Alt + F5, or hit the little 'play' button underneath the 'window' menu item.
If you get an error saying you don't have a tool connected, hit OK and select the Atmel-ICE from the menu that appears. Otherwise, to set up a programming tool in Atmel Studio go to 'Tools -> Device Programming' or right-click on the solution and open the properties. From there you can select a tool in the 'Tool' tab on the left.
\ No newline at end of file
If you get an error saying you don't have a tool connected, hit OK and select the Atmel-ICE from the menu that appears. Otherwise, to set up a programming tool in Atmel Studio go to 'Tools -> Device Programming' or right-click on the solution and open the properties. From there you can select a tool in the 'Tool' tab on the left.
If it programs, you will probably see the 'STL' light start to flash. Good news!
## Circuit Building
Each AutomataKit project includes circuit schematic and board files, as well as some notes (if I've been feeling verbose) under the /circuit directory, and should include a BOM.
Circuit Manufacturing is practically a commodity these days. I use [JLCPCB](https://jlcpcb.com/) in Shenzhen, and [OHS Park](https://oshpark.com/) is popular among the open source community. On both of these websites, you can drop the .zip folder from a projects' /circuit folder into their quoting system and get an estimate for cost. Normally, you can get 5 boards for $10 or so, OHS Park may be more expensive (also more awesome, and purple). Boards typically arrive in one week. I highly recommend also ordering a solder stencil.
To assemble circuits, you'll have to order parts as well, I use [DigiKey](https://www.digikey.com/), which is easy for you because I'll include DigiKey Part Numbers on my BOMs.
For final assembly, I recommend a readthrough of [sparkfun's documentation](https://learn.sparkfun.com/tutorials/electronics-assembly) or [adafruit's documentation](https://learn.adafruit.com/smt-manufacturing?view=all#overview)
Essentially, when boards arrive with a stencil, you can solder-paste squeegee paste onto the boards. While some people use a jig for this, in small volumes it's totally reasonable to do by hand (make sure you get a stencil with a 'framework'). Of course, you can also use a syringe of paste and dot each component off individually, but stencils seem like the way to go.
Then, find an old microscope (or don't, and squint!) and tweezer the components into place. This isn't as hard as you'd think, as the melting solder paste surface-tensions everything into the right alignment.
Now, you'll also need (or want) a reflow oven. I used the [controleo](http://www.whizoo.com/) to convert a toaster oven into a reflow oven. If you or your fab-community is not stoked about investing too much time into this, you can also do some [frying-pan reflow](https://www.youtube.com/watch?v=3drirgNktQg).
# Installing Node.js, WebSocket and SerialPort
To interface over mods, or with atkterminal, you'll need to install node.js, and then the packages serialport and ws (websocket).
## Install Node.js
Node.js is a runtime environment for javascript, so you can write and run js locally. [Download and install it here](https://nodejs.org/en/download/) - right now, I'm running v6.11.3, 8.11.3 should work as well.
To check that node is installed, you can use
``node -v``
## Install Serialport
Node comes with a package controller called 'npm' - node package manager. You can use this to install dependencies for node programs.
Serialport is a package for node that allows it to interact with a hardware serial port.
Navigate to the directory where you'll be running from (so, mods/ to run the *atkbridge* or automatakit/ for *atkterminal*). Do
``npm install serialport``
## Install WS (WebSocket)
WebSockets are very simple web connections. In the *atkbridge* we use one to move data between the browser and local hardware.
To install ws, do
``npm install ws``
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment