Table of Contents  (bolded ones are in this project log)

• General terms - the names I've decided to call things
• What's being stored - how the overall state is stored
• Pathfinding - how we find valid paths for each connection
• Controlling the 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

So, I didn't know Python, but it sounded like the easiest way to scrape a webpage with Beautiful Soup. Coming from C, it really makes you appreciate the hardline greybeards that have strong opinions about what the language should and shouldn't be. Because Python is a mess. But I learned it anyway.

What the app actually does

Most of the parsing and stuff is done on the Jumperless itself. Mainly because I wanted it to be relatively app-agnostic, and because I'm way more comfortable with C++. So really all the app is doing is:

• Using BeautifulSoup to scrape the webpage source of the Wokwi project every quarter of a second
• Pulling out the diagram.json section of the page
• Seeing if it's any different from the last diagram.json it pulled
• If so, parses that down into a list of connections
• Sends an 'f' over serial to put the Jumperless in "load preFormatted node list" mode
• Then sends those parsed connections over serial

Here's what the diagram.json looks like

We don't actually care about most of the stuff in that json file, so we just parse out the things that are important. The parsed connections look like this

11-105,
13-105,
13-46,
15-44,
43-100,
100-2,
100-2,
45-25,
38-44,
32-44,
22-24,
20-19,
21-23,

The numbers in the 100 range are special functions, 100 = GND, 103 = 3.3V, 105 = 5V, etc.

There's actually the same parser on the Jumperless itself, which I wrote first and then ported to Python. So you could just paste the whole diagram.json into the serial terminal and the Jumperless will figure it out. The main reason I'm doing parsing on the computer is that the serial buffers can fill up and it makes the updates feel less "snappy".

Other things the app does

When you open the app, it uses pySerial to look at all the things connected to USB. If one of them has Jumperless as the device descriptor, it automatically connects to that one and then moves along to prompting you for the Wokwi project link.

It became annoying to paste the link in every time so now it stores links as a text file and lets you just select from a list if you're opening a project you've used before 

The bridge app also has its own menu accessed by typing "menu", which is useful if you want to switch projects without closing and reopening the app.

I guess it's kinda confusing, because the menu on top is coming directly from the Jumperless, while the bridge app menu is coming from the app itself. Hopefully the indenting and spacing hints at that fact. 

Most of the code in the bridge app is just fighting with pySerial to keep the connection open and not crash when it gets unplugged. Especially when developing on this, I needed it to not crash when I flash new code onto the Jumperless from VScode/PlatformIO. So yeah, that works and it's very convenient.

How I got it to run in a persistent terminal window is a bit of a hack. When you open the app, it actually just opens a bash script that launches the real app

And here are the entire contents of jumperlesswokibridge

#!/bin/bash
# This is the launcher for OSX, this way the app will be opened
# when you double click it from the apps folder
open -n /Applications/jumperlesswokwibridge.app/Contents/MacOS/jumperlesswokwibridge_cli

 jumperlesswokwibridge_cli is where the real app is. The reason I had to do this is typically, when you open an app on a Mac, it just runs a script like this and then immediately closes that window. This is just to get around the closing part.

Packaging

This was kind of a nightmare, at first I was using pyInstaller but it wasn't signing the app it created correctly so macOS would throw a fit. Then I found Platypus and it's amazing. Hella easy to use and it just works. 

I don't use windows much but hopefully whatever I did to package that works too. If you have issues, let me know so I can fix them.

If none of these packaged apps work for you, you can just run the Python code in Thonny. There's a requirements.txt file too so you can get all the dependencies (you might have to remove the library called serial (JSON serialization library), because it uses the same name as pySerial (Serial terminal library), friggin' Python) It seems to have problems IDLE for reasons I don't care to find out.

How does Uri from Wokwi feel about me scraping his site every 0.25 seconds?

I think it's rude to scrape small open source projects like that without asking. So I asked and he says it's chill. If Jumperless gets really popular, we'll have to figure something out if I'm putting some serious load on his hosting. But Wokwi is pretty popular and he's assured me it won't be a burden at this scale.

If you want to look at the code for the app yourself, it's here on GitHub