Robopenguins

Location Display Map with PCB Art

Sun, 03 May 2026 00:00:00 +0000

I used a free PCB sponsorship as an excuse to build the biggest board I’ve ever designed. I turned it into a living map of my family.

To my great surprise, PCBWay reached out and offered to cover the manufacturing costs for a board in exchange for a mention on this hallowed blog. While I’ve avoided monetizing this blog in any way (including removing analytics), it turns out I’m not incorruptible when presented with an excuse to design a giant PCB. As you’ll probably be able to tell from the rest of the article, PCBWay had no involvement itself in the project or write up beyond agreeing to manufacture it.

I like using constraints as inspiration, and I wanted to build something that took advantage of the PCB medium itself.

All of the designs and source code for this project can be found at: https://github.com/axlan/pcb-map

While I don’t think I rushed the project, I did try to move faster than usual. With a new baby in the house, project time could sometimes feel borrowed, either from my family or from my already limited sleep. Still, making things is important to me, and in its own way, this project became a form of self-care. In some places that tradeoff worked out well. In others, not so much. See the Improvements section for the consequences of moving a little too quickly.

Previous PCB Designs
Brainstorming
High Level Design
Making the PCB
- PCB Design
- PCB Manufacturing
Software
Results
- PCB Solar Light
- Full Application
Improvements
- Hardware
- Software

Previous PCB Designs

As a kid doing hacky electronics projects, having a custom PCB made felt like an unimaginable luxury. It was exciting when I got to college and was able to get a discount on manufacturing a board for my final project (a persistence of vision display). Even then, I still ended up making the second of the two boards the project needed myself using toner transfer and ferric acid copper etching.

More recently, I made a little game handheld that could play snake or track the state of a Magic the Gathering game. Here, I had fun adding some decorative flourishes and got to practicing using a modern KiCad version.

Brainstorming

While I knew I wanted the PCB itself to be the centerpiece, I went through a long list of ideas before settling on one.

I spent some time specifically looking at other PCB art projects. There’s a lot of beautiful stuff out there. One site I found particularly interesting was Boldport. In particular, https://boldport.com/blog/2013/09/the-lifegame.html reminded of my recent wedding project. They actually have a whole design tool for PCB art https://github.com/boldport/pcbmode which I looked into. Unfortunately, it seems like the site and the tool haven’t really been active for a few years.

Another PCB art project that inspired me was https://chaijiaxun.com/blog/pcb-metro-map-build-log/. The author created meticulous transit maps as PCBs with light animations.

These two projects both dealt with illuminating PCB’s from the back. I used them as points of reference as I settled on my own design. The creator of the PCB Metro Map Chai Jia Xun in particular spent a lot of effort on perfecting his approach. He ended up shining light through the via holes in the board, coloring them with paper, and using a printed mask to avoid light leaking between holes.

With my prior art research done, I focused on coming up with my own design.

My default instinct for an interesting display project is always to turn it into a clock. I explored designs that combined static PCB artwork with dynamic elements like LEDs, LCDs, e-ink panels, and seven-segment displays. I considered building a traditional clock, a calendar, and even an orrery. But the more I explored those ideas, the more conventional they felt. I wanted something stranger and more personal.

In the end, the most interesting direction was a display that reflected the daily rhythms of my family in real time.

Of course, this takes inspiration from the “Weasley family clock” from Harry potter. Many people have made beautiful projects recreating the clock, and a few that incorporate the electronics to make it function like in the books as well. To put my own spin on it, I decided to combine the idea with the PCB Metro Map to make the display a map.

High Level Design

First, I had to settle a few basic layout questions:

What geographic area should the map cover?
Should the map be contiguous, or split into multiple regions?
Should it include zoomed-in sections?
How would I indicate which family member was which? Would I need RGB LEDs to create distinct colors?

I also considered an approach where a row of circles along the bottom of the board would call out points of interest like home or school, with lines connecting them back to their locations on the map.

There was also the question of how to light the board. I could either place LEDs on top of the PCB or mount them underneath it. LEDs mounted below the board would need some way for the light to shine through. Either holes through the PCB or regions without copper. The PCB Metro Map project meticulously tested the lighting and tempted me to take one of the more complicated approaches. Chai Jia Xun ended up shining light through via holes in the PCB, coloring them with paper, and using a printed mask to prevent light from leaking between holes.

As I explored lighting options, I also started thinking about the assembly process. I’ve built several projects that required soldering dozens of RGB LEDs (like the Icosahedron Globe and the Pixel Wreath) and it can be both tedious and finicky. Over time, I’ve learned that starting with the right off-the-shelf LED hardware can save an enormous amount of effort.

Since the goal was ultimately to illuminate points on a map, what I really needed was a dense LED grid. It turns out there are plenty of inexpensive RGB LED matrix panels available, and I found 64x32 panels selling for around $30. That was dramatically cheaper (and far less work) than populating the board with individual RGB LEDs.

Once I committed to using an LED matrix, the rest of the design started to come together. I decided to make the largest PCB I could reasonably pair with a 64x32 panel. I included the surrounding hills and water to create a more balanced, square composition, while centering the LED panel on the areas we actually travel through.

After ordering a panel, I found that it looked fine shining through a test PCB without copper or solder mask, which simplified the design considerably.

As usual, I ended up using an ESP32 development board to drive the display.

Making the PCB

PCB Design

All the design files can be found at https://github.com/axlan/pcb-map/tree/master/design.

I usually try to make my projects as automated and repeatable as possible (often to a fault). I’ll spend far more time building tooling and infrastructure than it would take to do a one-off task manually. For the map artwork, though, I gave myself permission to just wing it and focus on getting the design finished as directly as possible.

I initially considered using the Boldport PCBmodE tool, but it appeared to be unmaintained and seemed like it would come with a steep learning curve. Instead, I decided to try the image converter now built into KiCad.

Since the KiCad converter only works with bitmap images (JPGs, PNGs, and similar formats), I didn’t need to worry about building everything as vector artwork.

I also explored more abstract map styles, including this design from Archie’s Press:

In the end, though, I decided to stick with a normal geographic map.

I was surprised by how difficult it was to find a good source for the map imagery. If I had wanted to be truly meticulous, there are probably mapping APIs that expose the underlying geographic features directly so you can render everything exactly how you want. Instead, I mainly needed an online map tool where labels (road names, points of interest, etc.) could be disabled cleanly.

Eventually, I found Snazzy Maps, which was almost exactly what I was looking for. It provides a JSON-based styling interface with fairly fine-grained control over map appearance. I started from the existing Assassin’s Creed IV style and disabled railroads and local streets.

The site includes an export button, but it only supports images up to 1000x1000 pixels. Instead, I rendered the map at high resolution and captured screenshots manually.

Next I had to decide what map features I wanted to have on which PCB layers.

PCBs normally have these layers on both the front and back of the board, though additional copper layers can also be sandwiched internally. Since I planned to shine light through the PCB, I realized I could also use the back-side layers to block or dim light without affecting the visible front surface. Vias (the plated holes that connect copper layers together) could even be used to channel light directly through the board.

In the end, I decided to keep things simple:

Solder mask for water
Exposed copper for streets
Bare PCB substrate for land

To make the board translucent, I removed the copper and solder mask from the entire back side of the PCB. Once I started adding electronics, though, I limited this treatment to the land areas so that I could still place conventional components in the “water” regions.

At that point, I just needed to generate images for each PCB layer I wanted to import into KiCad. Here was the process I ended up using:

Using Snazzy Maps, I captured a screenshot of the region I wanted to use for the map.
Since I had decided on a final board size of 240x320 mm, I cropped the image to match the correct aspect ratio.
I created a reference layer with a 160x320 mm rectangle to verify that the LED matrix panel would fully cover the parts of the map I wanted illuminated.
Using GIMP, I used the “select by color” tool to separate the image into independent layers for water, land+roads, and roads. I made each layer a solid opaque color.
The road layer ended up looking heavily pixelated and didn’t import cleanly into the KiCad image converter. To fix this, I copied the roads image into Inkscape and used the “trace bitmap” feature to generate a smoothed vector version of the roads. I then re-exported this at a higher resolution and brought it back into GIMP to create cleaner road geometry.
I exported PNG images for both the land+roads layer and the roads layer. I also created a horizontally flipped version of the land+roads image for use on the back side of the PCB.
Using the KiCad image converter, I imported the PNGs into the PCB design at a final scale of 240x320 mm:
1. The roads became a top-side copper layer.
2. The land+roads image became a top-side solder mask layer.
3. The flipped land+roads image became a bottom-side solder mask layer.

At that point, I had a PCB file containing the complete map artwork.

Separately, I created another KiCad project for the actual electronics: the ESP32 development board, LED matrix interface, and power connectors. After verifying the footprints and laying out the PCB connections, I copied the completed electronics layout into the map PCB project.

At one point I considered trying to keep the board single-sided, so I intentionally selected ESP32 GPIO pins that minimized routing complexity and avoided needing additional copper layers.

When I finally ran the design rule checker (DRC), I discovered a few clearance violations near the board edges, so I added roughly half a millimeter of additional margin around the design. It also had issues with the single sided board, so I left it two sided.

One feature I especially appreciated during this process was KiCad’s 3D PCB viewer, which made it easy to preview how the finished board would actually look before sending it off for manufacturing.

PCB Manufacturing

I was curious how PCBWay would react to a giant decorative PCB, so I was pretty eager to get the design into their system and see what happened.

Their upload and ordering interface was straightforward enough. As someone with hobbyist PCB experience I found the process fairly painless. While exploring the manufacturing options, I was briefly tempted by the “hard gold” surface finish. Since my design intentionally exposed a large amount of copper, this would have effectively plated huge portions of the board in gold. Unfortunately, a 30-micron gold finish increased the estimated price from roughly $120 to $572. I also suspected the standard silver finish would probably look better and be less likely to be rejected, so I stuck with that.

One feature I especially appreciated was the ability to preview the board after uploading the design files. It made it easy to sanity-check that the solder mask color and surface finish matched the aesthetic I had in mind.

Once the board was submitted, I had to wait for the design review process. I was curious how this would go, and sure enough, the design was flagged for confirmation:

Hi,

Thanks for your inquiry, here is a question for project No.W1047802AS4C1_map_board.zip

Pls find the attached pic and confirm whether the design is normal or not?

Your timely response would be greatly appreciated!

The attached image was the entire copper layer of the board.

I replied:

This is the intended layout for the top copper layer. The large section is there for appearances only to make the board look like a metal map.

Thanks for double checking.

which got the reply:

Thanks for your reply!

W1047802AS4C1_map_board has been approved now, the PCB price is $126.17, with an estimated lead time of 3–4 days, pls kindly login to check the details and proceed to checkout if everything is in order. :D

Honestly, that felt like the right response. A board that is mostly decorative and only partially functional seems worth double-checking before fabrication, and it was easy enough to clarify the intent. I am curious what the exchange would have looked like if I hadn’t cleaned up the design rule check (DRC) errors before submitting it.

From there, everything went smoothly. PCBWay covered the manufacturing and shipping costs, though I still had to deal with import tariffs. In practice, that just meant FedEx sent me an invoice after delivery for a 31% tariff, plus a $15 processing fee for handling the import payment on my behalf.

Software

From the start, I knew I wanted to keep the panel firmware as simple and generic as possible. Ideally, I could reuse it for other display projects in the future. The device would receive commands over MQTT to drive all dynamic behavior.

This also meant I would need to write a separate host-side application to run on a PC, responsible for querying family locations and translating that data into commands sent to the device.

LED Matrix Driver

I bought the LED matrix panel with the hope that controlling it wouldn’t be too much of a pain. From what I can tell, HUB75 is an informal standard that many LED panels implement https://learn.lushaylabs.com/led-panel-hub75/. Since it’s informal, there are many small variations that need to be validated when buying a new model.

The matrix display that this project was tested with is the: Waveshare RGB Full-Color LED Matrix Panel, 5mm Pitch, 64x32 Pixels

It was labeled as P5(2121)-3264-16S-M5 (32x64 1/16 scan) and used the RUC7258D, SM16208SJ, and MW245BC control chips.

Like most embedded projects, finding the “best” library to use is a bit of a pain. It seems many owe their ancestry to the Adafruit graphics library, which has many descendants targeting different platforms and display technologies. After some research, I decided that the https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA library seemed to be the most capable and compatible option for the ESP32.

I wired up the panel directly to an ESP32 and tried the example script. The display sort of worked, but everything was slightly glitchy or shifted. Reading the control library README, I tried changing the clock phase setting, and just like that the panel was working correctly.

I did a bit more experimenting and eventually found other display artifacts, but these went away when I switched from jumper cables to my custom PCB. As it turns out, they’re not kidding when they say these boards are sensitive to needing a beefy power supply and short cables. The signal integrity issues might also be partly due to the panel expecting 5V signals while the ESP32 outputs 3.3V.

When my custom PCB arrived, I was delighted that the connection between the ESP32 and the LED panel worked without issue. It’s not that the layout is particularly complicated, but there’s a lot of room for something to get flipped left/right or top/bottom.

As I developed my application, I found the panel library mostly worked as expected and was pretty solid. When I started having issues with flickering, I enabled the library’s built-in double buffering, which fixed the issue.

With the driver done, I needed to implement the display control interface. I didn’t approach this particularly systematically and mostly just added features as needed. I ended up with two basic ways to draw things on the display.

First, I added an interface for drawing a background image. This is simply sending a bitmap of pixel colors for the whole panel to be statically displayed when nothing else overwrites them. When I started testing this, I realized that the MQTT library I was using had a 256-byte message limit. Since I didn’t want to rely on sending 4 KB (64x32x2 bytes, where 2 bytes per pixel is the RGB565 color scheme) messages, I set up the interface to update the background row by row (128-byte payloads).

I also wanted to support drawing elements that could be updated independently and could have some dynamic behaviors (e.g., pulsing). I created a concept of sprites indexed by a name identifier. The only sprite type I implemented was a pixel sprite that could oscillate between two colors. This also enabled the panel to periodically cycle between sprites sharing the same position, to handle the case where multiple people were at the same address and I wanted both to appear on the map. These sprites could then be updated by future commands referencing their name. There are other sprite types I could have added (such as driving routes) but I decided not to add complexity to the firmware until it was actually needed.

Network Discover Provisioning and Configuration

One of the first things I focused on when building out the firmware was making the network configuration completely reliable. In previous projects, I’d taken a variety of approaches to handling Wi-Fi credentials and MQTT configuration, but this time I wanted something more polished and dependable. I put extra effort into making the setup process stable and user-friendly so that, if I ever wanted to duplicate the project or revisit it in the future, getting it running again would be straightforward.

Setting or updating Wi-Fi credentials requires a side channel to configure the device before it has network access. For the first time, I read through the Espressif provisioning documentation. The Espressif unified provisioning libraries provide a robust way to provision a device over Bluetooth or an ad-hoc Wi-Fi access point. The downside is that the library is fairly complex and requires the host machine to either support Bluetooth or manually connect to the ad-hoc network.

There was also a library called SmartConfig, which uses clever techniques to decode network credentials from the length of encrypted packets by monitoring Wi-Fi traffic. Unfortunately, the documentation suggested this approach may not work consistently across all Wi-Fi drivers.

I ultimately fell back on the WiFiManager library, which I’ve used in previous projects. It still requires manually connecting to an ad-hoc Wi-Fi network, but it creates a captive portal that makes entering credentials straightforward.

To streamline finding the device on the network, I spent some time better understanding how mDNS works. On my Linux system, at least, it let me use the device’s local hostname directly instead of tracking down its assigned IP address.

Once the device is connected and configured, all communication happens over MQTT. This gives me flexibility in choosing between a local or remote broker, handling authentication, and avoiding a lot of lower-level protocol edge cases. Even after the device was online, though, I still needed a way to configure the MQTT host and authentication settings.

I ended up creating a simple UDP command packet format to configure all the parameters used for MQTT authentication. I spent a fair amount of time working through MQTT TLS certificate management before ultimately disabling certificate validation.

Supporting arbitrary brokers securely would have also required transmitting the root certificate through this configuration interface. The added complexity of managing certificates didn’t feel worth the relatively small security benefit of guarding against potential man-in-the-middle attacks for a project at this scale. For a commercial device the calculus would be different. I’d likely target a specific broker, embed the root certificate directly in the firmware, and skip this level of configurability entirely.

