I'm going to do a high-level explanation of what the code in the Jumperless is actually doing. There's a lot going on and it's in a bunch of separate files so I think it will be helpful for people who what to understand or improve upon it.
Table of Contents
- General terms - the names I've decided to call things
- What's being stored - how the overall state is stored
- File Parsing - how we fill in those arrays
- Routing - how we find valid paths for each connection
- Controlling the crosspoint switches - how we send that data to the CH446Qs
- LEDs - how we choose unique colors for each net
- The Wokwi bridge app - how we scrape the Wokwi page for updates
This is going to be really long and so I'll be filling out parts as I finish them in no particular order.
## General terms
I've made up terms for things here that may or may not be the formal definition, so I should probably let you know what I chose.
**Breadboard Chips** - This refers to the 8 CH446Q crosspoint switches (labeled A-H) that have their Y pins connected to the breadboard. This excludes Chip L which actually has it's X pins connected to the 4 corners of the board (rows 1, 30, 31 (b1), 60 (b30))
**Special Function Chips** - This refers to the 4 crosspoints (labeled I-L) that connect to everything else; the Nano header, power supplies, DACs, GPIO from the RP2040, etc...
**Nodes** - Also used synonymously with **Row** especially when it's on the breadboard or Nano Header. And end point to a bridge
**Bridges** - Just 2 nodes that should be connected
**Nets** - Groups of nodes and bridges that should all be electrically connected to each other
**Bounce** - Sometimes there won't be an available path directly from one node to another, so in this case it will pick another chip with a free path to the start and end chips and "bounce" through it.
**Paths** - Similar to a **bridge**, except that it contains data for *how* that bridge is connected. So it will have which chips and which X and X pins are needed to make the connection
### Defines
You'll see a lot of these, they're all in JumperlessDefinesRP2040.h. But the point of this whole this is so you don't have to dig through the code, so I'll put the abridged version here:
```
#define CHIP_A 0
...
#define CHIP_L 11
#define t1 1
...
#define t30 30
#define b1 31
...
#define b30 60
#define NANO_D0 70 //these are completely arbitrary
There are a few big arrays of structs that store the overall state of everything. Here are the main ones:
### chipStatus
This stores the actual hardware layout of each of the 12 crosspoint switches, like what is physically connected where and whether that path is being used. In the code it's and array called ch[12] and it's in MatrixStateRP2040.h
In general, I use -1 to mean the path is availale to be connected to something. As the pathfinding algorithm runs, it will fill up xStatus and yStatus with the net they're connected to.
Each path is also stored as an array of structs, this also gets filled out as the pathfinding stuff runs. There are also a couple enums to store the type of path it is, which becomes important for pathfinding because they all are sort of dealt with differently. Note that chip L is kind of a special case because it's kind of the special function chip among special function chips. Most notably, it's Y pins are actually connected to the Y pins on the breadboard chips instead of the X pins like the rest of the special function chips.
This is where it stores all the info about the nets, this is filled in early on in this whole process during input parsing.
```
struct netStruct{
uint8_t number; //nets are uint8_t, nodes are int8_t
const char *name; // human readable "Net 3"
int8_t nodes[MAX_NODES] = {}; //maybe make this smaller and allow nets to just stay connected currently 64x64 is 4 Kb
int8_t bridges[MAX_NODES][2]; //either store them here or in one long array that references the net
int8_t specialFunction = -1; // store #defined number for that special function -1 for regular net
uint8_t intersections[8]; //if this net shares a node with another net, store this here. If it's a regular net, we'll need a function to just merge them into one new net. special functions can intersect though (except Power and Ground), 0x7f is a reserved empty net that nothing and intersect
int8_t doNotIntersectNodes[8]; //if the net tries to share a node with a net that contains any #defined nodes here, it won't connect and throw an error (SUPPLY to GND)
rgbColor color; //color of the net in hex
};
extern struct netStruct net[MAX_NETS];
//The first 8 nets are the Special Function Nets so they're always filled
struct netStruct net[MAX_NETS] = { //these are the special function nets that will always be made
I guess "file" is a bit of a misnomer here, the main way of using this thing right now is via the JumperlessWokwiBridge app and that just sends data over serial where it's directly stored into the **Nets** array. There is support for loading a file using LittleFS but that's not the main way I use this thing anymore because it's slower. But the format is exactly the same.
There are actually 2 indentical file parsers, one in the Wokwi Bridge app and another on the Jumperless, they do the same thing. Really all they do is go through the list formatted with human readable names and replace them with the #defined numbers above. So D0 is replaced with 70 and DAC1_8V is replaced with 107.
This is the *really* tricky part. I probably wrote all this code about 4 times, trashed it and started over from scratch with only the lessons learned from the last attempt.
Earlier versions would add connections one at a time, but you'd end up in weird states because it has no knowledge of what other paths it needs to make room for. So the final version here clears the connections from the last update, takes in all the connections to be made, and finds paths for the whole board every time you add a new wire. All the old connections usually follow the same paths as last time unless they need to be nudged over to make room for some other path, and the actual connection won't be interrupted at all.
Here's the schematic of just the crosspoints, the Nano header, and the breadboard.
If you look closely, you'll see that there generally 2 connections (I'm calling these 2 connections **Lanes** between each breadboard chip, except for the chip that is across from it on the breadboard. And every breadboard chip has one connection to each of the special function chips. The pins on the Nano header has a connection to 2 special function chips (interleaved to make it easier to connect continuous pairs of pins to the breadboard).
Here's the high level outline of what NetsToChipConnections.cpp is doing
- Sorts all the paths by Net
This sort of sets priority, lower net numbers (so all the special function nets) will be picked first and are more likely to have direct connections chosen
- For each path, find the start and end chips
- If there are multiple candidates (Nano header pins will have 2) store both
- If both start and end chips have candidates in common, choose that chip (this would make it a bounce)
- Assign node and path types (BB to BB, NANO to BB, BB to SF, etc...)
- Sort a list of chips from least to most crowded (by how many connections that chip has used)
- Resolve the candidate chips by going down the sorted list of chips and picking the less crowded chip
- Search for a direct path between those 2 chips
- If there isn't one, swap to the other candidate chips and search again
- If one of the nodes is a special function with multiple options swap the nodes with their equivalents and search again
- If there still isn't a direct path, set the altPathNeeded flag and move on
At this point, any paths that have a simple direct connection should be done, now we need to deal with the ones that don't
- Resolve alt paths, if the altPathNeeded flag is set
- Search through all the other chips until you find one that has a direct connection to both the start and end chips
- If one chip is connected to the X inputs and the other the Y inputs, set that connection on chip[2] and x[2] y[2]
- If they're both on X or both on Y, set the sameChip flag and the x[3] or y[3] as -2 to denote that that connection is a bounce and it doesn't matter which pin is chosen, as long as it's available
- Resolve uncommitted hops, anything set as -2 gets a random unconnected pin assigned to it at the very end so it doesn't take up connection space
There's a lot more subltlety to this but if I go into any more detail you might as well just read the code itself. It will all be in the file NetsToChipConnections.cpp, and if you're running it on a Jumperless or just an RP2040, you can set the Chip Connections and Chip Connections Alt debug flags and it will show you everything it's doing in a somewhat nicely formatted way. There are comments in the code but there are a lot of nested array things that can get pretty confusing, if you need help understanding what's going on in a particular function, let me know and I'd be happy to walk you through it.
