Commit 9de71512 authored by Jake Read's avatar Jake Read
Browse files

housekeeping to squid

parent 0c216831
# Distributed Dataflow Machine Controllers
# Squid Works: Distributed Dataflow Machine Controllers
**Status**
The project is ongoing. Circuit designs listed here are stable, but softwares are changing.
The project is ongoing. Circuit designs listed here are mostly stable, software is in ongoing development. Lots to do.
## What it Is
The *Distributed Dataflow Machine Controllers* project is a collection of reconfigurable open hardware and software for machine-building, process development, and robotics projects.
The **Squid Works** project is a bundle of modular hardware and software resources for the development of Distributed Dataflow Machine Controllers: a class of controllers that use dataflow programming across network links to orchestrate global control across heterogeneous computing.
It uses a Distributed Dataflow Programming Paradigm: hardware and software objects are all nodes in a graph, executing computing and physical tasks, together!
[RuNDMC](https://gitlab.cba.mit.edu/jakeread/rndmc) serves a development environment for those graphs: and Integrated Development and Operation Environment (IDOE).
This means that *adding and removing hardware to a system is easy, and possible.* It also means that *re-writing machine controllers,* to accept new inputs, or deliver new outputs (material, or feedback) is easy. Machine controllers are transparent: their operating principles are obvious to their users, and so intelligent intervention (and modification!) of controllers is possible. We can re-use algorithms and processes that we have developed across many machine instantiations, and we can build custom systems with less overhead. Digital tools are pliable again (soon), and under our control.
![atkapi](images/machine-with-atkapi.jpg)
This means that *adding and removing hardware to a system is easy, and possible.* It also means that *re-writing machine controllers,* to accept new inputs, or deliver new outputs (material, or feedback) is easy. Machine controllers are transparent: their operating principles are obvious to their users, and so intelligent intervention (and modification!) of controllers is possible. We can re-use algorithms and processes that we have developed across many machine instantiations, and we can build custom systems with less overhead. Tools are pliable again, and under our control.
## Machines Running DDMCs
- [Little Rascal](https://gitlab.cba.mit.edu/jakeread/littlerascal)
- [Mother Mother: a Machine Generalist](https://gitlab.cba.mit.edu/jakeread/mothermother)
- [Small Stress and Strain Machine (uSSM)](https://gitlab.cba.mit.edu/jakeread/ussm)
- [*A Machine* for playing *Music for Pieces of Wood* by Steve Reich by Jake Read](https://gitlab.cba.mit.edu/jakeread/reich)
- [MPVMachine](https://gitlab.cba.mit.edu/jakeread/mpvmachine)
- [SmallGantries](https://gitlab.cba.mit.edu/jakeread/smallgantries)
- [ClayStacker](https://gitlab.cba.mit.edu/jakeread/claystack)
(Most of these machines are built with parametric designs for their constituent components, that project is here: [RCT Gantries](https://gitlab.cba.mit.edu/jakeread/rctgantries)).
# The Endpoints
![endpoints](images/endpoints.jpg)
When I say 'Endpoint' I mean the circuit boards (and computing) we expect to find at the edge of the network that we use to connect each of our modular controllers. I also mean: the modular controllers. These are the circuit boards that you seek.
### Mother Boards
### Contexts
I have started using 'Motherboards' with 'Daughters' - Mother Boards (of which I have only one so far) are home to Computing and Network Hardware: they are the minimum viable package needed to start having a Modular Controller. They feature one 60-pin (with 30 cpu pins connected) 'mezzanine' / 'board-to-board' connector.
[XMEGA Motherboard](https://gitlab.cba.mit.edu/jakeread/motherboard-xmega)
### Daughter Boards
Through the 60-pin mezzanine connector mentioned above, I connect the hardware-that-does-work. These are the gate-drivers, mosfets, sensing elements etc, that you need to actually do modular control.
[Router](https://gitlab.cba.mit.edu/jakeread/daughterboard-router)
[Stepper](https://gitlab.cba.mit.edu/jakeread/daughterboard-stepper)
!TODO migrate doc from BLDC, DC, Ultra, and Breadboard. Add AS5047 JST Conn Board.
!TODO make heating board (also current sensing big current board)
Each of the computers participating in the control of these machines runs a *context* - contexts, while written in different languages and running on different platforms, share a set of messages they can use to describe their internals to one another - and they run the same *execution model* internally. This is the (simple) reconfiguration that allows us to build controllers whose execution can be understood (and modified) cohesively, despite their operation across a network, in physical space.
# The Computing Contexts
[Cuttlefish](https://gitlab.cba.mit.edu/squidworks/cuttlefish), for the browser, also serves visual representations of its own dataflow graphs, as well as dataflow across a network. This allows us to visualize, interact with, and build and edit distributed programs.
Each of the computers participating in the control of these machines runs a *context* - contexts, while written in different languages and running on different platforms, share a set of messages they can use to describe their internals to one another - and they run the same *execution model* internally. This is the (simple) reconfiguration that allows us to build controllers whose execution can be understood (and modified) cohesively, despite their operation across a network, in physical space.
[Nautilus](https://gitlab.cba.mit.edu/squidworks/nautilus), for node.js, can run on servers and on local hardware. This is especially handy when we need to hook up to hardware resources like usb ports, etc. Its internals are directly scraped from cuttlefish.
I call these 'DMCCs' - Distributed Machine Control Contexts. None are ready for use.
[Ponyo](https://gitlab.cba.mit.edu/squidworks/ponyo), the smallest fish (and queen of the sea), runs dataflow graphs on embedded microcontrollers. At the moment this is limited to the ATSAMD51J19, a 120MHz Arm M4F. It connects to nautilus via usb links, and to other fishes via a very-fast-uart link that includes a synchronization line. Ponyo is very much under development.
[Cuttlefish: the Browser DMCC: the IDOE](https://gitlab.cba.mit.edu/jakeread/cuttlefish)
[Nautilus: Node.js DMCC](https://gitlab.cba.mit.edu/jakeread/nautilus)
[XMEGA DMCC (forthcoming)]
### Circuits
# The Network
At the end of the day, current moves through coils, voltages are read and delivered, etc. These machines aren't going to operate themselves (or, ) - so these are the hardware tools we use to make them dance.
To make individual motors and sensors modular, 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 hardware for hardware clock synchronization.
![endpoints](images/endpoints.jpg)
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 [odb](https://gitlab.cba.mit.edu/jakeread/odb) includes one UBS-to-UART Bridge, for very simple interface. [XMEGA Motherboard](https://gitlab.cba.mit.edu/jakeread/motherboard-xmega) and XMEGA DMCC will offer a USB serial link.
[ATSAMD51 Motherboard](https://gitlab.cba.mit.edu/squidworks/motherboard-atsamd51) is a host to Ponyo, boasting a 40-pin (30 IO, GND, 5V and 3V3 lines) GPIO 'port'. This connects to daughter boards;
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.
[Stepper Motor Daughterboard](https://gitlab.cba.mit.edu/squidworks/daughterboard-stepper) uses a TMC262 gate driver to drive two discrete H-Bridges, current chopping excited stepper motor coils. Spins those motors. Includes a home for an AS5047 encoder if I ever find time to close that loop.
### The Packet
[Router Daughterboard](https://gitlab.cba.mit.edu/squidworks/daughterboard-router) adds four (4) very-fast-uart (codename VFP) links to the motherboard, establishing system hubs, etc. These can be chained / etc - there is no graph size limit.
Because our UART hardwares typically operate on bytes, our packets are sets of bytes. Packets are structured like this:
[Power Distribution Boards](https://gitlab.cba.mit.edu/squidworks/pdbs) are handy circuits for bussing power (separate from network) around a machine.
![packet typ](/images/apa-networking-diagrams-packet.png)
**Planned Endpoints** include a DC motor driver and BLDC motor driver, both exist in revisions for earlier architectures. Also including an Ultrasonic driver. Many of these boards are just variations on the h-bridge, so there will be some attempt to anneal towards generic power control for i.e. heating, melting, solenoid switching, etc. Sensing is another topic.
### Port Forwarding and Route Shifting
## Machines Running DDMCs
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.
- [Little Rascal](https://gitlab.cba.mit.edu/jakeread/littlerascal)
- [Mother Mother: a Machine Generalist](https://gitlab.cba.mit.edu/jakeread/mothermother)
- [Small Stress and Strain Machine (uSSM)](https://gitlab.cba.mit.edu/jakeread/ussm)
- [*A Machine* for playing *Music for Pieces of Wood* by Steve Reich by Jake Read](https://gitlab.cba.mit.edu/jakeread/reich)
- [MPVMachine](https://gitlab.cba.mit.edu/jakeread/mpvmachine)
- [SmallGantries](https://gitlab.cba.mit.edu/jakeread/smallgantries)
- [ClayStacker](https://gitlab.cba.mit.edu/jakeread/claystack)
![packet typ](/images/apa-networking-diagrams-traversal.png)
(Most of these machines are built with parametric designs for their constituent components, that project is here: [RCT Gantries](https://gitlab.cba.mit.edu/jakeread/rctgantries)).
# Usage
......@@ -94,25 +64,25 @@ I have a small set of power distribution boards:
I hook these up end-to-end to make blocks of just-the-kind of power splitter, etc, that I want.
The boards should all share a ground, but can run on different voltages of input power. Most will take 24v on two M3 screw-mounts - I use eye terminals soldered to 18ga wire to deliver power.
The boards should all share a ground, but can run on different voltages of input power. Most will take 24v on two M3 screw-mounts - I use eye terminals soldered to 18ga wire to deliver power.
The router can also accept power from a USB device. If you're powering it over USB, *do not* also power it via 24v.
The router can also accept power from a USB device. If you're powering it over USB, *do not* also power it via 24v.
Last thing, don't power your supply on before you go to screw power connections onto the boards. Wire them up, and then switch on.
### Network Cables
### Network Cables
At a bare minimum, you're going to be hooking these things up to power, and to each other (network).
At a bare minimum, you're going to be hooking these things up to power, and to each other (network).
- 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.
- the transmit / receive ports are RS-485 Differential Driven, meaning there is no common gnd connection between boards besides the power bus.
- 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.
- the transmit / receive ports are RS-485 Differential Driven, meaning there is no common gnd connection between boards besides the power bus.
The connectors I use are called 'RJ45' Jacks and Plugs. These are standard for Ethernet, but also 'generally useful'. This is not ethernet, but these *are* RJ45. It's 8 wires, and in our case that's four differential pairs - two duplex lines on each side.
One cool thing about RJ45 is the modularity of the cables. We can use commodity crimping tools to make our own lengths:
- one side cuts, one side strips. use both at the same time to get the right length of stripped wire
- use the '8p' crimp, note the tab direction in the crimp
- pinch! the plug has a plastic tab inside that should come down to meet the wire jacket
- pinch! the plug has a plastic tab inside that should come down to meet the wire jacket
![rj45 video](images/rj45-assembly.mp4)
......@@ -120,13 +90,13 @@ One cool thing about RJ45 is the modularity of the cables. We can use commodity
![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.
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.
Power can be bussed - i.e. we can screw two terminals onto the same stud to make the circuit a 'drop' on the line.
## Network Interface
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.
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)
......@@ -134,6 +104,6 @@ Once you've gotten your hands on / or built some ATK Hardware, you'll need to lo
## [Circuit Reference](reproduction/circuits.md)
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.
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.
Along with this note, there's more detailed explanation in the link above.
\ No newline at end of file
Along with this note, there's more detailed explanation in the link above.
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