I’ll go into the details of how I tried to automate device setup in the Python controls find-devices section.

Simulator

See https://github.com/axlan/pcb-map/tree/master/firmware/simulation for the simulator source code.

While updating the firmware and testing on the device isn’t that painful, I wanted to make development as quick as possible. Since the interface to the display is so basic, it was relatively easy to create a small CMake application to simulate it locally.

I primarily wanted to test the MQTT handling and display logic, so I included the relevant source files from the firmware in my simulator build. To do this I created dummy header files that mocked out any Arduino or driver calls to allow them to compile. I used the SFML graphics library to render my simulated panel overlaid on a transparent map image.

Python Controls

I made two Python tools for interacting with the board. I continue to mostly design Python projects with uv in mind, and here I really tried to get good command-line ergonomics. I used the Typer library for the first time to handle parsing command-line arguments. It worked out well once I learned enough to cover my use cases. One feature I was happy to find was that you can map command-line arguments to environment variables, which makes it easy to set credentials without typing them in each time and without any extra code.

device-setup

The goal of this tool was to eliminate the tedious process of setting up an IoT device. Things like not knowing whether it’s connected to Wi-Fi, or having to log into the router to find it on the network. The states it detects and configures are:

control-server

Once the device is fully configured, further operation is controlled over MQTT. This tool handles that control for various tests and applications.

The main application is display-shared-locations. It loads the user’s and their friends’ positions to draw on the map, and checks calendar events for positions to draw routes to.

For testing purposes I also created a way to specify changing user positions and routes as a JSON file.

One issue I hit while developing this interface is that there’s no great way to access your location data over an API from Google. Google tracks your position and lets you share it with friends through Google Maps, but there’s no official way to access this data outside the app or website. There is a Python library that handles parsing the data, but it requires session cookies, which can be fragile for a long-running server.

I could use a side channel to report positions, but I wanted to avoid requiring my family to run any special software on their phones. Both for simplicity and for privacy.

Position data could also come from other services. If my kids get some sort of non-phone location beacon (like an AirTag), I could potentially integrate that as well, since it would just be an update to the Python server.

Drawing the routes was a bit more involved. I initially used an API from OpenRouteService since its free tier would have covered my usage, but it returned incorrect positions for the test addresses I tried. I switched to the Google Maps routing API, which requires a Google Cloud account but should also be effectively free.

Converting user locations to panel coordinates was a fairly straightforward mapping from latitude/longitude to the panel’s X/Y. Drawing routes was more complex: I receive the route as a series of line segments and need to map these onto the grid. The algorithm I used could almost certainly be improved, but I got something quick and dirty working.

I decided to add route drawing later in the process. Rather than adding a new sprite type for routes, I found it easier to draw them as part of the background image and manage them from the server side.

Once I had everything working, I spent some time hardening the application so it would behave more reliably as a long-running server process. I added MQTT status reporting so I could monitor whether the hacky cookie sharing mechanism needed to be refreshed or if some other unexpected failure had occurred.

To run it on my server, I Dockerized the application and wrote scripts to update the authentication credentials as needed. I also set up Uptime Kuma to monitor the service and alert me if anything failed.

Results

I ended up with two complementary projects: the PCB, which is beautiful on its own, and the position display server and firmware for the LED matrix. Using a PCB for the static map is a great aesthetic touch, but the whole thing would be completely functional with a printed paper map instead.

PCB Solar Light

Since the minimum order for a custom PCB was 5, I had four extra boards to work with. They seemed like they’d make nice gifts as-is, but I still wanted to give them some basic functionality. Since I wasn’t expecting people to run a server to display locations, I came up with the idea of fitting the guts of a solar garden light onto a board so it would glow at night.

Full Application

This demo shows a simulated scenario where Joe is driving to Sue’s house. Once he arrives, the map alternates between them:

Here’s some samples of uploading background images to the display:

In the end I got everything I wanted working, but in the next section I’ll go into some of the many improvements I could make.

All designs and code for this project can be found at: https://github.com/axlan/pcb-map

Improvements

Hardware

Choose a more common ESP32/ESP8266 footprint - The particular board I had on hand was one I got from AliExpress years ago. Its pinout wasn’t very standardized. Since I’m using it on a printed board, it probably would have been worth targeting a better-documented dev board footprint.
Select a thinner PCB - One of the PCBWay options I left at the default was board thickness. The lights are visible through the PCB, but they’re a little dimmer in daylight than I’d like. I think this would have been simply addressed by ordering a thinner board.
Avoid blocking the ESP32 antenna - I laid out the connectors without much thought. In hindsight, I wouldn’t have placed the ESP32 on the back behind a solid copper layer. It still works, but the Wi-Fi signal strength is much worse than it could be, and it probably wouldn’t work at all if the device weren’t fairly close to the router.
Avoid blocking the ESP32 USB - A similar mistake was placing the ESP32 too close to the LED matrix HUB75 connector. The USB and the display can’t be connected simultaneously since they block each other. I originally didn’t see this as a problem since I was planning on using a separate power connector, but once I was using the board I realized I could have used this port with data-only cables or high-power USB-C supplies.
Add more silkscreen info - I didn’t include any useful silkscreen on the board. I should have at least labeled the orientation of each connector to make plugging them in easier.

Software

Support special location indicators - This was an idea for better indicating when users are at known places like home or school. Originally I had thought I could shine LEDs under the “water” sections of the map with arrows pointing to their locations. Since the copper makes those sections opaque, I could instead add LEDs to the top of the board, or integrate them into the legend somehow.
Add Event Indicators - In addition to showing the route to events, I could have some indicator that an event start time is coming.

Making a Turtle Bot 2: Making a Dash Robot into a Turtle

Tue, 03 Mar 2026 00:00:00 +0000

Since a capable Dash robot fell into my lap, I could skip ahead and build a full child friendly turtle bot game. I went for simplicity and built the control logic and GUI in Python.

This completes the game idea I described in:

Making a Turtle Bot 1: Hacking a Mint Cleaner

and uses the interface I built in:

Reverse Engineering the Dash Learning Robot

Here’s a basic demo of the bot along with part of the GUI window:

and a longer demo of using cards to plan out a path to the goal:

The full source can be found in: https://github.com/axlan/dash-turtle-game

Turning the Dash into a Turtle

My first goal was to use the interface I made in https://github.com/axlan/WonderPy to send commands and get the sensor data I needed to implement the game.

Using the interface for real, I quickly found tons of bugs. Most were simple typos, but quite a few were also around how I wrapped the asyncio BLE library so it could be used from a traditional threaded application. There’s lots of nuance especially around graceful shutdown and error handling that made this a real pain to get right. I understand why many libraries I’ve seen create separate implementations for these use cases.

The bulk of this initial work involved getting the robot to follow the game grid. Getting the bot to turn in place and move forward was extremely simple. The difficulty was aligning these movements to the game board and keeping it aligned.

After experimenting with the Dash robot, I decided that inertial positioning (the robot’s estimate based on accelerometer, gyro, and wheel sensors) was good enough for this game. I had successfully tested using AprilTags to generate absolute position from markers built into the game board. However, this would have required a camera to monitor the game space, which seemed cumbersome for something I wanted to set up quickly. I also considered using light sensors to detect lines or features under the robot, but this was no longer an option since I was using a stock robot without these sensors. While drift in the inertial measurements is easy to notice, it rarely was enough for the bot to be off by enough to be off the grid in the dozen or so steps needed to solve the maze.

One weird thing I found in testing was that the Dash robot would occasionally turn on a television if pointed directly at it. At first it was like a poltergeist. I believe this relates to its IR beacon feature, where robots identify others nearby by decoding data sent from IR transceivers. I had also considered using this for absolute positioning, but that would have required significant reverse engineering effort and seemed unnecessary.

The Dash robot’s interface reports its current pose and includes a “pose” command. This lets you specify x and y positions in centimeters along with an orientation it should move to. This meant all I needed to do was map the orientation and x, y positions from the robot’s coordinate system to the game board.

Since I started planning this turtle game, I’d been thinking about what would make a good game board. I looked into buying a giant checkerboard or a picnic table cover. In the end, the most cost effective items I found were puzzle piece foam mats meant for gyms or children’s playrooms.

Since I wasn’t planning on detecting the mat edges for positioning, I got an alphabet mat to make it easier to map the mat tiles to the virtual game board.

The Dash robot’s coordinate system is described in https://github.com/playi/WonderPy/blob/master/doc/WonderPy.md#coordinate-systems. Each time the robot boots, it initializes its pose to {"x"=0, "y"=0, "degrees"=0}. It also has additional commands to reset its coordinates, but I didn’t reverse engineer that part of the command interface since I could compensate on the host side. To simplify the controller logic, I created a series of functions to translate, rotate, and scale the pose reported by the robot to a coordinate on the game board where each tile is one unit long.

def get_pose(self):
    # Remove start offset so robot starts at 0,0
    bot_x = self.sensors.x - self.start_pose_robot.x
    bot_y = self.sensors.y - self.start_pose_robot.y
    # Apply rotation so robot starts at correct angle
    # -90 to handle turtle bot coordinates face in +y direction
    bot_x, bot_y = rotate_point(bot_x, bot_y, self.theta_offset - 90)
    return TurtlePose(
        bot_x * self.pos_scale + self.start_pose_virtual.x,
        bot_y * self.pos_scale + self.start_pose_virtual.y,
        normalize_ang360(self.sensors.degrees + self.theta_offset),
    )

Once all the bugs were worked out, this provided a solid starting point for building the game controller.

Making the GUI and Adding Features

One of the reasons I explored ROS in my previous turtle bot iteration was that it provides a very modular way of connecting a robot to control and visualization systems. Hypothetically, the controls and game board idea I had could all be implemented as ROS packages. In practice, however, I found that the complexity of ROS added significant overhead when using it as the glue for my project. My use case was so simple that most of what ROS brought to the table was overkill. With that in mind, I decided to implement the game in the way I found most expedient and not worry about building it out of modular components that could be reused in other projects.

I went with PyGame for the GUI since it’s simple and I’d used it before. I added another transform to go back and forth between robot coordinates, game map coordinates, and pixels on the PyGame map. To command the robot, I used the arrow keys reported by PyGame.

The main challenge was setting up the threading strategy to handle the robot and GUI. I went from one big function to separating components more logically into classes.

I realized this would be a great application for the Giving a Toy Controller WiFi I had made. I added an MQTT client to supplement keyboard commands with button presses from the toy controller. I figured I could also wire in the turtle board game controls over MQTT when I got to it.

At this point, adding features was straightforward:

GUI shows positioning estimate and can queue up a sequence of commands to execute when connected.
Simulation mode allows testing without a Dash bot connected.
IR distance sensors provide basic collision detection.
The front, right, and left LEDs match the colors of the controller buttons to help the player understand how clockwise and counterclockwise turns correspond to the bot’s relative position.
The light on top of the bot indicates if it’s busy. When sending commands in real time, it will sigh if a new command is sent while executing the previous one.

I went on a little side quest when I was trying to get the robot’s sound effects working. To get the Dash to play sound, the command specifies a sound effects file name on the bot. A lot of the files in the original library were no longer working. I downloaded the APK and extracted the files with apktool. This would have been another avenue for reverse engineering the interface since it had the java implementation including debug information. It also had the robot’s firmware with the actual audio files that got compiled in.

Making the NFC Card Reader

The code for the reader can be found at:

https://github.com/axlan/dash-turtle-game/tree/master/reader_firmware

To “play” the cards from the original turtle game as commands to the robot, I decided the easiest approach was to stick them on NFC cards. I got 40 cards for less than $15.

While I could have used a phone as a reader, I’ve had bad luck running servers on phones. Instead, I made a standalone reader by connecting an Elechouse PN532 NFC module to an ESP32. For simplicity, I used the high speed UART connection to the ESP32’s serial2 pins.

I did a quick test with the Elechouse library https://github.com/elechouse/PN532. This library was somewhat annoying since it isn’t packaged as a library that can easily be pulled into a PlatformIO or Espressif project. Even including it as a submodule was cumbersome since I needed to delete code for the extra interfaces. Once I got it working, though, it worked great.

I decided to try a better packaged Adafruit library: https://github.com/adafruit/Adafruit-PN532. This library required a much deeper understanding of NFC cards. I eventually got it working, but it performed significantly worse than the Elechouse library. I ended up switching back and just adding the files I needed to my repo.

I think the Elechouse library was just packaging together a bunch of libraries as reference in https://github.com/Seeed-Studio/PN532:

This library is based on Adafruit_NFCShield_I2C. Seeed Studio rewrite the library to make it easy to support different interfaces and platforms. @Don writes the NDEF library to make it more easy to use. @JiapengLi adds HSU interface. @awieser adds card emulation function.

but I didn’t bother going back to test this.

To integrate the cards into the game, I used the “NFC Tools” app on my phone to add the card identifier (UP, LEFT, RIGHT, etc.) as a text record on each card. This was sent along with the card UID as JSON to my MQTT server, where the turtle game could listen for them.

Once the firmware was working, I just stuck the electronics in a box and connected a USB battery.

Conclusion

While I ended up adding a ton of features, this all came together pretty quickly. The final product is fairly solid and has mostly held up to use by a four year old. The inertial positioning is the biggest limitation. Probably more because initial conditions need to be set manually than due to drift during the run.

If I wanted to make this more standalone, I could require set start and goal points on the mat. For feedback, I could probably create a dedicated display attached to a Raspberry Pi or ESP32.

I’m still considering finishing the vacuum cleaner robot I started or implementing an absolute positioning system, but those are shelved for another day.

As for using this as an actual toy, my daughter thought it was neat, but it was just another toy in toy room. She’s not really old enough to plan out the robot’s course and I think I’d need to add some story elements to keep her engaged. The actual software designed for the Dash is much more polished, but seems like it would be more suitable for an 8+ year old. Rather than being a toy I think she’d learn from directly, I hope she gets something on seeing me make something an using it to play with her.

New Baby, New Umbilical Art

Sun, 01 Mar 2026 00:00:00 +0000

Our second child was born! So we had to make a new weird shrine with the umbilical cord so we’re not playing favorites.

When our daughter was born we made a shrine in reference to the artifacts you find in the game Bloodborne (see: baby projects).

My wife and I had recently played the game “Chants of Sennaar”, so we decided to make the shrine using glyphs from that game.

The game focusing on decoding a series of languages from glyphs by finding how the glyphs are written and spoken while solving puzzles to progress through a Tower of Babel.

We made a message saying “We love you little XXX” where we wrote out his name using a somewhat creative interpretation of the alchemist language:

https://chantsofsennaar.miraheze.org/wiki/Alchemist_(language)

building on the fan made periodic table.

As a fun update, I got a response from the person who originally made the periodic tables when I posted this on the Chants of Sennaar Reddit:

Oh wow, never imagined this could be an indirect outcome of my going a bit mad and making a periodic table a couple years ago! Many congratulations on your new arrival, and the memento looks beautiful.

A little behind-the-scenes on it - the silicon symbol technically breaks the rules of Alchemist glyphs as the circle on the right ought to be connected to the main symbol, but it looked unsatisfying like that and rules are inevitably broken now and again in languages. It’s meant to be an abstract representation of a logic gate (with the dot as a 0 and circle as a 1), given what I associate with silicon, although that logic probably doesn’t make sense in-universe.

Oxygen is far more straightforward - it’s a nonmetal that incorporates the cross symbol seen in some living things like Plant and Monster. A particularly suitable glyph for a piece celebrating a new life.

Congratulations again!

Reverse Engineering the Dash Learning Robot

Sun, 08 Feb 2026 00:00:00 +0000

I brushed up on my Ghidra to add to the open source interface for a Dash robot I found at Goodwill. Finally, another thrift store project!

Since Making a Turtle Bot 1: Hacking a Mint Cleaner, I’ve been keeping an eye out for other cheap robotic vacuums to play with. On a recent trip, I noticed a decent looking robot in the toy section for $15 https://store.makewonder.com/products/dash. A quick search showed the company was still in business and there was a repo that at least claimed to offer Python controls. I figured worse case, I could replace the controller and use it for its motors.

If you just want to use the library I updated for controlling the Dash in Python, see: https://github.com/axlan/WonderPy

Dash Robot Used as Intended

First, I gave it a spin using it as intended. It is meant to be controlled through an app and has a pretty nice remote control and visual programming language. Everything seemed to be working and already had a pretty neat toy out of my purchase.

Here’s an Overview of its features:

Commercial Educational Robot Toys

I can’t really say where the Dash falls in the ranking of learning robot toys. Its ecosystem seems fine, and the bot is cute while still having a bunch of features. On the other hand, I have a strong bias toward wanting something that’s an open system.

They are more likely to teach generalizable skills
They can more easily outlive their parent company
Their incentives are better aligned to be good rather than sticky
They’re more likely to be interoperable with other systems widening the play space

That is how I justify it anyway.

The Official Python Interface

Much to their credit, the MakeWonder company released an official Python library.

https://github.com/playi/WonderPy

Rather than being cutesy, or a stripped down basic interface, it breaks out all the controls and sensors in a reasonable way. It even covers overlapping functionality to expose high level features like getting a position estimate and moving to a certain pose as well as low level features like motor control and accelerometer readings.

Here’s the documentation of the features it covers: https://github.com/playi/WonderPy/blob/master/doc/WonderPy.md

They even have some handy diagrams for the coordinate system: https://github.com/playi/WonderPy/blob/master/doc/WonderPy.md#coordinate-systems

This would more than cover all the features I wanted for my turtle bot. The catch is that it only works in Python 2 on x86 OSX.

Porting the Library

I found a few efforts to port the library to Python 3 and other OSs.

https://github.com/IlyaSukhanov/morseapi - As far as I can tell, this was the only real reverse engineering effort. I hadn’t looked at it in detail until writing this article, since I figured the forks would have been mostly additive. As it turned out, this project has more functionality then its “children” and even had a partial implementation of the command I was interested in.
https://github.com/havnfun/python-dash-robot - Is built on the previous project. It adds Python 3 compatibility along with dropping a bunch of the previously supported commands and sensors
https://github.com/mewmix/bleak-dash - Is built on the previous projects. Switches the BlueTooth support library and adds back the some of the sensor decoding

Since I assumed the latest project would be the most complete, I used it as my starting point. In testing, the movement commands worked, but even doing something as simple as turning 90 degrees wasn’t easy to achieve. Instead of using the high level pose command like the original library, it used low level motor control in a way that didn’t seem well tuned.

To illustrate here’s the evolution of the turning command:

# https://github.com/playi/WonderPy
# This uses the robot's pose command to turn the robot in place.
def do_turn(self, deg, speed_deg_s):
    """
    This is a somewhat naive drive command because it moves relative to the robot's measured position,
    which means error can accumulate.
    """
    self.do_pose(0, 0, deg, abs(float(deg)) / float(speed_deg_s), True,
                  WWRobotConstants.WWPoseMode.WW_POSE_MODE_RELATIVE_MEASURED,
                  WWRobotConstants.WWPoseDirection.WW_POSE_DIRECTION_INFERRED,
                  False)


# https://github.com/IlyaSukhanov/morseapi
# This still uses the pose command, but the command no longer actually maps to the full pose.
# It appears that only relative movements are supported and some of the other flags are missing.
def turn(self, degrees, speed_dps=(360/2.094)):
    """
    Turn Dash specified distance.

    This is a blocking call.

    :param degrees: How many degrees to turn.
    Positive values spin clockwise and negative counter-clockwise.
    :param speed: Speed to turn at, in degrees/second
    """
    if abs(degrees) > 360:
        raise NotImplementedError("Cannot turn more than one rotation per move")
    if degrees:
        seconds = abs(degrees/speed_dps)

        # def _get_move_byte_array(distance_mm=0, degrees=0, seconds=1.0, eight_byte=0x80):
        byte_array = _get_move_byte_array(degrees=degrees, seconds=seconds)
        self.command("move", byte_array)
        # self.sleep does not work and api says not to use time.sleep...
        time.sleep(seconds)


# https://github.com/mewmix/bleak-dash
# This is the worst of all since it uses the drive command to try to spin the
# wheels open-loop, and doesn't appear to make logical sense since the speed_dps
# used to compute duration isn't related to the actual speed applied to the motors.
async def turn(self, degrees, speed_dps=360/2.094):
    """
    Turns the robot a specific number of degrees at a certain speed.
    This method simplifies the operation to a 'spin' command for a calculated duration.
    Adjust this method based on your robot's capabilities.
    """
    if abs(degrees) > 360:
        print("Cannot turn more than one rotation per move")
        return
    
    # Assuming positive degrees for clockwise, negative for counter-clockwise
    speed = 200 if degrees > 0 else -200
    # Calculate duration based on speed and degrees to turn
    duration = abs(degrees / speed_dps)
    speed = max(-2048, speed)
    speed = min(2048, speed)
    if speed < 0:
        speed = 0x8000 + abs(speed)  # Adjust for negative speeds if necessary
    await self.command("drive", bytearray([
        0x00,  # Placeholder for potential additional parameters
        speed & 0xff,
        (speed >> 8) & 0xff
    ]))
    await asyncio.sleep(duration)
    await self.stop()

I originally assumed that these ports were rewriting the original Python implementation. However the original Python code doesn’t generate the commands to send to the robot directly. It builds a JSON string that it passes to a native OSX binary library that generates the binary data to send to the robot over Bluetooth.

This explains why the original library was so limited and why the ports mostly just remix each other. If I wanted to get robust controls, I’d need to do some reverse engineering myself.

Reverse Engineering

The authors of the previous ports don’t explain how they reverse engineered the existing features. Only https://github.com/IlyaSukhanov/morseapi seems to have actually done original work and he describes it as a process of trial and error, looking at the binary data sent when doing certain behaviors.

While they don’t go into details as far as I can tell, the two ways I’d guess they might have tried would be:

Spy on the BlueTooth packets sent when using the android app (For example: https://www.instructables.com/Reverse-Engineering-Smart-Bluetooth-Low-Energy-Dev/)
Use the original Python library on OSX and capture the binary data from various commands

Since I didn’t have a suitable OSX machine, the second option was out.

While capturing the Android BlueTooth packets sounded interesting (and might be the only way for some other devices), it would be a lot of tedious trial and error.

Rather than take either of these approaches, I decided to go back to the original program. Since the JSON commands were already very comprehensive, I predicted that reverse engineering the OSX dylib wouldn’t be too hard. This is mostly due to the JSON being all string based. Somewhere the key value pairs being sent would be mapped to the command data.

The file I needed to decompile is: https://github.com/playi/WonderPy/blob/master/WonderPy/lib/WonderWorkshop/osx/libWWHAL.dylib

While I haven’t done any serious decompiling in the past, I had used the NSA open source decompiler Ghidra for some capture the flag reverse engineering games. Decompiling dylibs is supported out of the box, so I imported the library and gave it a go. Fortunately, the function names were compiled into the library, so I had a decent amount of context to understand the call trees.

I probably only know a fraction of Ghidra’s functionality, and I’m not going to be going step by step through the menus. In general I only used a few features.

The Symbol Tree - This is a list of the namespaces functions and other symbols in the binary. I would filter by the word (e.x. “pose”) and look at the decompilation of the functions with relevant names.
Search - I could search the binary for certain strings and see where they’re used. This is especially helpful since I knew exact JSON key names to look for.
In the decompilation window I would select variables and edit their names. I’d double click functions to go to their implementations.
To find a functions caller, I’d right click and search for the places that reference it.
The most advanced thing I’d do is edit data types. This let me specify the fields in a struct so Ghidra can figure out what members pointers are referencing.

The first thing I did was find where the strings for the keys related to the commands were being used. I started with a command that was fully supported in the unofficial ports to check that the JSON was turning into the expected binary packets.

void __thiscall
APICore::BotMessengerBuffer::parseBodyWheels
          (BotMessengerBuffer *this,nx_json *param_1,HALMotorWheel_t *param_2,HALMotorWheel_t *param_3)

{
  int iVar1;
  cnx_json har *lVar2;
  int local_2c;
  
  if ((param_2 != (HALMotorWheel_t *)0x0) && (param_3 != (HALMotorWheel_t *)0x0)) {
    for (local_2c = 0; local_2c < *(int *)(param_1 + 0x28); local_2c = local_2c + 1) {
      lVar2 = _nx_json_item(param_1,local_2c);
      iVar1 = _strcmp((char *)(lVar2 + 8),"left_cm_s");
      if (iVar1 == 0) {
        *(undefined8 *)(param_2 + 8) = *(undefined8 *)(lVar2 + 0x20);
      }
      iVar1 = _strcmp((char *)(lVar2 + 8),"right_cm_s");
      if (iVar1 == 0) {
        *(undefined8 *)(param_3 + 8) = *(undefined8 *)(lVar2 + 0x20);
      }
    }
  }
  return;
}

A quick Google found that the nx_json refers to the https://github.com/thestr4ng3r/nxjson C JSON library which helpfully lists its structure definition in the README:

typedef enum nx_json_type {
  NX_JSON_NULL,    // this is null value
  NX_JSON_OBJECT,  // this is an object; properties can be found in child nodes
  NX_JSON_ARRAY,   // this is an array; items can be found in child nodes
  NX_JSON_STRING,  // this is a string; value can be found in text_value field
  NX_JSON_INTEGER, // this is an integer; value can be found in int_value field
  NX_JSON_DOUBLE,  // this is a double; value can be found in dbl_value field
  NX_JSON_BOOL     // this is a boolean; value can be found in int_value field
} nx_json_type;

typedef struct nx_json {
  nx_json_type type;       // type of json node, see above
  const char* key;         // key of the property; for object's children only
  const char* text_value;  // text value of STRING node
  long int_value;          // the value of INTEGER or BOOL node
  double dbl_value;        // the value of DOUBLE node
  int length;              // number of children of OBJECT or ARRAY
  nx_json* child;          // points to first child
  nx_json* next;           // points to next child
} nx_json;

With this I could define the structure of nx_json in Ghidra

and simplify the function to:

void __thiscall
APICore::BotMessengerBuffer::parseBodyWheels
          (BotMessengerBuffer *this,nx_json *param_1,HALMotorWheel_t *param_2,
          HALMotorWheel_t *param_3)
{
  int iVar1;
  nx_json *lVar2;
  int local_2c;
  
  if ((param_2 != (HALMotorWheel_t *)0x0) && (param_3 != (HALMotorWheel_t *)0x0)) {
    for (local_2c = 0; local_2c < param_1->length; local_2c = local_2c + 1) {
      lVar2 = (nx_json *)_nx_json_item(param_1,local_2c);
      iVar1 = _strcmp(lVar2->key,"left_cm_s");
      if (iVar1 == 0) {
        *(double *)(param_2 + 8) = lVar2->dbl_value;
      }
      iVar1 = _strcmp(lVar2->key,"right_cm_s");
      if (iVar1 == 0) {
        *(double *)(param_3 + 8) = lVar2->dbl_value;
      }
    }
  }
  return;
}

This is pretty readable without doing the extra steps to guess the structure of HALMotorWheel_t and give the variables nicer names. This already was fairly different from the Python code. These values are being stored as doubles, and they don’t appear to be directly being used to build the packet structure that gets sent to the Robot. That means that the parsing process is more complicated.

Looking at the references to parseBodyWheels I found :

// A bunch of intermediate variables are removed for brevity.
nx_json * APICore::BotMessengerBuffer::convertCtlrMessageToPackets(nx_json *param_1)
{
  RobotHW *this;
  Ctlr2BotMsg *this_00;
  ...
  HALPamplemousse_t *local_1a8;
  HALAudioSynth_t *local_1a0;
  HALPing_t *local_198;
  HALPower_t *local_190;
  HALBodyPose_t *local_188;
  HALBodyMotionLinearAngular_t *local_180;
  HALUserSetting_t *local_178;
  HALAnim_t *local_170;
  HALSpeaker_t *local_168;
  HALEyeRing_t *local_160;
  HALRGB_t *local_158;
  HALLED3_t *local_150;
  HALLED_t *local_148;
  HALMotorWheel_t *local_140;
  HALMotorWheel_t *local_138;
  HALMotorWheel_t *local_130;
  HALComponentScalar_t *local_128;
  HALMotorServo_t *local_120;
  HALMotorServo_t *local_118;
  HALLedMsg_t *local_108;
  HALLauncher_t *local_100;

  HAL::Ctlr2BotMsg::Ctlr2BotMsg(this_00);
  HAL::RobotHW::initComponentsForCtlr2BotMsg((RobotHW *)in_RSI->dbl_value,this_00);

  do {
    if (local_d0[10] <= local_e8) {
      local_1b1 = 0;
      HAL::RobotHW::packetizeCtlr2BotMsg((Ctlr2BotMsg *)param_1);
      std::shared_ptr<>::shared_ptr<>((shared_ptr<> *)&local_1c8,local_d8,0);
      
      return param_1;
    }
    local_f0 = (nx_json *)_nx_json_item(local_d0,local_e8);
    local_f4 = _atoi(local_f0->key);
    if (local_f4 == 1) {
      local_190 = (HALPower_t *)HAL::Ctlr2BotMsg::getPowerStorage(local_d8,1);
      parsePower((BotMessengerBuffer *)in_RSI,local_f0,local_190);
    }
    else if (local_f4 == 100) {
      local_160 = (HALEyeRing_t *)HAL::Ctlr2BotMsg::getEyeRingStorage(local_d8,100);
      parseEyeRing((BotMessengerBuffer *)in_RSI,local_f0,local_160);
    }
    else if (local_f4 - 0x65 < 4) {
LAB_000662f5:
      local_158 = (HALRGB_t *)HAL::Ctlr2BotMsg::getRGBStorage(local_d8,local_f4);
      parseLightRGB((BotMessengerBuffer *)in_RSI,local_f0,local_158);
    }
    else if (local_f4 - 0x69 < 2) {
LAB_00066285:
      local_148 = (HALLED_t *)HAL::Ctlr2BotMsg::getLEDStorage(local_d8,local_f4);
      parseLightLED((BotMessengerBuffer *)in_RSI,local_f0,local_148);
    }
    else {
      if (local_f4 == 0x6b) goto LAB_000662f5;
      if (local_f4 == 0x6c) {
        local_150 = (HALLED3_t *)HAL::Ctlr2BotMsg::getLED3Storage(local_d8,0x6c);
        parseLightLED3((BotMessengerBuffer *)in_RSI,local_f0,local_150);
      }
      else {
        if (local_f4 - 0x6d < 3) goto LAB_00066285;
        if (local_f4 - 200 < 2) {
          local_130 = (HALMotorWheel_t *)HAL::Ctlr2BotMsg::getMotorWheelStorage(local_d8,local_f4);
          parseMotorWheel((BotMessengerBuffer *)in_RSI,local_f0,local_130);
        }
        else {
          if (local_f4 == 0xca) goto LAB_00066187;
          if (local_f4 == 0xcb) goto LAB_0006614f;
          if (local_f4 == 0xcc) {
            local_180 = (HALBodyMotionLinearAngular_t *)
                        HAL::Ctlr2BotMsg::getBodyMotionLinearAngularStorage(local_d8,0xcc);
            parseBodyMotionLinearAngular((BotMessengerBuffer *)in_RSI,local_f0,local_180);
          }
          else if (local_f4 == 0xcd) {
            local_188 = (HALBodyPose_t *)HAL::Ctlr2BotMsg::getBodyPoseStorage(local_d8,0xcd);
            parseBodyPose((BotMessengerBuffer *)in_RSI,local_f0,local_188);
          }
          else if (local_f4 == 0xce) {
LAB_00066187:
            local_120 = (HALMotorServo_t *)HAL::Ctlr2BotMsg::getMotorServoStorage(local_d8,local_f4)
            ;
            parseMotorHeadTiltServo((BotMessengerBuffer *)in_RSI,local_f0,local_120);
          }
          else {
            if (local_f4 != 0xcf) {
              if (local_f4 == 0xd0) goto LAB_00066187;
              if (local_f4 != 0xd1) {
                if (local_f4 == 0xd2) {
LAB_00066117:
                  local_110 = HAL::Ctlr2BotMsg::getNoParamsStorage(local_d8,local_f4);
                  parseNoParams(in_RSI,(HALNoParams_t *)local_f0);
                }
                else if (local_f4 == 0xd3) {
                  local_138 = (HALMotorWheel_t *)
                              HAL::Ctlr2BotMsg::getMotorWheelStorage(local_d8,200);
                  local_140 = (HALMotorWheel_t *)
                              HAL::Ctlr2BotMsg::getMotorWheelStorage(local_d8,0xc9);
                  parseBodyWheels((BotMessengerBuffer *)in_RSI,local_f0,local_138,local_140);
                }
                else {
                  if (local_f4 == 0xd4) goto LAB_00066117;
                  if (local_f4 - 0xd5 < 2) {
                    local_128 = (HALComponentScalar_t *)
                                HAL::Ctlr2BotMsg::getScalarStorage(local_d8,local_f4);
                    parseScalarPercentage((BotMessengerBuffer *)in_RSI,local_f0,local_128);
                  }
                  else if (local_f4 == 300) {
                    local_168 = (HALSpeaker_t *)HAL::Ctlr2BotMsg::getSpeakerStorage(local_d8,300);
                    parseSpeaker((BotMessengerBuffer *)in_RSI,local_f0,local_168);
                  }
                  else if (local_f4 == 0x12d) {
                    local_170 = (HALAnim_t *)HAL::Ctlr2BotMsg::getAnimStorage(local_d8,0x12d);
                    parseOnRobotAnim((BotMessengerBuffer *)in_RSI,local_f0,local_170);
                  }
                  else if (local_f4 == 0x130) {
                    local_1a0 = (HALAudioSynth_t *)
                                HAL::Ctlr2BotMsg::getAudioSynthStorage(local_d8,0x130);
                    parseAudioSynth((BotMessengerBuffer *)in_RSI,local_f0,local_1a0);
                  }
                  else if (local_f4 - 400 < 2) {
                    local_100 = (HALLauncher_t *)
                                HAL::Ctlr2BotMsg::getLauncherStorage(local_d8,local_f4);
                    parseLauncher((BotMessengerBuffer *)in_RSI,local_f0,local_100);
                  }
                  else if (local_f4 == 0x19a) {
                    local_108 = (HALLedMsg_t *)HAL::Ctlr2BotMsg::getLedMsgStorage(local_d8,0x19a);
                    parseLedMsg((BotMessengerBuffer *)in_RSI,local_f0,local_108);
                  }
                  else if (local_f4 == 0x1c2) {
                    local_1a8 = (HALPamplemousse_t *)
                                HAL::Ctlr2BotMsg::getPamplemousseStorage(local_d8,0x1c2);
                    parsePamplemousseStart((BotMessengerBuffer *)in_RSI,local_f0,local_1a8);
                  }
                  else if (local_f4 == 0x1c3) {
                    local_1b0 = (HALPamplemousse_t *)
                                HAL::Ctlr2BotMsg::getPamplemousseStorage(local_d8,0x1c3);
                    parsePamplemousseStop((BotMessengerBuffer *)in_RSI,local_f0,local_1b0);
                  }
                  else if (local_f4 == 5000) {
                    local_178 = (HALUserSetting_t *)
                                HAL::Ctlr2BotMsg::getUserSettingsStorage(local_d8,5000);
                    parseUserSettings((BotMessengerBuffer *)in_RSI,local_f0,local_178);
                  }
                  else if (local_f4 == 9000) {
                    local_198 = (HALPing_t *)HAL::Ctlr2BotMsg::getPingStorage(local_d8,9000);
                    parsePing((BotMessengerBuffer *)in_RSI,local_f0,local_198);
                  }
                  else {
                    _printf("unknown component id: %d",(ulong)local_f4);
                    _printf("\n");
                  }
                }
                goto LAB_000665c3;
              }
            }
LAB_0006614f:
            local_118 = (HALMotorServo_t *)HAL::Ctlr2BotMsg::getMotorServoStorage(local_d8,local_f4)
            ;
            parseMotorHeadPanServo((BotMessengerBuffer *)in_RSI,local_f0,local_118);
          }
        }
      }
    }
LAB_000665c3:
    this = (RobotHW *)in_RSI->dbl_value;
    pvVar1 = (void *)HAL::Ctlr2BotMsg::GetHwData(local_d8);
    HAL::RobotHW::setCommand(this,pvVar1,local_f4);
    local_e8 = local_e8 + 1;
  } while( true );
}

For my purposes this is the top level function. It does the following:

Initialize a Ctlr2BotMsg. This has the storage for all the messages that might be sent.
Loop through the JSON and set the values in the corresponding HAL structure in Ctlr2BotMsg.
After setting the data for the each command call setCommand.
Once all the commands have been setup, call packetizeCtlr2BotMsg.

The first thing I looked for, was where the commands were being mapped to command IDs that we see in the Python port:

COMMANDS = {
    "neck_color":0x03,
    "tail_brightness":0x04,
    "eye_brightness":0x08,
    "eye":0x09,
    "left_ear_color":0x0b,
    "right_ear_color":0x0c,
    "head_color":0x0d,
    "head_pitch":0x07,
    "head_yaw":0x06,
    "pose":0x23,
    "say":0x18,
    "beep":0x19,
    "drive":0x02,
    "move":0x23,
    "reset":0xc8,
}

The JSON uses different integers to identify the commands:

class RobotComponent(object):
        WW_COMMAND_POWER                      =    '1'
        WW_COMMAND_EYE_RING                   =  '100'
        WW_COMMAND_LIGHT_RGB_EYE              =  '101'
        WW_COMMAND_LIGHT_RGB_LEFT_EAR         =  '102'
        WW_COMMAND_LIGHT_RGB_RIGHT_EAR        =  '103'
        WW_COMMAND_LIGHT_RGB_CHEST            =  '104'
        WW_COMMAND_LIGHT_MONO_TAIL            =  '105'
        WW_COMMAND_LIGHT_MONO_BUTTON_MAIN     =  '106'
        WW_COMMAND_LIGHT_RGB_BUTTON_MAIN      =  '107'
        WW_COMMAND_LIGHT_MONO_BUTTONS         =  '108'
        WW_COMMAND_LIGHT_MONO_BUTTON_1        =  '109'  # cue button light - circle
        WW_COMMAND_LIGHT_MONO_BUTTON_2        =  '110'  # cue button light - square
        WW_COMMAND_LIGHT_MONO_BUTTON_3        =  '111'  # cue button light - triangle
        WW_COMMAND_HEAD_POSITION_TILT         =  '202'
        WW_COMMAND_HEAD_POSITION_PAN          =  '203'
        WW_COMMAND_BODY_LINEAR_ANGULAR        =  '204'
        WW_COMMAND_BODY_POSE                  =  '205'
        WW_COMMAND_MOTOR_HEAD_BANG            =  '210'
        WW_COMMAND_BODY_WHEELS                =  '211'
        WW_COMMAND_BODY_COAST                 =  '212'
        WW_COMMAND_HEAD_PAN_VOLTAGE           =  '213'
        WW_COMMAND_HEAD_TILT_VOLTAGE          =  '214'
        WW_COMMAND_SPEAKER                    =  '300'
        WW_COMMAND_ON_ROBOT_ANIM              =  '301'
        WW_COMMAND_LAUNCHER_FLING             =  '400'
        WW_COMMAND_LAUNCHER_RELOAD            =  '401'
        WW_COMMAND_LED_MESSAGE                =  '410'
        WW_COMMAND_SET_PING                   = '9000'

The JSON integers can be seen (as hex) in convertCtlrMessageToPackets which makes sense. They are also referenced in setCommand:

void HAL::RobotHW_rev0::setCommand(void *cmd_data,uint cmd_id)
{
  size_t sVar1;
  
  if (cmd_data != (void *)0x0) {
    if (cmd_id == 1) {
      *(ulong *)cmd_data = *(ulong *)cmd_data | 0x8000;
      *(undefined1 *)((long)cmd_data + 0x28c) = 1;
    }
    else if (cmd_id == 100) {
      if (*(int *)((long)cmd_data + 0x70) == 0) {
        *(ulong *)cmd_data = *(ulong *)cmd_data | 0x100;
      }
      else if (*(int *)((long)cmd_data + 0x70) == 1) {
        *(ulong *)cmd_data = *(ulong *)cmd_data | 0x80000000000;
      }
      else {
        _printf("error: unsupported brightnessMode: %d\n",(ulong)*(uint *)((long)cmd_data + 0x70));
        *(ulong *)cmd_data = *(ulong *)cmd_data | 0x100;
      }
      if (*(int *)((long)cmd_data + 0x58) == 0xffff) {
        *(ulong *)cmd_data = *(ulong *)cmd_data | 0x200;
        *(ulong *)cmd_data = *(ulong *)cmd_data & 0xfffffffffffffbff;
      }
      else {
        *(ulong *)cmd_data = *(ulong *)cmd_data | 0x400;
        *(ulong *)cmd_data = *(ulong *)cmd_data & 0xfffffffffffffdff;
      }
      *(undefined1 *)((long)cmd_data + 0x54) = 1;
    }
    else {
      if (cmd_id != 0x65) {
        if (cmd_id == 0x66) {
          *(ulong *)cmd_data = *(ulong *)cmd_data | 0x800;
          *(undefined1 *)((long)cmd_data + 0x84) = 1;
          return;
        }
...

Here the JSON commands are mapped to the one or more bit mask flags.

These flags are then checked in packetizeCtlr2BotMsg. The pose command I’m interested in has the JSON ID of 0xCD, which sets the bit flag 0x20000. In packetizeCtlr2BotMsg this is handled in this snippet.

uVar19 = testAndClearCommandMaskBit(prVar25,0x20000);
if ((uVar19 & 1) != 0) {
  uVar17 = *(int *)(msg_hw_ptr + 0x2f8);
  if ((uVar17 == 0) || (local_688 = uVar17 + -6, uVar17 - 2U < 4)) {
    *(double *)local_200 = 0.0;
  }
  for (i = 0; i < 3; i = i + 1) {
    if ((*(int *)(msg_hw_ptr + 0x2f8) == 3) || (*(int *)(msg_hw_ptr + 0x2f8) == 4)) {
      local_3e0 = 9;
      if (8 < 0x14U - *(int *)(msg_hw_ptr + (long)i * 0x18 + 8)) {
        if (*(int *)(msg_hw_ptr + 0x2f8) == 3) {
          local_3e1 = (robot_hw0_cmd_data)0x17;
        }
        else {
          local_3e1 = (robot_hw0_cmd_data)0x29;
        }
        local_690 = *(double *)(msg_hw_ptr + 0x2d8) * 10.0;
        if (32767.0 <= local_690) {
          local_690 = 32767.0;
        }
        if (local_690 <= -32768.0) {
          local_698 = -32768.0;
        }
        else {
          local_698 = local_690;
        }
        ...
        msg_hw_ptr[(ulong)*(uint *)(msg_hw_ptr + (long)i * 0x18 + 8) + (long)i * 0x18 + 0xc] =
              local_3e1;
        msg_hw_ptr
        [(ulong)(*(int *)(msg_hw_ptr + (long)i * 0x18 + 8) + 1) + (long)i * 0x18 + 0xc] =
              SUB21((ushort)local_40a >> 8,0);
        ...

Based on parseBodyPose, I’d already created a data type for the pose data. It appeared that the data parsed from the JSON was being accessed here and serialized into the packet to send to the robot. I made a new data type to map the pose data to the right offset

and made this block much clearer:

uVar20 = testAndClearCommandMaskBit(prVar12,0x20000);
if ((uVar20 & 1) != 0) {
  mode = (msg_hw_ptr->pose).mode;
  if ((mode == 0) || (local_688 = mode - 6, mode - 2 < 4)) {
    *(double *)local_200 = 0.0;
  }
  for (i = 0; i < 3; i = i + 1) {
    if (((msg_hw_ptr->pose).mode == 3) || ((msg_hw_ptr->pose).mode == 4)) {
      // Logic for generating command to change the global coordinate origin
      ...
    }
    else {
      local_411 = 0x23;
      local_420 = 9;
      if (8 < 0x14U - *(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8)) {
        x_enc = (msg_hw_ptr->pose).x * 10.0;
        local_430 = (msg_hw_ptr->pose).y * 10.0;
        local_438 = (msg_hw_ptr->pose).theta * 100.0;
        local_440 = local_438 - *(double *)local_200;
        local_6d8 = (msg_hw_ptr->pose).time * 1000.0;
        if (65535.0 <= local_6d8) {
          local_6d8 = 65535.0;
        }
        if (local_6d8 <= 0.0) {
          local_6e0 = 0.0;
        }
        else {
          local_6e0 = local_6d8;
        }
        local_448 = local_6e0;
        local_428 = x_enc;
        *(undefined8 *)((long)pppHVar27 + -8) = 0x7e580;
        dVar29 = (double)_round(x_enc);
        x_enc = local_430;
        local_44a = (undefined2)(int)dVar29;
        *(undefined8 *)((long)pppHVar27 + -8) = 0x7e59b;
        dVar29 = (double)_round(x_enc);
        x_enc = local_440;
        local_44c = (undefined2)(int)dVar29;
        *(undefined8 *)((long)pppHVar27 + -8) = 0x7e5b6;
        x_enc = (double)_round(x_enc);
        local_6e2 = (short)(int)x_enc;
        iVar18 = (int)local_448;
        local_450 = (undefined2)iVar18;
        *(double *)local_200 = (double)(int)local_6e2 - local_440;
        msg_hw_ptr->field0_0x0
        [(ulong)*(uint *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + (long)i * 0x18 + 0xc] =
              local_411;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 1) +
          (long)i * 0x18 + 0xc] = (char)local_44a;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 2) +
          (long)i * 0x18 + 0xc] = (char)local_44c;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 3) +
          (long)i * 0x18 + 0xc] = (char)(int)x_enc;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 4) +
          (long)i * 0x18 + 0xc] = (char)((uint)iVar18 >> 8);
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 5) +
          (long)i * 0x18 + 0xc] = (char)iVar18;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 6) +
          (long)i * 0x18 + 0xc] = (byte)((ushort)local_44a >> 8) & 0x3f;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 7) +
          (long)i * 0x18 + 0xc] = (byte)((ushort)local_44c >> 8) & 0x3f;
        uVar20 = (ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 6);
        msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] =
              msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] |
              (byte)(local_6e2 >> 2) & 0xc0;
        uVar20 = (ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 7);
        msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] =
              msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] |
              (byte)(local_6e2 >> 4) & 0xc0;
        msg_hw_ptr->field0_0x0
        [(ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 8) +
          (long)i * 0x18 + 0xc] = 0;
        if ((msg_hw_ptr->pose).mode == 5) {
          local_6e8 = 3;
        }
        else {
          local_6e8 = (msg_hw_ptr->pose).mode;
        }
        uVar20 = (ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 8);
        msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] =
              msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] | (byte)(local_6e8 << 6);
        uVar20 = (ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 8);
        msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] =
              msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] |
              ((msg_hw_ptr->pose).ease & 1) << 5;
        uVar20 = (ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 8);
        msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] =
              msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] |
              (byte)((msg_hw_ptr->pose).wrap_theta << 4);
        uVar20 = (ulong)(*(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + 8);
        msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] =
              msg_hw_ptr->field0_0x0[uVar20 + (long)i * 0x18 + 0xc] |
              (byte)(msg_hw_ptr->pose).dir;
        *(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) =
              *(int *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + (int)local_420;
        local_44e = local_6e2;
        break;
      }
    }
  }
}

The only complicated thing left is where these values are being written to. For some reason, this code loops through the data making three copies. The line:

msg_hw_ptr->field0_0x0
        [(ulong)*(uint *)(msg_hw_ptr->field0_0x0 + (long)i * 0x18 + 8) + (long)i * 0x18 + 0xc] =
              local_411;

Writes the command ID byte 0x23 (which matches the value in the Python port) to an offset in memory. This value appears to be the result of following a pointer to a pointer of the structure that’s building the packets to send. Still, we get the clear sequence of data which can be cleaned up to:

// Get base pointer to the buffer
uint8_t *buffer_base = msg_hw_ptr->field0_0x0 + (long)local_3d8 * 0x18 + 0xc;
int *write_offset_ptr = (int *)(msg_hw_ptr->field0_0x0 + (long)local_3d8 * 0x18 + 8);
int write_offset = *write_offset_ptr;

// Initialize tracking variable
*(double *)local_200 = 0.0;

// Packet type/ID
uint8_t packet_id = 0x23;
uint8_t packet_size = 9;

// Scale and prepare pose data
double x_scaled = (msg_hw_ptr->pose).x * 10.0;
double y_scaled = (msg_hw_ptr->pose).y * 10.0;
double theta_scaled = (msg_hw_ptr->pose).theta * 100.0;
double theta_delta = theta_scaled - *(double *)local_200;
double time_ms = (msg_hw_ptr->pose).time * 1000.0;

// Clamp time to uint16 range
if (time_ms >= 65535.0) {
    time_ms = 65535.0;
}
if (time_ms < 0.0) {
    time_ms = 0.0;
}

// Round values for encoding
int16_t x_encoded = (int16_t)round(x_scaled);
int16_t y_encoded = (int16_t)round(y_scaled);
int16_t theta_encoded = (int16_t)round(theta_delta);
uint16_t time_encoded = (uint16_t)time_ms;

// Update tracking variable with rounding error
*(double *)local_200 = (double)theta_encoded - theta_delta;

// Serialize to buffer
buffer_base[write_offset + 0] = packet_id;                              // Byte 0: Packet ID (0x23)
buffer_base[write_offset + 1] = (uint8_t)x_encoded;                     // Byte 1: X low byte
buffer_base[write_offset + 2] = (uint8_t)y_encoded;                     // Byte 2: Y low byte
buffer_base[write_offset + 3] = (uint8_t)theta_encoded;                 // Byte 3: Theta low byte
buffer_base[write_offset + 4] = (uint8_t)(time_encoded >> 8);          // Byte 4: Time high byte
buffer_base[write_offset + 5] = (uint8_t)time_encoded;                  // Byte 5: Time low byte
buffer_base[write_offset + 6] = ((uint8_t)(x_encoded >> 8)) & 0x3F;    // Byte 6: X high 6 bits
buffer_base[write_offset + 7] = ((uint8_t)(y_encoded >> 8)) & 0x3F;    // Byte 7: Y high 6 bits

// Pack theta high bits into bytes 6 and 7
buffer_base[write_offset + 6] |= ((uint8_t)(theta_encoded >> 2)) & 0xC0;  // Theta bits [9:8]
buffer_base[write_offset + 7] |= ((uint8_t)(theta_encoded >> 4)) & 0xC0;  // Theta bits [11:10]

// Initialize control byte
buffer_base[write_offset + 8] = 0;                                      // Byte 8: Control flags

// Handle mode (convert mode 5 to mode 3)
uint8_t mode = ((msg_hw_ptr->pose).mode == 5) ? 3 : (msg_hw_ptr->pose).mode;

// Pack control flags into byte 8
buffer_base[write_offset + 8] |= (mode & 0x03) << 6;                   // Bits [7:6]: mode
buffer_base[write_offset + 8] |= ((msg_hw_ptr->pose).ease & 0x01) << 5;     // Bit 5: ease
buffer_base[write_offset + 8] |= ((msg_hw_ptr->pose).wrap_theta & 0x01) << 4; // Bit 4: wrap_theta
buffer_base[write_offset + 8] |= ((msg_hw_ptr->pose).dir & 0x0F);      // Bits [3:0]: direction

// Update write offset
*write_offset_ptr += packet_size;

This is trivial to port to the Python library to add a more complete version of the missing functionality.

As I continued to read through the original Python library, I realized that the expected behavior was to pack multiple commands into packets up to a max size. This finally let me figure out that the for loop is just writing the command into the next packet with capacity. This gives the extra context for the pose serialization:

#define POSE_CMD_BYTE 0x23
#define POSE_CMD_SIZE 9
#define MAX_PACKET_SIZE 20

for (i = 0; i < 3; i++) {
    uint8_t  cmd         = POSE_CMD_BYTE;
    uint8_t  msg_len     = POSE_CMD_SIZE;
    // msg_hw_ptr->packets are the struct:
    // struct Packet {
    //   uint32_t size;
    //   uint8_t data[20];
    // }
    uint8_t  packet_size = msg_hw_ptr->packets[i].size;

    if (packet_size + POSE_CMD_SIZE > MAX_PACKET_SIZE) {
        continue;
    }

    // Scale pose values to fixed-point integers
    int16_t x_enc     = (int16_t)round(msg_hw_ptr->pose.x     * 10.0);
    int16_t y_enc     = (int16_t)round(msg_hw_ptr->pose.y     * 10.0);
    int16_t theta_enc = (int16_t)round(msg_hw_ptr->pose.theta * 100.0);

    // Clamp time to uint16 range
    double time_ms = msg_hw_ptr->pose.time * 1000.0;
    if (time_ms >= 65535.0) time_ms = 65535.0;
    if (time_ms <= 0.0)     time_ms = 0.0;
    uint16_t time_enc = (uint16_t)time_ms;

    // Pack command byte and fixed-point values into packet
    uint8_t *data = &msg_hw_ptr->packets[i].data[packet_size];

    data[0] = cmd;
    data[1] = (uint8_t)(x_enc     & 0xFF);         // x low byte
    data[2] = (uint8_t)(y_enc     & 0xFF);         // y low byte
    data[3] = (uint8_t)(theta_enc & 0xFF);         // theta low byte
    data[4] = (uint8_t)(time_enc  >> 8);           // time high byte
    data[5] = (uint8_t)(time_enc  & 0xFF);         // time low byte
    data[6] = (uint8_t)(x_enc     >> 8) & 0x3F;   // x high bits
    data[7] = (uint8_t)(y_enc     >> 8) & 0x3F;   // y high bits
    data[6] |= (uint8_t)(theta_enc >> 2) & 0xC0;  // theta bits 9:8 -> x high byte bits 7:6
    data[7] |= (uint8_t)(theta_enc >> 4) & 0xC0;  // theta bits 11:10 -> y high byte bits 7:6

    // Pack flags byte
    // Map mode 5 -> 3, otherwise pass through
    uint8_t mode = (msg_hw_ptr->pose.mode == 5) ? 3 : (uint8_t)msg_hw_ptr->pose.mode;
    data[8] = 0;
    data[8] |= (mode                          & 0x03) << 6;  // bits 7:6 = mode
    data[8] |= (msg_hw_ptr->pose.ease         & 0x01) << 5;  // bit  5   = ease
    data[8] |= (msg_hw_ptr->pose.wrap_theta   & 0x01) << 4;  // bit  4   = wrap_theta
    data[8] |= (msg_hw_ptr->pose.dir          & 0x0F);       // bits 3:0 = dir

    msg_hw_ptr->packets[i].size += msg_len;
    break;
}

Systematically Decoding the Commands

Now the I understood the basic structure of the library, I took notes on the all of the commands and the process to encode them:

https://github.com/axlan/WonderPy/blob/master/doc/reversing/ReversingDylib.md

Ghidra can be a little slow to navigate, so I used its Python API to dump the decompilation of functions that matched a regex: https://gist.github.com/axlan/c38f7b01e54ab9f7cdefea51cd1dc9ed . I included this output in case anyone wants to implement some of the commands I skipped.

With the mapping of the JSON commands to the flags that get set to send the various command packets, it was fairly quick to go through the features I wanted to support and write the serialization in Python.

In doing this investigation I found quite a few commands that weren’t actually referenced in the original Python library. While most were just variations, I found a “Pamplemousse” command that appears to be able to define autonomous behaviors.

Decoding the Sensors

Decoding the sensor data coming from the bot was more straight-forward than encoding the commands. Rather then going through multiple conversion stages, the _deserialize function retrieves the bytes accicociated with each value, and calls the functions to scale them and write them to their corresponding JSON keys.

The infrared distance sensors were a bit interesting. The bot directly reports a value referred to as “reflectance”, but the library had a function for converting this to distance in cm. There’s a class that builds a model based on a series of observations for each of the 3 sensors. They compiled in a series of test observations to initialize the model and that’s what they used to do the conversion. While implementing this in Python would have been possible, it would probably be a lot easier to just make my own model based on my own bot and the environment I’m using it in.

The other interesting sensor was the microphone. It’s supposed to report the direction of detected sound along with its confidence. The reported direction seemed to work (its quite inaccurate which isn’t too unexpected), but it never reported any level of confidence. This might just be a lack of decompiling skills or a mistake on my part, but it is also possible this interface changed at some point.

Conclusion

While I present a pretty clear progression to understanding this library, the actual process was much messier. I didn’t know which leads would be the most fruitful, so sometimes I missed important details as I jumped back and forth, spending time analyzing parts of the library that didn’t turn out to be relevant.

While this turned out to be more complicated than I expected, it was still a relatively straightforward library that I had a lot of external context for.

This function should be all that I need for my project, but maybe I’ll take the time at some point to clean up these libraries a bit more.

The last mystery is why was the original project designed this way? It’s possible hiding the actual packet specification in a binary library was intentional obfuscation, but my guess is that it was a side effect of minimizing effort.

It’s possible that the Python library was initially an internal testing tool. Someone realized that making it public open source would get people like me to consider the dash. If development was standardized on OSX and Python 2.7, that might have been all they supported internally. Once it was released, if it didn’t generate a ton of buzz, there may not have been much will to keep updating it.

To implement my findings I made a fork the original https://github.com/playi/WonderPy with the following changes:

Making it Python 3 compatible
Switching from its deprecated BLE library to https://github.com/hbldh/bleak
Removing the OSX library and replacing it with Python conversions for the commands/sensors I want to support.

See: https://github.com/axlan/WonderPy

It is still far from complete. Partly, because some of the features are complicated, but mostly just to not having infinite time.

Profiling ESP32 UDP Sends

Thu, 29 Jan 2026 00:00:00 +0000

With my new profiling setup, I decided to test efficiently sending UDP data logs.

With my findings from Making an Embedded Profiler 3: ESP IDF Tools, I decided to stick with using MabuTrace. While it isn’t exactly what I wanted for profiling, it covers all the key features, and in many ways is better than anything I’d end up making.

However, it doesn’t cover the continuous logging use case. While it would generally make more sense to use MQTT, ESP-IDF logging, or some other existing protocol, I wanted to try using my https://github.com/axlan/min-logger since I made it with the exact features I wanted.

For the ESP32, min-logger was still missing a backend for buffering logged data and sending it to the host.

I quickly setup a ESP-IDF framework test application, and began to experiment with different approaches. MabuTrace was great in letting me see exactly what was happening with each approach.

My goal was to set up a system where multiple tasks on multiple cores could write data simultaneously with minimal latency. This data would be buffered and periodically sent to the host over UDP. Since I don’t care about latency and each send has overhead, each send would be the maximum UDP packet size. I wanted to find a way to do this while being efficient with CPU and memory usage.

Code for these tests is found at: https://github.com/axlan/esp32-idf-udp-send-profiling

While this article is about figuring out how to efficiently send UDP data, based on these results I added a buffered UDP output option to min-logger. I fell down a bit of a rabbit hole making a custom ring buffer for the use case: https://github.com/axlan/min-logger/blob/master/src/min_logger/platform_implementations/lock_free_ring_buffer.h.

Data Synchronization

After reading the ESP-IDF documentation, I found the FreeRTOS ring buffer addition. Specifically, I could use it in “byte buffer” mode. This meant I could efficiently write arbitrarily sized chunks from multiple tasks and combine them into a single large read for sending over UDP. Initially, I set it up to drain the ring buffer into an array in the UDP send task. However, I realized that by sizing the buffer to be twice the desired UDP write size, I could effectively double-buffer the data and not need to worry about tearing on the consumer side.

Here’s a little demo below. Note that as long as each read is half the buffer size, the data will always be contiguous.

Ring Buffer Operations (Size: 20)

Filled

Empty

↓ Read Pointer

↑ Write Pointer

Initial State

R W 0

Read = 0, Write = 0, Count = 0

Step 1: Write 5 elements

R 0

W 5

Read = 0, Write = 5, Count = 5

Step 2: Write 6 elements

R 0

W 11

Read = 0, Write = 11, Count = 11

Step 3: Read 10 elements

R 10

W 11

Read = 10, Write = 11, Count = 1

Step 4: Write 12 elements (wraps around)

R 10

Read = 10, Write = 3 (wrapped), Count = 13

Step 5: Read 10 elements

R 0

W 3

Read = 0 (wrapped), Write = 3, Count = 3

The issue with implementing this approach is that the FreeRTOS ring buffer addition doesn’t have a way to wait for a certain threshold of data to be available. This meant I needed to poll the buffer to determine when it was full enough to read from.

lwIP UDP Send Options

The first place I looked for an example of efficiently sending UDP packets was the ESP32 Arduino library. It has the AsyncUDP library. This library introduced me to an API I hadn’t seen before: the lwIP raw/callback-style API. I spent considerable time trying to unravel this poorly documented interface. Once I started to understand it, I noticed the esp32-idf lwIP documentation mentioned that this API is not supported and to instead use a similar netconn API. Additionally, even this netconn API is only unofficially supported, and the BSD sockets are the recommended interface.

Regardless, I completed a basic test application with both the BSD and raw APIs:

Raw:

BSD:

Even looking at heap usage it isn’t obvious that the raw API has any advantage over the BSD.

This was somewhat surprising since I set up the raw API to perform zero-copy operations:

static void udp_client_task_raw(void *pvParameters)
{
  struct udp_pcb *pcb;
  pcb = udp_new();
  udp_bind(pcb, IP_ADDR_ANY, 0);

  ip_addr_t dest_ip;
  dest_ip.type = IPADDR_TYPE_V4;
  IP4_ADDR(&dest_ip.u_addr.ip4, 192, 168, 1, 111);

  // Allocate a pbuf that will point to a block of read only memory. In this case it will point to a half of the ring buffer being held.
  struct pbuf *pbuf = pbuf_alloc(PBUF_TRANSPORT, UDP_MESSAGE_SIZE, PBUF_ROM);
  assert(pbuf != NULL);

  // This is effectively const, but needs to be mutable to match pbuf typing since it's used for receive calls as well as send.
  void *held_data = NULL;

  while (1)
  {
    // Check if UDP send is done. If so return data to ring buffer.
    if (held_data != NULL && pbuf->ref == 1)
    {
      vRingbufferReturnItem(buf_handle, held_data);
      held_data = NULL;
    }

    // Check if a UDP packet's worth of data is ready to send.
    if (xRingbufferGetCurFreeSize(buf_handle) <= UDP_MESSAGE_SIZE)
    {
      size_t read_size = 0;
      // By always reading half the buffer size, the read will never be limited by rolling over the end of the buffer.
      held_data = xRingbufferReceiveUpTo(buf_handle, &read_size, pdMS_TO_TICKS(portMAX_DELAY), UDP_MESSAGE_SIZE);
      assert(read_size == UDP_MESSAGE_SIZE);
      pbuf->payload = held_data;
      pbuf->tot_len = UDP_MESSAGE_SIZE;
      udp_sendto(pcb, pbuf, &dest_ip, PORT);
    }
    vTaskDelay(10 / portTICK_PERIOD_MS);
  }
}

It’s also surprising that for both implementations, the send call usually blocks for 3.5ms with just a single send every couple of seconds.

There are several possibilities for this result:

As mentioned, the raw API isn’t maintained, so it may be doing something less efficient than the better-supported BSD sockets.
Since no other data is being sent, each send call transmits the packet immediately. The behavior might be different if data was being queued.
The BSD socket appears to leverage the tiT (the lwIP background) task. It’s possible it’s using resources that are already allocated there.
The expected behavior may be for these functions to block to reduce buffer usage.
There may be more optimal compile-time configuration settings that would improve the raw interface if sockets weren’t being used anywhere.

As a final test, I also implemented this with the netconn API. It ended up performing being fairly similar to the BSD code, passing off the processing to the tiT task.

Here are the three implementations:

In the end, for this use case, the BSD sockets make the most sense since they are the simplest and best documented. The only real behavioral advantage I could identify is that the raw implementation spends more time in the user task instead of the lwIP task. This could potentially help the latency of other user tasks since they could more easily preempt it.

Making an Embedded Profiler 3: ESP IDF Tools

Tue, 27 Jan 2026 00:00:00 +0000

I want to settle on the tooling I’ll use for a large ESP32 project. I gave the raw ESP-IDF Espressif tools (without the Arduino wrapper) a try for the first time and found two additional logging/profiling tools to evaluate.

This is a follow up to:

I’m at the point where I want to actually figure out the workflows and tools to use to continue my work on Making a Turtle Bot 1: Hacking a Mint Cleaner. I had been frustrated by the limited feedback I was getting during development. So this time I wanted to make sure I could:

Easily dump data for analysis.
Get a wholistic view of what the system was doing.
Have useful debugging and logging tools.

Having completed my own https://github.com/axlan/min-logger, my plan A was to make an ESP32 specific design. My high-level plan was to write the logs to a buffer that would be drained by a separate task sending the data over UDP.

As I began to look into the details of making this implementation I stumbled on two additional candidate libraries I wanted to cover. They both seem worth considering for use in my own development process, and also have interesting implementation details.

MabuTrace

https://github.com/mabuware/MabuTrace

Like my initial assessment of profiling tools, this library also decides to capture binary data to convert into Perfetto logs.

This library wraps the functionality in a super easy UI. To use it you:

Include the MabuTrace library in the build.
Initialize MabuTrace during application setup.
Instrument your code with tracing macros.
When your process runs, it creates an HTTP server and captures data into a ring buffer.
Going to the webserver lets you dump the ring of logged profiling data into your browser and seamlessly load it in Perfetto.

I initially tried to use their Arduino example in PlatformIO, but found that it used a newer version of the ESP Arduino library than PlatformIO supported. This is something that had been worrying me for a while since Espressif had decided to stop directly supporting PlatformIO. I decided that if I was going to need to use the ESP-IDF interface to test this library, I might as well go all the way and just use it directly without PlatformIO.

Once I got the ESP-IDF toolchain setup (which was surprisingly painful), the https://github.com/mabuware/MabuTrace/tree/master/examples/MabuTraceIdfExample example worked out of the box.

The output was exactly what I was looking for and I may very well decide to use this tool as part of my development.

One thing I was surprised by was the inclusion of the CPU scheduling information. My reading of the Espressif FreeRTOS integration was that while some FreeRTOS features like the idle/tick hooks or the run time stats were accessible, the majority of the https://freertos.org/Documentation/02-Kernel/02-Kernel-features/09-RTOS-trace-feature weren’t available:

In looking at how Mabu achieves this, they have:

mabutrace_hooks.h:

void trace_task_switch(unsigned char type);

// This macro is called when a task is about to be switched out.
#define traceTASK_SWITCHED_OUT() \
  do { \
    trace_task_switch(7); \
  } while(0)

// This macro is called when a task has just been switched in.
#define traceTASK_SWITCHED_IN() \
  do { \
    trace_task_switch(6); \
  } while(0)

which are included into the CMake build with:

idf_build_set_property(COMPILE_OPTIONS "-include${CMAKE_CURRENT_SOURCE_DIR}/src/mabutrace_hooks.h" APPEND)

The trace_task_switch feeds the data into the profiler https://github.com/mabuware/MabuTrace/blob/master/src/mabutrace.c#L330.

While the IDF build is complicated, it seems that this effectively forces all the files in the build to add this include https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html#index-include. This sets the macro for the FreeRTOS compilation.

Even if I don’t use this library directly, this seems like a useful (if possibly brittle) way to customize FreeRTOS beyond what’s available as configuration settings.

One thing to note is that this library uses the Perfetto JSON format instead of protobuf. This means that the way they represent the task core affinity is a bit of a hack.

You can see the core affinity is being shown as “process 2”:

instead of the built-in mechanism that I used in my tests:

While this isn’t quite as nice as having the cores as their own part of the display, it’s a great workaround for getting most of the way there with the much simpler JSON interface.

ESP-IDF Binary Logging Library

In giving a thorough review of all the libraries and features in the ESP-IDF framework, I was surprised to find https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/log.html#binary-logging. This was surprisingly similar to my https://github.com/axlan/min-logger library.

At a high level, its usage is the same as the design I came up with. The code makes normal logging calls that can either emit text like normal logs or packed binary messages with the strings replaced with integer IDs. On the host side, a special tool is needed to convert the binary back to messages and add back in the missing strings from a local repository.

There are some major differences, though. Functionally, min-logger is much simpler with many fewer features. However, it does out of the box support directly logging values and profiling data, while esp-idf logging is really just about generating formatted log messages.

In terms of implementation, the magic to swap out the strings is very different between the libraries. As explained in min-logger, the strings are captured by a Python script that uses a regex to identify the logging calls and capture the strings. The mapping is made by either manually assigning IDs or through a compile-time CRC of source file locations of the log call.

The ESP-IDF logger uses the following macros:

// https://github.com/espressif/esp-idf/blob/master/components/esp_common/include/esp_attr.h
#define _SECTION_ATTR_IMPL(SECTION, COUNTER) __attribute__((section(SECTION "." _COUNTER_STRINGIFY(COUNTER))))

// https://github.com/espressif/esp-idf/blob/master/components/esp_common/include/esp_attr.h
// Forces data to be removed from the final binary but keeps it in the ELF file
#define NOLOAD_ATTR _SECTION_ATTR_IMPL(".noload_keep_in_elf", __COUNTER__)

// https://github.com/espressif/esp-idf/blob/v5.5.2/components/log/include/esp_private/log_attr.h
// Forces a string to be removed from the final binary but keeps it in the ELF file
#define ESP_LOG_NOLOAD_STR(str) (__extension__({static const NOLOAD_ATTR char __f[] = (str); (const char *)&__f;}))

// https://github.com/espressif/esp-idf/blob/v5.5.2/components/log/include/esp_log_attr.h
#define ESP_LOG_ATTR_STR(str)           (__builtin_constant_p(str) ? ESP_LOG_NOLOAD_STR(str) : str)

// https://github.com/espressif/esp-idf/blob/v5.5.2/components/log/include/esp_log.h#L184
#define ESP_LOG_LEVEL(configs, tag, format, ...) do { \
        esp_log(ESP_LOG_CONFIG_INIT((configs) | ESP_LOG_CONFIGS_DEFAULT), tag, ESP_LOG_ATTR_STR(format) ESP_LOG_ARGS(__VA_ARGS__)); \
    } while(0)

What this does is declare the string as an array stored in a noload_keep_in_elf memory section. The pointer to this array is what is logged in the binary message.

Presumably, one of the build steps strips this section when the ELF is being turned into the binary to send to the device.

The monitor Python tool then recovers these strings from the ELF using the pyelftools library: https://github.com/espressif/esp-idf-monitor/blob/master/esp_idf_monitor/base/binlog.py

This is an interesting approach, and I had considered doing something like this before I came up with the CRC approach. It is probably more robust than my regex approach, but it is more complex and potentially less efficient in needing to store and parse the ELF to interpret the logs.

It’s interesting to see another library that achieved the same goals I was trying for. I might use the approach of putting data in a section that is stripped out for future use cases where I want to capture data from the compiler without adding it to the production binary.

Making an Embedded Profiler 2: Minimal Logging Library

Tue, 13 Jan 2026 00:00:00 +0000

I prototyped an embedded logging library. It focuses on flexibility, low resource usage, and compile-time configurability.

The library can be found at: https://github.com/axlan/min-logger/

This is a follow up to Making an Embedded Profiler 1: Surveying Existing Tracing Tools.

I did the development described here shortly after the original article, but didn’t have a chance to write it up until now.

In that time, another developer reached out to me about https://github.com/RTEdbg/RTEdbg which targets a very similar niche to the code I’ll discuss here. I’ve only had a chance to give it a fairly cursory look through, but it seems like a well thought-out project with a pretty end-to-end implementation for several processors. However, its tooling is Windows only and its build systems are all coupled with IDEs, so getting started would require a fair bit of work to adapt to the project structures I’m interested in.

I called my library “min-logger” and focused on making a prototype that would run in Linux and on a PlatformIO Espressif (the WiFi microcontrollers like the ESP32) build.

Design Priorities

Every now and then I find myself looking for a good embedded logging library. Unfortunately, there are a bunch of trade-offs in both resource usage and moving complexity between different parts of the system. For example:

The mechanism for getting the log data off the device can be a serial channel. Here you need to potentially contend with dropped data and initial synchronization. These channels are also often bandwidth limited.
Alternatively, logging may need to be done using a debugging tool like JTAG. This can make things very coupled to the specific processor and debugger (e.g. SEGGER RTT).
It can use up precious storage space to compile in the strings used for logging.
The design of bare-metal, RTOS, and POSIX applications are very different, requiring different log handling.
Often continuous logging is not practical, so logging is only done when a trigger or crash occurs.
Does the logging need to be low latency? How much memory is available for buffering, and what should happen if a buffer fills up?
Different applications will want to log different amounts and types of data. Sometimes this requires instrumenting an RTOS or querying info from the kernel if present.
Different embedded systems have different build tools and compilers, which may limit the standard libraries that can be used.
To minimize resources on the device, context can be kept on the host collecting the log. This can make the host tools more complicated and require pre-build steps to generate files.
The code for calling the log function can be more permissive, or be more explicit and generate compile-time errors if it’s used incorrectly.
Ideally it should be easy to use. Making the logging calls should be simple.

So having a universal logging library is a bit of a pipe dream. Even if a single library did address all the use cases and trade-offs, it would be overwhelmingly complicated. There may be a way to thread that needle, but for now there are lots of small projects in this space that do an OK job at some of these priorities.

So with this in mind, I decided to write my own library that hits the balance that I personally wanted.

Theory and High Level Design

What a Logger Captures

I’ve been particularly interested in making a logging library that didn’t need to send any static strings. For a log message like LOG_ERROR("CRITICAL ERROR"), there’s no information that needs to be conveyed except that the particular error occurred. The severity (‘LOG_ERROR’) and the string message can be inferred by just tracking which log call was triggered.

This means that for a most minimal logging library that could only send static messages like this, the only thing that needs to be logged is an ID that maps to this unique log statement in the code. The host would then have a map of IDs back to their original context and could generate text or other data files with all the details like severity, source file+line, and a string message. This would be limited to very basic logging though.

There are two main kinds of dynamic data that are usually added as part of a log. First, there are the values captured explicitly like: LOG_INFO("temp: %d", temp_val). This example encodes the temperature as a string, though some logs will capture values in more structured ways. The second kind of values are the context that is captured implicitly. For example:

import logging

logging.basicConfig(
    format="%(name)s: %(asctime)s | %(process)d:%(thread)d >>> %(message)s",
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)

logging.error("unexpected error")

captures the logger name, timestamp, process ID, and thread ID:

root: 2023-02-05T14:11:56Z | 428223:128418208166016 >>> unexpected error

Whether the values are captured explicitly or implicitly, I’d at least want a design that has the capacity for capturing dynamic values.

Dividing Up the Design

I’m at the point in my software development journey where it’s hard for me not to overengineer a greenfield project like this. To try to combat this, I like making things modular. It’s still a form of overengineering, but at least it lets me focus on the parts of a project I’m interested in. I can rationalize doing a basic job on the rest with the thought that I could always swap those sections for something better down the line.

I divided up the logging library into the following parts:

Log specification - Any extra information that needs to be defined for the logging to work. For example, data to map enumeration values to log strings or logged data descriptions.
The logging calls - The way that the user code interacts with the library. It needs to be able to pass an ID and values to be logged.
Context generation - This layer adds values for implicit context like thread ID or timestamps.
Serialization - This layer generates the message in memory to send.
Transport - This layer sends out the data to the host.
Host capture - This tool logs the data coming from the device.
Data analysis - These are tools that can process the logs and generate visualization or other artifacts.

I’m primarily focused on layers 2. and 6.. I want to make the logging calls as polished as I can, and I want to be able to use the profiling visualization tool from Making an Embedded Profiler 1: Surveying Existing Tracing Tools.

I’m a bit less interested in 2-4 since these steps tend to be the most platform specific.

To make the design modular, I need to think through what information passes from one step to the next.

Log Specification

The log specification can potentially get the following details from a log ID:

The source file and line the log statement is on
The severity of the log statement
The expected payload size and structure
A string description
Log filter tags. For example, all the logs involved with request handling could have a “requests” tag that could be used for host-side filtering
A format string that references the included payload, or other information (e.g. “Error duration too long. [previous:%u, current:%u]”)
Special handling. For instance, certain log IDs could be reserved for capturing profiling data that would be processed differently from “generic” values
A relationship with other log messages. For example, two logs that captured timestamps could be matched up to compute the delay between them. This is useful for profiling execution times

This information could be its own file, but it could also be inferred from the logging calls implicitly. For example I could use a C parser to find the log calls and record their source location.

Logging Call Design

I want adding log statements to be very low friction, so I want to minimize the boilerplate needed. The logging call could be as simple as:

void log(IDType id, void* data, size_t data_len)

This requires making a concrete choice about the size of the ID. I’ll discuss that a bit later so for now we’ll treat it as its own integer type.

There are a few reasons to make the logging call a bit more complex. First, I initially wanted to make this logging library capable of swapping between minimized binary and full string output. This would be a compile-time macro that would do something like the following:

#define LOG_ID(id, level, msg, payload_type, payload, size)                              \
    if (!DISABLE_VERBOSE_LOGGING && is_verbose()) {                                      \
        log_verbose(id, __FILE__, __LINE__, __func__, msg, level, payload_type, payload, \
                    size);                                                               \
    } else {                                                                             \
        log_binary(id, payload, size);                                                   \
    }

Separately, I also didn’t like that the ID needed to be manually specified. The user would need to keep track of the values used. I wanted to see if I could figure out a way to generate the IDs at compile time.

Context Generation

The context I’m most interested in is a timestamp and thread/task ID.

I didn’t want to spend a ton of time engineering this process so I mostly just made simple solutions for Linux and Espressif.

The main design point I needed to decide was how to log this additional data. To a certain extent this is tied up with the serialization. For example, to minimize bandwidth, the timestamps could be a relative time. If absolute time was needed, a periodic mapping message could be sent.

Similarly, if I wanted to map log messages to named threads, I could publish this mapping periodically or send it with every message. These approaches would be less viable in a system where messages might be frequently dropped.

Capturing this context or sending out periodic messages brings in the potential for processing delays, additional threads, and inter-thread synchronization. The design for a single-core system would be vastly different from one that’s multi-cored.

Serialization / Transport

On the serialization side, there’s tons of design space. In some systems you’d need to work with an existing message framing protocol. Some interfaces are lossy, and some don’t have that concern (UART vs TCP). I make some basic choices for my implementation, but it should be easy enough to swap out for other platforms.

The main thing to figure out is the layer between the serialization and the transport. Ideally, logging should not block on the data waiting to be sent out to the host. In my examples I used existing transport buffers. On a bare-metal system this might be best accomplished by using a ring buffer and setting up DMA.

Host Capture

Host capture can be surprisingly complicated to implement robustly. Some systems have tiny buffers for serial data by default that can silently drop data, and it can be hard to minimize latency if that’s a priority. However, here I’m doing the minimum to dump data to files.

Data Analysis

The most basic design for analysis would be to combine the information from the log specification to the data captured from the host and converting it into a machine-readable format (CSV, JSON, binary structs, etc.). It could involve syncing the data and error correcting, and propagating any persistent state between messages.

For special message types like profiling, visualizations could be built in.

My Implementation

Based on my skill set, I wanted to make a C/C++ library that used Python for any pre-build processing and for analysis. I ended up going through a few iterations as I got far enough to realize that there was a simpler option.

Throughout, I used CMake to manage the Linux build with test examples.

Attempt 1: Generating Helper Functions

My first instinct was to use Python to generate C code that would capture the context for logging with strings. The advantage to generating the code this way was that in code, the log functions could be identified with a string (e.g. “example_temp_error”). The Python code could then turn all the values into numeric IDs that fit in the smallest number of bytes and include these IDs in the generated files.

The code can be found here: https://github.com/axlan/min-logger/tree/gen-helper-file

The CMake would run a pre-build Python command https://github.com/axlan/min-logger/blob/gen-helper-file/cmake/BuildLogger.cmake to generate _min_logger_gen.h

The user would use the MIN_LOGGER_LOG function:

#define MIN_LOGGER_LOG(level, msg, id) \
    if (MIN_LOGGER_MIN_LEVEL >= level) { \
        min_logger_log_func_##id(); \
    }

which would then call the generated code. For example MIN_LOGGER_LOG(MIN_LOGGER_INFO, "hello world", 0); would generate:

static inline void min_logger_log_func_0(){
    if (*min_logging_is_verbose()){
#if !MIN_LOGGER_DISABLE_VERBOSE_LOGGING
        min_logger_format_and_write_log(MIN_LOGGER_NO_TAGS,
                                        "examples/hello_cpp/hello.cpp",
                                        4,
                                        "hello world",
                                        20);
#else
    min_logger_write_msg_from_id("0", "", 0);
#endif
    }
    else {
        min_logger_write_msg_from_id("0", "", 0);
    }
}

I realized as I went to add additional logging functions that it was becoming quite complex to generate all this C code in Python. Naming the log statements actually seemed like more work than giving them a numeric value, so I decided to refactor to drop the whole code generation approach.

Attempt 2: Generating ID from CRC of Source Location

The code for this version can be found here: https://github.com/axlan/min-logger/tree/verbose-logging

I had spent a lot of time brainstorming how to generate a unique ID on the device side that would be possible to determine for the host as well. There are a few macros that are often used for this sort of purpose:

__LINE__ - The line number of the source file the macro expands on. This will have collisions if log statements occur on the same line in different files.
__COUNTER__ - Not part of the C standard, but supported by most compilers. Each time it’s used, it expands to an integer literal one greater than its previous expansion. This would be difficult to predict the value from Python, and could have collisions for code with multiple compilation units.
__FILE__ + __LINE__ - This would be fairly reliably unique, but there’s no simple compile-time method to convert this to an integer.

I am probably overly fond of C++ metaprogramming, and had been contemplating using recursive templating to hash the file+line number at compile time. When I decided to commit to using integers as an ID, I decided to actually implement this approach: https://github.com/axlan/min-logger/blob/master/src/min_logger/min_logger_crc.h

I didn’t want to drop C support, so I made a runtime implementation as well, but it had a few disadvantages.

The code to do the computation uses a lookup table which takes up RAM.
The code needs to run the first time a log is called, adding to the CPU usage.
The logic for caching the ID adds to the complexity of the logging calls.
The strings for the file+line need to be compiled into the program, making it larger.

To avoid these disadvantages, I left the option to explicitly specify the ID. This would also have a use in the C++ code to avoid having an ID change if the code was refactored and a log statement’s source location changed. If the IDs are hard-coded, old logs could be reprocessed without needing to archive or regenerate the log specification associated with that build.

With this approach I finished off the basic features, and was able to get the end-to-end demo I was looking for. https://github.com/axlan/min-logger/blob/master/examples/log_threads/log_threads.cpp could be visualized as:

This version of the library uses a somewhat convoluted system for associating dynamic values with log messages. This has the disadvantage that the overhead of sending a log message needs to be duplicated for each value, but the values can be used by multiple different log statements. Variables are logged in their own log calls, and subsequent log messages can reference them:

MIN_LOGGER_RECORD_STRING(MIN_LOGGER_INFO, "T_NAME", msg.c_str());
MIN_LOGGER_RECORD_VALUE(MIN_LOGGER_INFO, "LOOP_COUNT", MIN_LOGGER_PAYLOAD_U64, i);
MIN_LOGGER_LOG(MIN_LOGGER_INFO, "task${T_NAME}: ${LOOP_COUNT}");

The analyzed logs would be printed as:

14780722.900970 INFO  examples/log_threads/log_threads.cpp:19 thread_id_1] tasktask2: 0
14780722.900990 INFO  examples/log_threads/log_threads.cpp:19 thread_id_0] tasktask2: 0
14780723.901040 INFO  examples/log_threads/log_threads.cpp:19 thread_id_1] tasktask2: 1
14780723.901062 INFO  examples/log_threads/log_threads.cpp:19 thread_id_0] tasktask1: 1
14780724.901795 INFO  examples/log_threads/log_threads.cpp:19 thread_id_0] tasktask2: 2
14780724.901811 INFO  examples/log_threads/log_threads.cpp:19 thread_id_1] tasktask2: 2
14780725.902618 INFO  examples/log_threads/log_threads.cpp:19 thread_id_1] tasktask2: 3
14780725.902661 INFO  examples/log_threads/log_threads.cpp:19 thread_id_0] tasktask2: 3
14780726.903073 INFO  examples/log_threads/log_threads.cpp:19 thread_id_0] tasktask2: 4
14780726.903142 INFO  examples/log_threads/log_threads.cpp:19 thread_id_1] tasktask2: 4

This shows a bug/feature where the variables associated with the log lines aren’t thread specific. You can see that the name for the second thread would sometimes be interleaved with the log line from the first thread. This would be trivial to fix if I made the values thread specific, but the preferred behavior is situational. Ideally, I’d want to be able to specify the behavior as part of the format string.

Attempt 3: Dropping Verbose Logging to Streamline Logging Payloads

The code for this version can be found here: https://github.com/axlan/min-logger/ (I finally spent the time to mostly clean up the documentation)

A lot of the complexity and limitations in the code base were due to wanting to be able to switch between ASCII and binary logs at runtime.

I had decided to support this feature since it made debugging easier, and it was nice to have a mode to get human-readable output directly. However, I decided that improving and documenting the library would be easier going forward if I simplified it to focus on the efficient binary output.

This let me make the interface for logging arbitrary values much more robust:

/**
 * Log a single fixed-size value (C++ only, auto-generates ID).
 *
 * The message ID is automatically generated from __FILE__ and __LINE__.
 *
 * Compile-time constraints:
 * - level must be an integer or priority constant
 * - name should contain only variable-name-valid characters
 * - type must match the actual type of value. If it is not a primitive type, it must be
 *   described in a type_defs JSON file when generating the mapping. The type must be a
 *   plain old data (POD) type with no pointers or references.
 * - value must be a variable that can be pointed to
 *
 * Runtime behavior:
 * - Serializes the value if level checks pass
 *
 * @param level The log level (MIN_LOGGER_DEBUG, MIN_LOGGER_INFO, etc.)
 * @param name  Descriptive name for the value (used in external mapping)
 * @param type  The C++ type of the value (must match actual type)
 * @param value The value to log (type-checked at compile time)
 *
 * Example:
 *   float current_temp = 25.5f;
 *   MIN_LOGGER_RECORD_VALUE(MIN_LOGGER_WARN, "cpu_temp", float, current_temp)
 */
#define MIN_LOGGER_RECORD_VALUE(level, name, type, value)                 \
    {                                                                     \
        PRIVATE_MIN_LOGGER_LOG_MSG_GEN_ID(MIN_LOGGER_LOC);                \
        MIN_LOGGER_RECORD_VALUE_ID(min_log_id, level, name, type, value); \
    }

/**
 * Identical to MIN_LOGGER_RECORD_VALUE at runtime. The difference is that this macro
 * provides context for tools that extract log metadata to generate a message when this
 * value is sent. In the msg, use ${VALUE_NAME} to reference this or previously logged
 * values.
 */
#define MIN_LOGGER_RECORD_AND_LOG_VALUE(level, name, type, value, msg) \
    MIN_LOGGER_RECORD_VALUE(level, name, type, value)

Now arbitrary data types can be logged, and if a log message should be printed each time a value is sent, this can be done with a single logging call. I also added the capability to save the recorded values to *.csv files.

I supported this by making a quick and dirty JSON data type description format. This file is a dictionary of custom or ambiguous types to Python struct format string values. These can reference other definitions in the file or C primitives. Struct formats must be a number of repetitions and a single value character. Custom types can also start with a number of repetitions for fixed-size arrays.

Example:

{
    "int": "i",
    "Point": {
        "x": "f",
        "y": "f",
        "dummy": "2i"
    },
    "Rect": {
        "pos": "Point",
        "size": "Point",
        "padding": "10x",
        "str": "10s",
        "bytes": "10s"
    }
}

See https://github.com/axlan/min-logger/tree/master/examples/custom_type for a full example.

One last feature I added was a tool for cross-checking these type definitions with the structures as defined by the compiler. The easiest way I could think of was using the debugger to print the size of the type:

gdb build/examples/custom_type/custom_type -X "print sizeof(Rect)" 

I made a Python script to automate this cross-check: https://github.com/axlan/min-logger/tree/master/python/src/min_logger/validate_types.py

Serialization and Transmission Limitations and Improvements

The library has two serialization approaches built in. The default format (MIN_LOGGER_DEFAULT_BINARY_SERIALIZED_FORMAT / BINARY) isn’t optimized for any particular application, but would be reasonably robust to send over a UART interface. The micro format (MIN_LOGGER_MICRO_BINARY_SERIALIZED_FORMAT / MICRO_BINARY) is pretty minimal while still being suitable for multi-threaded execution profiling.

It is trivial to use a different scheme on the device side. However, it would be somewhat complicated to add new formats to the Python parsing tool.

The Python parsing tool is extremely inefficient. The message framing and decoding of any complex values is done naively in the Python code. If I wanted to support parsing large amounts of data, I would probably choose a dedicated compiled framing tool to sync and drop corrupt data. Then I could use a more well-supported deserialization tool like Kaitai.

On the device side, I’ve mostly been relying on directly passing the data to the output with syscalls. This may add significant overhead to the logging calls. It would be fairly trivial to buffer the transmissions before the calls that may block on a separate thread. I plan on setting something like this up when I make a non-trivial use of this library.

Conclusion

This library reached the level of capability I wanted for a real project.

On the other hand, I made a bunch of choices that met my preferences, but might be baffling to anyone looking to use it.

Some notable decisions:

Using macros (instead of functions) to allow auto-generated enums in C++
Using Python regexes to scan the C/C++ macros to record the metadata
Using the uv tool to orchestrate Python scripts in the glue logic
Focusing on passing the thread ID in the serialization and analysis

Fatal Core Dump Game

Wed, 07 Jan 2026 00:00:00 +0000

I decided to make a somewhat educational murder mystery game, with debugging a core dump as the main piece of evidence.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
THIS ARTICLE HAS SPOILERS! IF YOU’RE INTERESTED, PLAY THE GAME HERE FIRST:
https://www.robopenguins.com/fatal_core_dump/

All the code for this game can be found at: https://github.com/axlan/fatal_core_dump

Over the years, I’ve seen a couple of murder mysteries used to teach the basics of different software skills:

CLI Murder Mystery
SQL Murder Mystery
I never wrote it up, but https://deadlockempire.github.io/ is another fun entry in this genre

As a thought experiment, I tried to come up with the most esoteric computer skill I could package into a murder mystery. I came up with debugging a core dump.

Brainstorming

I’ve talked about core dumps before: Making Core Dumps Useful. I found the idea that an entire mystery’s worth of twists and turns could be captured in a program’s dying breath to be compelling.

Initially, I wasn’t sure what kind of clues could be hidden. If the killer’s name was just sitting in an access log, that wouldn’t be particularly interesting. I knew I would need some sort of framing around the game so I could split information between the core dump itself and other sources.

One of my first thoughts was that as you found answers to certain questions, you might gain access to additional source code or databases to query.

My main inspiration was the way the mysteries worked in the games Return of the Obra Dinn and The Case of the Golden Idol. Both have you exploring frozen scenes and uncovering clues that reframe the evidence you’ve already collected.

Pretty early on, I settled on an airlock door controller as the program at the center of the mystery. It had a reasonable amount of complexity while also having obvious potential for murder.

From there, I decided to use a sci-fi setting. The idea of a “company town” in space, using third party arbitration, jumped to mind. This helped provide motivations and justified limiting the player’s access to information.

Writing the Airlock Controller

Once I had the basic idea, I decided to actually write a simple airlock controller. I wanted to keep things as minimal as possible, so I wrote a C library with minimal dependencies. This may seem backwards, since I hadn’t decided on all the details of the mystery yet, but I felt it would be easier to make something feel realistic if the software wasn’t designed primarily as a puzzle.

One challenge I realized right away was that I needed a way to set up the program state so it would look exactly the way I wanted when it generated the core dump.

Initially, I considered having the process communicate with various sensors and servers. After some thought, though, I realized it would be simpler to send all external interactions through a library whose internals I could hide. Any dynamically linked libraries would be unavailable to the debugger unless I explicitly included them.

In this project, the libraries used to generate fake interfaces that I didn’t want the player to see live in https://github.com/axlan/fatal_core_dump/tree/v0.1.2/lib, while the only source code I intended players to examine is https://github.com/axlan/fatal_core_dump/blob/v0.1.2/src/airlock_ctrl.c.

I think I went a bit overboard with the communication interface. I ended up writing an entire binary protocol for an imaginary “Station Device Network” (SDN) used for inter-device communication. In retrospect, I probably should have planned this better. It made some things needlessly complicated since I didn’t yet know the extent of what I’d want it to do.

That said, this approach let me write the main controller as a loop waiting for messages on the SDN interface. I could then write the SDN library to generate the precise sequence of messages needed to set up the murder. While I considered reading these sequences from a text file, I ultimately cut out the middleman and hard coded them directly in C. See: https://github.com/axlan/fatal_core_dump/blob/v0.1.2/lib/sdn_interface.c#L523

This let me create test scenarios to validate “normal” behavior, as well as capture the exact state I wanted in the core dump.

Figuring Out the Mystery

At some point while writing the controller, I decided I wanted the murder to be committed by abusing a buffer overflow to trigger the airlock.

I wanted a balance between negligence on the part of the software designer and the cleverness of the murderer.

This sent me down a series of twists and turns to make the attack plausible while still being solvable via a core dump.

The first challenge was making the buffer overflow less obvious. I solved this in two ways:

Obfuscating the buffer size check
Having the attack “hide” in memory until a separate trigger was reached

To obscure the bounds check failure, I made the buffer size a configuration parameter used at startup to allocate the buffer. I then added a debug command that could modify the configuration variable without resizing the buffer. I gated this behind multiple debug options to justify why it wouldn’t be enabled in production.

From there, I wrote a series of small test programs to prototype the exploit: https://github.com/axlan/fatal_core_dump/tree/v0.1.2/minimal_example

To keep the exploit dormant until later, I initially explored self-modifying code (see https://ephemeral.cx/2013/12/writing-a-self-mutating-x86_64-c-program/ for a basic example). This approach had several drawbacks. First, it would cause the binary seen in the debugger to differ from the runtime version. While the core dump could technically capture this, I wanted to keep things as realistic as possible. Second, it would require making program memory writable via a system call (see https://github.com/axlan/fatal_core_dump/blob/v0.1.2/minimal_example/vuln_test3.py). At that point, I realized there was a more fundamental problem.

My initial idea involved return-oriented programming (ROP): https://tc.gts3.org/cs6265/tut/tut06-01-rop.html. This relies on overwriting a return address on the stack, which only works if the stack is executable and other defenses are disabled. However, this is totally a non-starter for overflows on the heap. I couldn’t easily justify a stack overflow in an otherwise competently written program.

However, I realized that if a heap overflow corrupted a callback pointer stored on the heap and pointed it to attack code stored on the stack, I could get the effect I wanted. If the stack memory persisted across messages, I wouldn’t need to write into program memory at all. After some experimentation, I arrived at https://github.com/axlan/fatal_core_dump/blob/v0.1.2/minimal_example/min_poc.c paired with https://github.com/axlan/fatal_core_dump/blob/v0.1.2/minimal_example/vuln_test5.py.

In the end, the attack looked like this:

    ; This is needed to align the stack to a 16 byte offset.
    ; I don't update the rbp since it interferes with the core dump's backtrace.
    push    rbp
    movabs  r15, ADDRESS_OF_HANDLE_MESSAGE_CALLBACK
    mov     r12, rdi
    add     r12, OFFSET_TO_USER_ID_VALUE
    ; Check if the message was sent by the murder target
    ; If it's not from the target skip to ".L_skip"
    cmp     DWORD PTR [r12], USER_ID_OF_TARGET_FOR_MURDER
    jne     .L_skip
    ; Save the parameters passed to this function
    mov     r12, rdi
    mov     r13, rsi
    mov     r14, rdx
    ; Call the ControlDoor function to open the outside door
    movabs  rax, ADDRESS_OF_DOOR_OPEN_FUNCTION
    mov     edi, DEVICE_ID_FOR_AIRLOCK_CONTROLLER
    mov     esi, DEVICE_ID_FOR_OUTSIDE_DOOR
    mov     edx, 1
    call    rax
    ; Restore the original callback to erase this hack
    mov     rax, THE_HEAP_ADDRESS_FOR_CALLBACK_POINTER
    mov     qword ptr [rax], r15
    ; Restore the parameters to call the message handler normally
    mov     rdi, r12
    mov     rsi, r13
    mov     rdx, r14
.L_skip:
    call    r15
    pop     rbp
    ret

While it would have been ideal to make this work under fully realistic OS protections, I chose simplicity. I built the binary with extra compiler flags -fcf-protection=none -z execstack to make the stack executable and turn off some protections. Second, when I ran the executable I would do so like: env -i setarch $(uname -m) -R $PWD/bin/min_poc .

env -i cleared the environment variables so the memory offsets weren’t affected by them
setarch $(uname -m) -R turned off the address space layout randomization so memory would be laid out consistently
Calling the executable with the absolute path also helped keep the memory offsets consistent between calling from the shell, and calling in GDB.

On the GDB side I just needed to call set exec-wrapper env -i to clear the environment variables. I would use GDB to find the memory offsets I’d be using in the hack, and hard code them.

Once the mechanics were settled, I refactored the airlock controller to support this scenario. This required a few unrealistic memory layout decisions, but nothing too too crazy.

The final piece was justifying the crash that produced the core dump. I decided the murderer would trick another person into loading malicious data into their spacesuit. If the data payload was unusually large, it wouldn’t be overwritten by subsequent users. I justified copying this data to the stack by having the airlock forward this data to the suit. Because the stack buffer didn’t go out of scope, it was suitable for storing the attack.

To create an in-fiction reason for the crash, the patsy unexpectedly modifies the data, overwriting the code with actual settings data. I spent far more time than was justified making this feel plausible.

I wrote a final script to generate the attack payload: https://github.com/axlan/fatal_core_dump/blob/v0.1.2/scripts/generate_shellcode.py . The exploit is appended to a settings string and partially corrupted by the overridden field.

Here you can see the intact payload and the version overridden by a “bass volume” setting:

Making an RPG Maker Simulation

I originally wanted the game to be more interactive, with dialogue trees and a graphical interface. While a website was the most accessible way to present the puzzle, I still wanted a small visual component. I ended up creating a simple pixel-art demo to illustrate the airlock and sequence of events of the murder.

You can play this “game” at https://www.robopenguins.com/fatal_core_dump/rpg_maker/index.html and the source code is available at https://github.com/axlan/fatal_core_dump/tree/v0.1.2/rpg_maker_project.

I had a free copy of RPG Maker and thought it would be a good tool too make this. It was, but it has a strange learning curve. It’s trivial to make a basic RPG with the built-in assets, but trying to program complicated events or making your own assets introduces a lot of gotchas. Overall, it was probably slightly easier than using a general-purpose engine. I used a single plugin https://someran.dev/rpgmaker/plugins/mz/SRD_HUDMakerUltra.js/ to display console logs.

Most of the logic lives in the event system, which took some time to understand. Events are tied to map tiles, and behavior is controlled via event pages with AND-ed conditions. The highest-numbered matching page wins. It was oddly reminiscent of a Zachtronics game.

I spent the bulk of my time here on pixel editing. I started from https://pvgames.itch.io/pvgames-sci-fi tile assets, but had trouble finding “compatible” pixel art. I ended up making a whole sprite sheet for a space suit using aseprite along with a bunch of other small tweaks.

Debugging Without GDB on Your PC

One stretch goal was allowing the puzzle to be solved entirely in the browser. That required running GDB on the core dump in a web environment.

I found https://github.com/leaningtech/webvm which let’s you emulate a full virtual machine in the browser. I forked it and modified a Dockerfile to include the core dump and install GDB: https://github.com/axlan/webvm/blob/fatal_core_dump/dockerfiles/debian_mini.

I spent a bunch of time trying to get pwndbg working in the VM. Unfortunately, it ended up being too big to easily fit in the image.

You can try it out here https://axlan.github.io/webvm/.

Putting It All Together

With the main artifacts done, I had to put it together into a playable puzzle.

I initially tried to put the information together diegetically. I presented the information through things like emails or data sheets. Eventually, I ran out of steam and most of the evidence is simply presented as downloadable files.

To be able to consistently generate the logs and core dump, I ended up wrapping the build and runtime scripts in docker containers. That way I could just run the https://github.com/axlan/fatal_core_dump/tree/v0.1.2/scripts/docker_generate_site.sh to generate all the programmatic clues for the project. I considered using a GitHub action, but stuck with just running the scripts locally.

I ended up writing a lot of filler to act as red herrings. I’m not sure I made enough though, since pretty much all the logs are relevant to the murder. It was hard to balance forcing the player to sift through a bunch of pointless filler and effectively hiding the evidence.

One especially tricky page to design was the one used to validate whether the player had solved the puzzle. I wanted a series of questions that would demonstrate the player’s understanding of the technical mechanisms behind the murder. I implemented this as a set of fill-in-the-blank questions, populated via an autocomplete dictionary. My concern is that this approach may require players to phrase their answers in their minds too similarly to my own in order to fill in the blanks correctly. I’m hoping to get feedback on whether these questions are easy to complete once the puzzle has been solved.

I’m not a frontend guy, so that’s probably the weakest part of this project. With more time I could probably improve the presentation of the clues and the solutions entry. If I manage to get sufficient interest in this, maybe I’ll go back and try to polish things up.

Traffic Costumes

Tue, 11 Nov 2025 00:00:00 +0000

For Halloween this year, my family went as traffic controls. In particular, I made a traffic light costume that changes color based on my daughter’s movement.

Here’s the full family:

and here’s the traffic light in action:

All code for this project can be found at https://github.com/axlan/traffic-light-costume.

In the end, I basically made a low power and cost GPS position logger with a few costume specific features.

Making the Stop Sign Costume

Cut up some cardboard boxes into half octagons
Taped them together
Painted them red
Printed and cut out the letters using the font “Highway Gothic Narrow”
Glued the letters on
Made a border with white tape
Attached straps using bungee cords

Making the Traffic Light Costume

My original idea was to use an accelerometer to determine when the lights should change. My hypothesis was that I could use the magnitude of the x, y, z acceleration as a rough proxy for movement. When walking there’s a lot of up and down movement that would probably be sufficient to discriminate between moving and standing still.

I did some prototyping using an Arduino and an old IMU. I was disappointed that it didn’t just work and there was no response from the IMU. Rather than spend a bunch of time debugging the SPI interface, IMU driver, and the hardware, I decided to go with a backup approach.

Testing the GPS Receiver

I had gotten a u-blox GY-NEO6MV2 GPS receiver (or probably a clone) for a couple bucks a while back. These modules communicate using the NMEA protocol over UART, which makes it straightforward to read velocity. This also meant I could log position and generate a map of the trick-or-treat route. This does come at the cost of not working indoors, and not working well if there isn’t a clear view of the sky.

The first thing I did was configure and test the GPS receiver by itself. I used a USB-to-TTL adapter to connect the receiver directly to my computer and the u-blox GUI u-center to get status and configure the unit. I changed the UART baud rate and customized the messages the receiver would send.

To test it “in the field”, I stuffed it into a box and used an Arduino as a power supply.

I took it for a walk to get a sense of how well it would work in trick-or-treat conditions. It performed reasonably well. Positions would jump if houses or trees blocked the sky, but the velocity was stable enough when averaged over a few seconds.

Building the Costume Circuit

For the version that went in the costume, I wanted to use an Arduino Nano. They are small and low-power, and I had one on hand. I found some older boards had inconsistent support in current Arduino tools and documentation. I had trouble finding schematics and documentation on which pins were associated with the SPI interface.

Getting the GPS talking with the Arduino was straightforward using a software serial port (there was only one hardware UART, which I used for debugging). I initially used the TinyGPS library, which made basic verification easy. The baud rate I used for PC testing, 115200, was far too fast for the Arduino’s SoftwareSerial port. It constantly dropped data, so I switched down to 9600 baud.

Similarly, getting the SD card working was simple; the built-in SD card library worked out of the box.

While I originally considered making the costume from scratch, that wasn’t the part I was most interested in. Building something sturdy enough to wear is its own challenge (foreshadowing for later problems), so in the end I bought a costume for $30. The original costume had a control box for the lights with a connection for each light and a common ground. A little testing showed the box was just directly wired to the LEDs, and the LEDs drew low enough current that I could drive them with Arduino GPIO pins using a 500 ohm resistor in series for each LED.

While getting each component working individually went smoothly, I spent a lot more time than expected integrating everything.

The first issue was that the Arduino wasn’t fast enough to log the raw GPS NMEA data to the SD card. To improve efficiency, I cached position and speed (updated once per second) and performed bulk writes every 30 seconds.

Even with reduced write frequency, I still saw unexpected crashes. My best guess was that memory usage between the GPS, software serial, and SD libraries was too much for the small processor. I wrote a minimal NMEA parser that only handled the one message I needed (RMC). With that, I was able to write firmware that handled the costume’s complete functionality.

The final firmware is the PlatformIO project at https://github.com/axlan/traffic-light-costume.

With the hardware assembled, I put it all together:

I powered everything from a USB battery pack. I had a large one that reported nearly no drain after running for a couple of hours.

Once assembled, I started noticing power-related issues. The SD card would often fail to be detected. After debugging, I realized the VIN pin on some Arduino Nano boards couldn’t supply enough current for the GPS and SD card. Something in the onboard power conditioning couldn’t handle the load. Powering the SD and GPS directly from the USB 5V line fixed the issue.

As I mentioned earlier, I did have some durability issues with the costume. Some of the cabling between the Arduino and the GPS proved fragile and occasionally needed to be wiggled to restore the connection. In hindsight, I should have kept the GPS closer to the microcontroller rather than mounting the receiver up near the top for a better antenna vantage point. A shorter, more secure cable run or a sturdier connector would have been a better choice. Fortunately, it held together for the actual trick-or-treating run.

Processing the Data

The data is logged if a FAT32 formatted SD card is in the costume when it boots. It creates filenames like “log000.bin”, “log001.bin”, etc. each time it powers up. Each binary file contains latitude, longitude, and velocity as four-byte floating-point values.

I created a Jupyter notebook (https://github.com/axlan/traffic-light-costume/blob/master/python/analysis.ipynb) to load the data and generate plots and maps.

Eye Chart With Hidden Message

Thu, 02 Oct 2025 00:00:00 +0000

A wedding gift for my brother. I wanted to make something that didn’t rely on electronics, but was still an original idea. So I made an eye chart that folded into a secret message.

Brainstorming

Since my brother is an eye doctor, I immediately thought about different sorts of optical illusions. I wanted to make something that would contain a “secret” message. Some mechanisms I considered were:

Ishihara test

Hidden Color Decoder Glasses

Shadow Sculptures

Hidden QR code

In the end, I decided to go with the iconic Snellen Eye Chart.

Designing the Chart

While I could simply make the letters in the chart contain a message, I had the idea that the chart could be a Triptych (a three-panel artwork) showing the message when the sides fold shut. I’d do this by having the letters be cut through the design and have the letters seem random when seen from the front, and make the message when they flip over. My familiarity with laser cutter design is why I decided to go with this.

This meant that I had to design the letters so that they would spell the message when flipped horizontally. I used a few different techniques to get the letters I wanted when the Triptych was folded shut. I could use letters with vertical line symmetry directly (H, I, O, etc.). Some letters looked a little like others when flipped (Z→S, q→p). But for other letters, I needed a way to add and subtract lines. To do this, I made the front and back use two different colors. That way I could draw the lines to add on the back, and overlap with the lines I wanted to remove. See below:

I considered a few different quotes and messages to put into the chart, mostly from movies or songs the couple shared. I ended up choosing one partly because the letters were relatively easy to flip.

What do you expect? To live happily ever after? Yes.

The Parent Trap 1998

Now that I had my work cut out for me, I wanted to automate the design layout as much as possible. I considered adding scripting to Inkscape, but decided the easiest approach would be to use the SVG manipulation library https://github.com/cduck/drawsvg and make a Python Jupyter notebook.

You can see what I ended up with here: https://github.com/axlan/word_triptych/blob/master/draw.ipynb

Originally, I planned to fill the entire chart with letters and control the overlapping by subtly offsetting the letters. Once I started experimenting, I decided to make my life easier by doing a layout with large gaps, and drawing an image through the center that would create the desired overlaps.

Another decision I made to simplify things was to use a monospaced font. This made calculating the spacing a lot easier. Another requirement for the font was that the letters could be cut out. For letters with internal shapes (like A, B, P, etc.) the font would need bridges to look right. Initially, I considered a bunch of stencil fonts. However, these tended not to be as clear at the various sizes. In the end, I started with “Ubuntu Mono” and edited it with a program called FontForge. I followed this tutorial https://www.youtube.com/watch?v=ch8KuiABczo. While the changes I wanted were pretty basic, I found the process a bit finicky. I also found that Inkscape was very inconsistent about reloading the font after I made changes and reinstalled it https://gitlab.com/inkscape/inbox/-/issues/12513.

Since it’s an eye chart, I wanted to include the vision acuity values for each row. I started from these eye chart values and came up with values between 20/162 and 20/54 when I measured the sizes the letters scaled to on the final design.

After a few iterations of arranging the letters, I ended up with the following “simulation”. When making a design for a laser cutter, each color represents a different sort of cut. I used black for things that should be cut out, and red for lines that should be engraved.

Cut SVG:

Fold Simulation:

While trying to export the SVG for this write-up I hit a weird SVG issue. I originally wanted to post the actual SVGs, but to have it look right it would need to have my custom font available. I tried to host the file on this blog and have the SVG import it, but I hit a series of issues. First, viewing it locally was giving CORS errors. When I fixed that, the SVG would look OK when viewed on its own, but when it was embedded on this blog page, the custom font didn’t work. Rather than continuing to fight this, I’m just using raster images.

From these generated files, I still needed to do some manual steps. I used Inkscape to draw a flower over the regions that would need overlaps. To avoid any potential issues with the font, I also converted the text to shapes.

Building the Chart

While I have a laser cutter, this would be a bit too large for my device. Initially, I wanted to use a local maker space, but after doing some research I found a local shop that could cut all sorts of materials for less than the monthly membership. I ended up going with 1/8in MDF which cost $60. Initially, I was worried that the MDF might swell at the edges when I painted it, but it turned out fine in the end.

After a couple days, I got the cut back:

It was only at this point that I planned out the rest of the steps to paint and finish the design. I got some primer (Kilz original), some house paint samples, and a clear coat for the finish. I also got some hooks for hanging, and some small hinges. I painted the background coats with a small paint roller, but realized that it was going to be a pretty tedious process to paint the engraved letters and the flower in the middle. In retrospect, I should have done a raster engrave for these shapes instead of the vector outline engraving. Painting by hand would have been easier, and I could have even tried a powder coat paint https://www.youtube.com/watch?v=5slQcAI2WSw. I ended up needing to do three or more coats and even then it wasn’t particularly even.

As a flourish, I used gold leaf for the bride and groom names on the front. This turned out to be a bit of a pain since the leaf stuck a bit to the paint and didn’t come off cleanly. I managed to get a system of using a razor and painter’s tape to more cleanly lift off the excess.

For the portions being added to the flipped letters, I used painter’s tape to mask on the extra lines.

After some touch ups, I put on the clear coat and added the hinges.

In the end, while it came out pretty well, the “subtractive” part of the design isn’t as strong an effect as I would have liked. It works when looked at closely, but from further away, the shadow of the closed panel partly obscures the color matching.