xythobuz.de Blog

Glove80 USB Dongle

Wed, 29 Jul 2026 12:00:00 -0000

For about three years, since September 2023, my daily-driver keyboard has been the Glove80. It has always worked great, with the only downside being the battery life of the left half, which is much shorter due to it being the BLE central, the right half only operating as BLE peripheral.

The manufacturer often mentioned it is possible to use a dongle to avoid that problem. But many people struggle to get that working.

So here is how I did it and how you can replicate it.

Quick Start

You need to buy an nRF52840 Dongle, aka. PCA10059, from Nordic. You can check their website for distributors. Other dongles or microcontroller boards can work as well, but then you need to make your own config.

Download the latest pre-built binaries from my GitHub releases.

Release builds for glove80-dongle are available on GitHub.
Latest release of glove80-dongle: Custom ZMK with USB HID multi-battery reporting (2026-07-24 13:34:13)
(at the time of this writing)

Release Assets:

dongle_fw.zip (290 KiB)
glove80_custom-glove80_lh-zmk.uf2 (390 KiB)
glove80_custom-glove80_rh-zmk.uf2 (390 KiB)
glove80_custom.settings_reset-glove80_lh-zmk.uf2 (127 KiB)
glove80_custom.settings_reset-glove80_rh-zmk.uf2 (127 KiB)
glove80_dongle-nrf52840dongle__zmk-zmk.bin (290 KiB)
glove80_dongle.settings_reset-nrf52840dongle__zmk-zmk.bin (103 KiB)

You need dongle_fw.zip to flash to the PCA10059 board. The glove80_custom-glove80_X-zmk.uf2 files need to be flashed to the left and right half of the keyboard. When you switch from a config without a dongle to one with, or vice-versa, you need to flash the settings_reset firmwares in between.

To enter the Glove80 bootloader of the left half, turn it on while holding the MAGIC and E keys. For the right half it's PgDn and I. You can then simply drag-n-drop the corresponding .uf2 file to the removable drive that appeared.

If you haven't already, prepare nRF Util. In this example I install to ~/bin, which is in my $PATH.

wget -O nrfutil https://files.nordicsemi.com/ui/api/v1/download?repoKey=swtools&path=external/nrfutil/executables/x86_64-unknown-linux-gnu/nrfutil&isNativeBrowsing=false
chmod a+x nrfutil
mv nrfutil ~/bin
nrfutil install nrf5sdk-tools
nrfutil install device

To enter the dongle bootloader, stick it into a USB port and press the RESET button. Then flash the dongle_fw.zip.

nrfutil device program --firmware dongle_fw.zip --traits nordicDfu

If you ever need to reset the settings of the dongle, convert the .bin to a .zip first.

nrfutil pkg generate --hw-version 52 --sd-req=0x00  --application glove80_dongle.settings_reset-nrf52840dongle__zmk-zmk.bin --application-version 1 dongle_reset.zip
nrfutil device program --firmware dongle_reset.zip --traits nordicDfu

As mentioned above, when doing this initially you need to reset the settings of the two previously paired halves first, to clear the cached bluetooth pairing keys. Then plug in the dongle with its new firmware and turn on the two keyboards with their new firmware. They will automatically pair and everything should just work™, as usual with ZMK.

Software Implementation

As a first step I've taken a look at the ZMK documentation. They have a great guide for configuring dongles. I also searched GitHub and found "zmk-dongle-config" by stammy, which also seems to be based on the Glove80.

The repo stops halfway short, when building I got a firmware build that properly paired the two peripherals to the central. But it didn't know how to interpret the keypresses, as the layouts were missing. So finishing according to the documentation, I had a working keyboard.

At this point I need to mention the differences between upstream ZMK and the MoErgo fork. The stock Glove80 firmware uses the RGB per-key backlight to indicate status information like the battery level and BLE profiles. This is not supported in the upstream ZMK firmware. Even following the ZMK guide I was not able to get the MoErgo fork to build for a dongle.

But even though I was not expecting the RGB indicators to work on my upstream ZMK build, at least the RGB backlight animations should have worked, but didn't. An issue by Samsuper12 brought me on the right track for that. The dongle device tree also needed RGB backlight configured. So I copied the corresponding nodes from the Glove80 device tree, and then RGB backlight was working as well.

This only left the problem of not seeing the battery level of the keyboard now. ZMK supports reporting battery levels, but only via BLE. Fortunately there is a pullrequest that implements battery level reporting via USB HID, and there even is a branch by "zampierilucas" that implements multiple battery levels for Linux >= 7.2. I simply rebased that on the current ZMK upstream master, which worked without any conflicts.

Hardware

The dongle is plugged into an ugly hack consisting of two portable USB hubs, hidden behind my display, connected to my PC using a USB extension. This has been holding my webcam, AutoBrightness and a Logitech dongle. And now this keyboard dongle as well.

The 3D printed case is "nRF52840 Dongle case with Button accessible" by janxgeist. Though I actually didn't end up using it.

Logging Battery Levels

Based on the idea from this blog post I wrote a shell script that reads available battery states from /proc and outputs it for Influx in line-protocol format.

#!/bin/bash

for d in /sys/class/power_supply/*/ ; do
        # ZMK etc.
        if [ -f "$d/capacity" ] && [ -f "$d/status" ] && [ -f "$d/model_name" ] && [ -f "$d/type" ] ; then
                CAPACITY=`cat "$d/capacity"`
                STATUS=`cat "$d/status"`
                MODEL=`cat "$d/model_name" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                TYPE=`cat "$d/type" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                DIR=`basename "$d" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                echo "battery,name=${MODEL},type=${TYPE},protocol=HID,path=${DIR} capacity=${CAPACITY}i,status=\"${STATUS}\""
        fi

        # Logitech HID++
        if [ -f "$d/capacity_level" ] && [ -f "$d/status" ] && [ -f "$d/manufacturer" ] && [ -f "$d/model_name" ] && [ -f "$d/type" ] && [ -f "$d/serial_number" ] ; then
                LEVEL=`cat "$d/capacity_level"`
                STATUS=`cat "$d/status"`
                MANUFACTURER=`cat "$d/manufacturer" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                MODEL=`cat "$d/model_name" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                TYPE=`cat "$d/type" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                SERIAL=`cat "$d/serial_number" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                DIR=`basename "$d" | sed 's/ /\\\\&/g' | sed 's/,/\\\\&/g' | sed 's/=/\\\\&/g'`
                echo "battery,name=${MANUFACTURER}\ ${MODEL},type=${TYPE},protocol=HID++,path=${DIR},serial=${SERIAL} level=\"${LEVEL}\",status=\"${STATUS}\""
        fi
done

Here is some example output.

 $ batteries.sh
battery,name=ZMK\ Project\ G80\ Dongle,type=Battery,protocol=HID,path=hid-XXX-battery-5 capacity=91i,status="Discharging"
battery,name=ZMK\ Project\ G80\ Dongle,type=Battery,protocol=HID,path=hid-XXX-battery-6 capacity=75i,status="Discharging"
battery,name=Logitech\ MX\ Ergo\ Multi-Device\ Trackball\ ,type=Battery,protocol=HID++,path=hidpp_battery_0,serial=XXX level="Normal",status="Discharging"

I stored this in /usr/local/bin/batteries.sh and set the executable-bit.

Using a small telegraf config snippet my desktop PC will call this shell script and write the output to my Influx DB.

[[inputs.exec]]
  commands = [ "/usr/local/bin/batteries.sh" ]
  data_format = "influx"
  interval = "60s"

This is then visualized, as usual, in my Grafana dashboard.

In 5 days since installing the script both peripheral batteries have gone down by around 2%.

So it looks like the promised reduction in energy usage was true. Previously, the right half (peripheral) had a runtime of a couple of months. The left halt (central) had a much shorter battery life, of a couple of weeks maybe. It should be mentioned, I never turn the keyboards or my desktop PC off.

Now the left half seems to have similar battery life as the right half, as they both act as peripheral. The "large" energy consumption is in the central, which is now powered via USB from the desktop.

Logitech MX Ergo switch replacement

Mon, 27 Jul 2026 12:00:00 -0000

After using a Logitech M570 trackball for a while I switched to their MX Ergo model while the pandemic was going on. I've been pretty happy with it, but after around three or four years, it had now developed the "doubleclick issue". Apparently it's a common problem with these devices. In my case, the switch in the left mouse button started to register false clicks when holding it down. This caused drag-and-drop or selecting text to become pretty much impossible.

To disassemble the device you can follow this great iFixit guide, but it's pretty easy and well constructed, so you'll find your way around.

The most important part is unscrewing all the torx screws in the bottom, then sliding a prying tool under the right button, and unclip the two shells all the way around, until you arrive at the left button or they pop open.

I was very surprised about the ridiculous amounts of cat hair that had built up. Even though the encoder slots in the mouse wheel were pretty much invisible, it didn't seem to interfere with anything. Of course I gave it a thorough clean.

From research I assumed that the low-force variant, OMRON D2F-01F would be the correct replacement. But turns out, the original ones are OMRON D2FC-F-7N (10M). So if you care to have an exact replacement, make sure to get these. Some people also recommend Kailh GM8.0 as a replacement.

Even though I've got the "wrong" type, D2F-01F, I only replaced the left button. It works properly now, but you can hear and feel the difference between the left and right side. I don't really care, to be honest, so I'll probably just leave it like that.

Unsoldering the original switch is a bit tricky. I used solder wick to get rid of most of the tin, then heated each of the three switch pins, one after the other, while pressing down on them to get the switch to move a bit. Then I could get a small screwdriver between the switch and PCB, to pry a bit more, while still heating the pins. When there was enough space, I simply cut off the pins near the switch housing. Then the remaining pins can be easily unsoldered. The large ground pad is a bit tricky, due to high thermal mass. Make sure not to rip off the pad with too much force or heat.

I also noticed that the switches themselves can be disassembled, they have small plastic latches on two sides. So if you really want to, you could also try to clean the contact surfaces, instead of replacing the whole switch.

Dry Filament Storage

Sat, 18 Jul 2026 12:00:00 -0000

For years the filament roll for my 3D printer has just been hanging from the front of my Lack tower. As I also often have long stretches of time where I don't use much filament, it tends to draw moisture from the air. This reduces print quality, so it's recommended to keep the filament dry.

So I finally decided to upgrade my printing situation by adding an air-tight container for the filament roll, with a bowden tube running to my direct-drive extruder.

The 3D printed coupling mount on the extruder is "Sherpa Mini PTFE Coupler Holder (Reverse Bowden, PC4‑M10 coupler)" by sulli18.

I really like the cheap chinese box. The kit already comes with everything except the bowden tube. The filament rolls smoothly on bearings and it even includes a humidity meter.

Part	Cost
3D Printer Filament Dry Box Storage Hot-Air Heating Storage Printing Material Holder Moisture-Resistant for Filaments Dryer Box	16.49€
Blue/Orange Indicating Silica Gel Desiccant Beads，Reusable Moisture Absorber for Storage，Closets，Electronics，3D Printer Filament (Blue-9oz)	7.09€
Ultra-Smooth PTFE Tube for 1.75mm filament with Cutter for Extruder,2.5mm IDx4mm OD Length Tube for Bambu Lab A1/P1P/P1S/X1C (White 4M cutter)	4.89€
Sum	28.47€

I simply stuck a bag of silica gel in the bottom. Only later I found out that the blue desiccant has toxic cobalt for coloring, so I'd recommend to buy the orange variant instead.

E-Scooter Battery Build

Sat, 04 Jul 2026 12:00:00 -0000

Background

For over two years now, since February 2024, I own a Xiaomi Mi 3 scooter. Of course I flashed it with SHFW using the ST-Link method, which then allows using the normal SHFW Android app to do all updating and configuring.

This worked perfectly fine for about 2500km. Then the internal battery was noticeably degraded and I could no longer reach home from work in winter.

So I got one of the last Rita adapters before the product was discontinued, which allows connecting an external battery with differing voltage for range extension.

A colleague of mine bought a 13S6P battery on AliExpress which he didn't end up using, so I got that from him. Unfortunately it was total crap, and died much much quicker. After only a handful of trips, I could again not reach work anymore.

Still not having learned my lesson, I got a "new" internal Xiaomi scooter battery from AliExpress as well, which was just as bad and died in just a couple of trips.

So finally I decided to build my own.

Build

In my scooter config I've set a maximum current of 28A, so I decided to get a DIY battery kit from AliExpress with nominal support for 30A, in a 13S6P configuration. 30A divided by 6 cells in parallel gives a discharge current of 5A per cell.

Looking around online I decided to go with nkon.nl as they are a well-known large supplier of cells in Europe. There I found the INR18650-M29 cells from LG, which support a surge discharge current of 10A and continuous discharge of 6A, according to their datasheet.

As mentioned above, I checked the internal cell resistance, but you don't necessarily have to do that, as long as you use cells from one batch.

Now just stick them all into the carrier and attach the paper rings to the positive poles, to protect from shorts with the negative pole around the perimeter of each cell.

Then do the spot welding. I recommend doing some testing first on an unused cell, which is how I arrived at the settings mentioned above. I ended up with four welds per cell pole.

The whole thing was covered with more insulating paper, and some battery fibre tape to hold the cells firmly in place.

The BMS can also be welded, just the (dis)charge leads need to be soldered. Use thick wires for that, rated for the current. Therefore you will also need a beefy soldering iron to get them soldered to the PCB without unnecessary heating of other components.

Tools Used

Fortunately I have some access to tools at work.

So I used their RS Pro RSBM-3300 Battery Tester to check the charge state and internal resistance of each cell. This turned out to be unnecessary though, as all cells came from the same batch and had matching voltages and resistances.

For spot welding I used the FNIRSI SWM-10. The settings I was happy with are:

Preheat: 3ms
Pulse: 15ms
Interval: 10ms
Dots: 3

Although all around I don't like this spot welder very much. It's made with a single very beefy lithium cell inside, that seems to just be shorted for welding, which is fine. But the charging and safety monitoring of this cell seems problematic. It was deep-discharged by itself after some time on the shelf, and when left to charge it stopped the charge at a cell voltage of 4.3V, which is overcharging the cell. So be careful with that, if you own the device yourself. Some people online suggest only using it with slow USB chargers with 500mA or so.

It also took around three or four recharges of the spot-welder battery to finish this project.

Bill of Materials

These are the consumables I bought, with the price I paid at the time.

Part	Amount	Unit-Cost	Total-Cost
INR18650-M29 2850mAh - 10A	78x	1.06€	82.68€
48V 30A 13S 6P 18650 Battery Holder E-bike Battery Case Box BMS for E-scooter Electric Bike Battery Housings with Welding Nickel	1x	24.59€	24.59€
XT60 Battery Connector Male & Female Bullet Connector Plugs with Sheath Housing for RC Battery Motor FPV XT-60 Adapter Silicone (L)	1x	4.69€	4.69€
High Viscosity Stripe Fiber Tape, Non-Marking Tape, Battery Bundling, Wear-Resistant, Waterproof, and High-Temperature Resistant (50mm)	1x	3.55€	3.55€
5m 18650 Battery Electrical Insulating Adhesive Paper Thickness Battery Pack Insulator Gasket Tape Warp Electrode Insulated Pads (65mm)	1x	3.29€	3.29€
400 Pieces of Self-Adhesive Solid/Hollow 18650 Battery Insulation Pads, 18650 Battery Insulation Rings, 18650 High-Density Paper, Insulation Pad Circles, Single-Sided Adhesive Batteries (Hollow)	1x	1.59€	1.59€
ANL Fuse Holder Bolt-on Fuse Automotive Fuse Holders Fusible Link with fuse 40A 60A 80A 100A 200A 250A 300A Fuses AMP (2x 40A)	1x	4.99€	4.99€
Sum			125.38€

With these 2.85Ah cells, arranged as 6 in parallel, the resulting capacity of the pack is 17Ah. And the 13 strings of these in series give a nominal voltage of 48V.

Fuse Update

After building the battery I noticed that UL certified batteries are required to have a fuse or some other mechanism to prevent thermal runaway events. The BMS has short-circuit-protection, but I guess adding an actual fuse may help in some cases. So I bought some 40A fuses and a matching fuse block from AliExpress. Turns out they are way bigger than I expected. Reading the specs before buying may be helpful, lesson learned... 😅

So I just skipped the fuse block and wired the fuse directly into the positive wire.

It's a bit tight, but with some M5x12 screws to mount the cables I was able to make it fit.

I also took this opportunity and replaced the original six Philips M2.5x16 screws with ones that have internal hex heads.

Oscilloscope Video Display

Mon, 22 Dec 2025 12:00:00 -0000

After playing oscilloscope music the next obvious question that came up was: can we make it run Doom?

Turns out a couple of people already did that, even in different ways. The last link is just running normal Doom on a modern LCD osci, which seems a bit boring. Even more involved is modifying the game engine to output vectors, which has been done here or here, for Quake.

For this project I copied the circuit from the XYZ converter by MrSlehofer. The basic idea is to convert a CRT oscilloscope into a grayscale TV, by rastering each NTSC / PAL field line-by-line. So the X and Y channels contain saw-tooth waveforms, with the X frequency matching the horizontal blank period, and the Y frequency matching the vertical blank period. When Z is not connected you should therefore see something resembling a rectangular white 4:3 image. Then Z just needs to have the amplitude of the video signal, which corresponds to the brightness at that moment in time.

Just to test that process out for the first time I turned the PCB into a KiCad design that can be assembled by JLCPCB. This worked out well. If you want to order some as well, use the production_files from the repo.

Initially I had some problems getting the circuit to work at all. The oscilloscope screen only showed some strange warbling lines or squares.

Turns out it is very susceptible to changes in voltage levels. Depending on the source you use to feed it you may need to adjust some resistance values. In the end I replaced two resistors with potentiometers. This allows easy on-the-fly adjustments. Try a 10k poti for R1, and a 100k Poti for R10. Big thanks to Walter (DL2OL) from the local ham radio club co-located at our makerspace for helping with tuning the circuit!

The next step was to use a Raspberry Pi 1 that I still had lying around, because of the prominent analog video output connector on there.

Powering it with switching voltage regulators was not a good idea. The voltage ripple on the supply lines is very visible on the output image. So next I used a lab power supply for the video converter PCB, and an official Raspberry Pi USB wall wart for 5V. I also used the opportunity to switch to a beefier Raspberry Pi 3, after I learned that it still has an AV out on the 3.5mm jack.

Replacing the USB power supply with another big lab power supply and dimming the room lights / providing some shade for the scope screen meant we could finally play for the first time. Philipp and I tried both Doom (chocolate-doom) and Tux Racer.

Here's another run where we actually completed the first Doom 1 Episode. I also brought my old Tektronix scope. All the scopes we tried don't have any gain control for their Z / brightness input, and the video PCB is also not that finely adjustable. With the Tektronix scope the voltage ranges and therefore contrast and brightness seem to fit best.

To have another portable setup for display in the local makerspace I planned to iterate on the case idea from my Osci Music Player. The housing should be a plastic kitchen ware container with all required connections routed to panel mount connectors.

Everything was initially planned to be powered by a USB-C PD power supply with 12V for the converter PCB and a step-down converter to power a Raspberry Pi with 5V. Unfortunately I think some more serious filtering of the regulator outputs would be needed to get acceptable image quality while using step-down converters.

For now I'm simply hooking up some high quality lab power supplies. Considering the device is always operated near an oscilloscope that should probably not be too restricting.

Though I have to admit, I'm still not quite happy with this raster approach. The high frequency audio interface of the Osci Music Player hardware could also be used to improve the visual quality of Michael Ayles' ScopeDoom.

CYD MQTT Touchscreen UI

Sun, 28 Sep 2025 12:00:00 -0000

...back to Smart Home overview

After adding more actors to my Smart Home in the form of power sockets running Tasmota, I had to improve the ways to control all of these devices. The Telegram Bot and Web UI are a good start, but the Wife Acceptance Factor is pretty low, and they require access to a computer or smartphone.

Recently I learned about the CYD (cheap yellow display), a nice ESP32 dev board with a touchscreen. This seemed ideal to run a simple user interface to control everything via MQTT.

Here are the results. When not in use the device shows a stand-by screen with the current time and date. After pressing the screen a menu is shown.

I mounted multiple of these units in different places. They can be updated easily over-the-air.

To get the LDR on the device to work properly, so the screen brightness can be adjusted to the environment lighting conditions, you need to modify the hardware a bit. I removed R19 and replaced R15 with a 100k resistor. The top board in the following image is in the original state, the bottom board has already been modified.

The CYD code has been integrated into my ESP-Env project and repo.

Smart Meter Bridge

Sat, 06 Jul 2024 12:00:00 -0000

...back to Smart Home overview

A while ago my power net company installed new smart power meters, specifically the Iskra MT681. It has a standardized infrared interface to get some data from it. There are different designs available to attach a microcontroller, both open-source and commercial. I've gone the lazy route and bought one from eBay.

Unfortunately the meter is mounted in the basemet of my apartment building, too far for any WiFi signals. So I decided to try out LoRa to transmit the data, using two Heltec LoRa32 dev boards.

The interface to the meter is an infrared UART with 9600 8N1. Over this port it sends messages in a format called SML. To decode these I'm using sml_parser.

To get useful data from the meter you have to unlock it with a PIN from the net provider. Without this PIN you only get the current energy count in kWh, the same number you can see on the display. After unlocking all data, you get the energy count in 1/10th Wh, so much finer resolution. And you also get the current power in W.

For the LoRa PHY I'm using RadioLib, which already comes integrated into the unofficial Heltec LoRa 32 library.

I'm doing lots of deep sleep on the transmitter side, to safe as much battery capacity as possible. And I had to use the watchdog in the ESP32 and also do an auto-reset when no messages have been received after a while. So somewhere the code hangs, sometimes. But with these hacks in place it seems to work well.

The code is integrated into my ESP-Env project and repo.

Here you can see a normal weekend for me, going to bed at 4:30 in the morning, and waking up at around 13:00. The spike with 1.3kW is heating water for coffee. The other power readings come from tasmota sockets or my NAS UPS.

Also the battery usage of the LoRa transmitter is very low. ~~I will update when I have to recharge them for the first time.~~

Update from September 2025:

The device works for around two to three months on a single charge. This is with an over five year old Panasonic NCR18650B that was previously used in an E-Cigarette mod, with nominal 3400mAh. Here is the battery status from the previous year.

As you can tell I even accidentally deep-discharged the cell last christmas, but it still runs fine.

Duality

Tue, 19 Aug 2025 12:00:00 -0000

Introduction

I regularly watch the livestreams of fulltime GTA:SA speedrunner Joshimuz. A while ago he did a PS2 Retro Achievements run. As part of these he has to get a Top 5 score in the in-game arcade machine Duality in both the black and white highscore table. In Part 10 at 04:02:16, when Josh starts playing Duality, chat user Caffie_ mentions how this could be a Game Boy game. So this inspired me to try to port the game to the Game Boy Color. Here are the results.

You can either download the ROM or try it out right here, if you have JavaScript enabled, thanks to EmulatorJS.

On PCs use keyboard input with the keys given below. On mobile devices a touch overlay should automatically appear over the emulator.

Button	Key	Action
D-Pad Left	Arrow Left	Rotate Left
D-Pad Right	Arrow Right	Rotate Right
A	S	Accelerate
B	A	Shoot
Start	Enter	Play / Pause
Select	Space	Config / About

Although you can use EmulatorJS I recommend a native emulator for your target device if you experience stuttering music or bad performance with the emulator on this page.

Alternatively here's a short gameplay video and some screenshots.

Click for more screenshots.

Quick Start Guide

Press Left or Right on the title screen to show either the black or white highscores. Press Select to show the about screen and build info. In-game press Start to pause and resume. While paused press Select to return to the menu.

Collect small white spheres to get +5 white score. Collect small black spheres to get +5 black score. The opposite color will reduce your score when collected. Shooting while you have a white score will reduce it by one. Large black holes will attract you and damage your ship when touched. Large white spheres will repel you and replenish your health when touched. Accelerating will reduce your fuel, which will recharge when not accelerating. You can shoot large spheres for +10 points.

For a more detailed description of the original game check out the Duality article on GTA Wiki 😛

Links

The code is of course freely available under the GPL license. Also check out the automatically generated project website on GitHub Pages.

Toolchain

Fortunately the Game Boy is probably one of the retro hardware platforms with the best community-created documentation. The most important piece from this community is Pan Docs, a living document that has been extended and revised over the years that basically is the reference manual for the platform.

I wrote the whole game in C, which is very easy thanks to the GBDK-2020. It uses SDCC as the compiler with some custom tools to link the final ROM file. Additionally it also includes a tool that can convert graphics to the proper hardware sprite tile and map format. The GBDK also comes with good documentation and lots of examples that really make it easy to get started.

Over the course of the project my Makefile grew relatively big and customized. Of course I've added the usual stuff like dependency file generation and git version information. I'm also automatically generating the graphics data with the png2asset tool. To convert sound samples I've modified the cvtsample.py tool from the GBDK examples. And to pre-calculate some speed vector tables for different angles I wrote my own gen_angles.py script.

To find out how to convert the graphics assets I'm encoding the mode in the filename of the input images.

$(BUILD_DIR)/$(DATA_DIR)/%.c $(BUILD_DIR)/$(DATA_DIR)/%.h: $(DATA_DIR)/%.png Makefile
        @mkdir -p $(@D)
        $(eval SPRFLAG = $(shell echo "$<" | sed -n 's/.*_spr\([0-9]\+\).*/\-sw \1 \-sh \1/p'))
        $(eval FNTFLAG = $(shell echo "$<" | sed -n 's/.*_fnt\([0-9]\+\).*/\-sw \1 \-sh \1/p'))
        $(if $(findstring _map,$<),                                                             \
                @echo "Converting map $<" &&                                                    \
                $(PNGA) $< -o $@ -spr8x8 -map -noflip                                           \
        ,$(if $(findstring _fnt,$<),                                                            \
                @echo "Converting font $<" &&                                                   \
                $(PNGA) $< -o $@ -spr8x8 $(FNTFLAG) -map -noflip                                \
        ,$(if $(findstring _spr,$<),                                                            \
                @echo "Converting 8x8 sprite $<" &&                                             \
                $(PNGA) $< -o $@ -spr8x8 $(SPRFLAG) -noflip                                     \
        ,$(if $(findstring pause,$<),                                                           \
                @echo "Converting 40x16 sprite $<" &&                                           \
                $(PNGA) $< -o $@ -spr8x8 -sw 40 -sh 16 -noflip                                  \
        ,$(if $(findstring _sgb,$<),                                                            \
                @echo "Converting sgb border $<" &&                                             \
                $(PNGA) $< -o $@ -map -bpp 4 -max_palettes 4 -pack_mode sgb -use_map_attributes \
        ,                                                                                       \
                @echo "Converting tile $<" &&                                                   \
                $(PNGA) $< -o $@ -spr8x8                                                        \
        )))))

Link to the complete file "Makefile" (alt 1)

Like with the documentation, the emulation ecosystem for the Game Boy is also very healthy.

I've mostly been using Gearboy which includes some nice visualization tools for the hardware state.
To test the Super Game Boy borders I used SameBoy.
A very nice symbolic C debbuger integration is available in Emulicious.
GBE+ can also emulate a Game Boy Printer.
NO$GMB is able to emulate multiple linked Game Boy systems.
While testing debugging I also played around with BGB for a bit.
And for one especially hard debugging session I used the reverse-time-step feature of GameRoy with good success (to actually see the faulty jump to the wrong bank after it happened).

The Windows-only emulators all ran fine using Wine.

I described the Emulicious debugger integration to Kate (or VSCode I guess) in more detail in the README.

Software

The game is really made for the Game Boy Color (GBC). On the monochrome Game Boy (DMG) and the Super Game Boy (SGB) it runs at half-speed and the black and white spheres are hard to differentiate. Or, to put it another way, I was not able to optimize the code enough that it run's at the DMG clock speed of ~1MHz. So I had to cheat by putting the GBC CPU into a double-clock mode.

    // "cheat" and enable double-speed CPU mode on GBC
    if (_cpu == CGB_TYPE) {
        cpu_fast();
    }

Link to the complete file "main.c" (alt 1)

To get some randomness into the gameplay I'm initially showing a splash screen after reset, where the user has to press Start. The timing of this button-press is used to initialize a random number generator that's later used to determine spawning positions of objects in the world map.

    splash();

#ifdef CONSTANT_SEED
    uint16_t seed = CONSTANT_SEED;
#else
    uint16_t seed = DIV_REG;
    waitpadup();
    seed |= ((uint16_t)DIV_REG) << 8;
#endif

    // store in an SRAM variable, so the
    // value goes over the cartridge bus.
    // gives gb-interceptor a chance to see it.
    prng_seed = seed;
    initarand(prng_seed);

Link to the complete file "main.c" (alt 1)

The splash screen in main.c also handles the configuration and debug menus (try the Konami code).

The main game loop in game.c is pretty straight-forward, like with most game engines. It basically does the following things:

read key inputs from user
modify player and world state (according to input and time)
draw the output graphics

The world state is kept track of in obj.c, where each shot and colored sphere is represented as an entry in an object list.

Background music is played automatically on the pulse channels (1 and 2), as well as the noise channel (4). Only the sample channel (3) is used for sound effects like shots or explosions. Both of these are handled by interrupts, so they should never stutter or crackle (instead gameplay slows down). For timekeeping I'm also configuring the internal timer and handle all of these tasks in the same ISR.

static void timer_isr(void) NONBANKED {
    sample_isr();
    snd_play();
    count++;
}

Link to the complete file "timer.c" (alt 1)

One pattern I've used repeatedly is storing (const) lists of "things" in ROM to be able to use them easily in other places. This is used for sprites, background maps, sound samples and music. For example, this is the start of the list of sprite graphics.

struct sprites metasprites[SPRITE_COUNT] = {
    { // SPR_SHIP
        .ms = rockshp_spr24_metasprites,
        .ms_n = ARR_LEN(rockshp_spr24_metasprites),
        .ti = rockshp_spr24_tiles,
        .pa = rockshp_spr24_palettes,
        .pa_n = rockshp_spr24_PALETTE_COUNT,
        .pa_i = OAMF_CGB_PAL0,
        .cnt = rockshp_spr24_TILE_COUNT,
        .off = TILE_NUM_START,
        .bank = BANK(rockshp_spr24),
    },
    { // SPR_LIGHT
        .ms = light_metasprites,
        .ms_n = ARR_LEN(light_metasprites),
        .ti = light_tiles,
        .pa = light_palettes,
        .pa_n = light_PALETTE_COUNT,
        .pa_i = OAMF_CGB_PAL2,
        .cnt = light_TILE_COUNT,
        .off = TILE_NUM_START,
        .bank = BANK(light),
    },
    { // SPR_DARK

Link to the complete file "sprite_data.c" (alt 1)

By then calling the sprite functions the correct data is automatically loaded into VRAM and used accordingly. The sprite and map lists are not const because the offsets are calculated dynamically when loaded. The music and sample lists are both const though.

void spr_init(void);
void spr_init_pal(void);
void spr_draw(enum SPRITES sprite, enum SPRITE_FLIP flip, int8_t x_off, int8_t y_off, uint8_t frame, uint8_t *hiwater);
void spr_ship(enum SPRITE_ROT rot, uint8_t moving, uint8_t *hiwater);

Link to the complete file "sprites.h" (alt 1)

It's not possible to rotate sprites by arbitrary angles, only the X and Y axis can be flipped individually. So for each desired rotation a sprite has to be prepared manually.

I decided to split the circle into 16 different angles, or 22.5 degree steps. When taking advantage of the tile flipping we can get away with five different sprite rotations, from 0 degrees to 90 degrees.

To get the proper movement and shot velocity vectors for the current angle I'm also pre-calculating these tables.

const int8_t table_speed_move[table_speed_move_SIZE] = {
    0, 23, // 0.0
    9, 21, // 22.5
    16, 16, // 45.0
    21, 9, // 67.5
    23, 0, // 90.0
    21, -9, // 112.5
    16, -16, // 135.0
    9, -21, // 157.5
    0, -23, // 180.0
    -9, -21, // 202.5
    -16, -16, // 225.0
    -21, -9, // 247.5
    -23, 0, // 270.0
    -21, 9, // 292.5
    -16, 16, // 315.0
    -9, 21, // 337.5
};

Graphics

To easily visualize the data in VRAM here are some screenshots from Gearboy.

There's not enough space to fit all graphics data at once, so I'm loading different subsets in the menu and in-game.

The first image shows the sprite objects in OAM. These are instances of tiles from the tile data.
Tile data is shown in the upper left part of the second image. The middle and lower left parts of the second image contain the tile data for the background maps and window. The right half of the second image shows a second bank only available on GBC, which I use for a smaller font.
The third image shows the background map, a large map of tiles that can be scrolled easily.
The fourth image shows the palettes to colorize the tiles on GBC hardware.

You can only store a maximum of 40 tile instances in OAM at once, but there are more complicated rules on when they appear. To colorize tiles the GBC adds a palette index to the attributes.

The background map works similar to the OAM in that it indexes the background tile map, but the positions are fixed and the GBC has attributes for the map that don't exist on DMG.

Sound

The background music is simply stored as long lists of notes. Here are some example excerpts from the score-screen music.

#include <assert.h>

#include "banks.h"
#include "sound.h"
#include "sound_over.h"

BANKREF(sound_over)

static const enum notes over_notes[] = {
    // repeat 1

    Ab4,  C5, Ab4,  F4, Ab4, Ab4, Ab4,  C5,
    Ab4,  F4, Ab4, Bb4,  C5, Bb4, Ab4,  F4,

     A4,  C5,  A4,  F4,  A4,  A4,  A4,  C5,
     A4,  F4,  A4, Bb4,  C5, Bb4,  A4,  F4,


// ...

    END
};

#define ADD_LOOP \
    Ab2, SIL, Ab2, SIL, Ab2, SIL, Ab2, SIL, \
    Ab2, SIL, Ab2, SIL, Ab2, SIL, Ab2, SIL

#define ADD_LOOP_2 \
     A2, SIL,  A2, SIL,  A2, SIL,  A2, SIL, \
     A2, SIL,  A2, SIL,  A2, SIL,  A2, SIL

#define ADD_LOOP_3 \
     E2, SIL,  E2, SIL,  E2, SIL,  E2, SIL, \
     E2, SIL,  E2, SIL,  E2, SIL,  E2, SIL

static const enum notes over_notes2[] = {
    // repeat 1

    ADD_LOOP, ADD_LOOP_2,
    ADD_LOOP, ADD_LOOP_3,
    ADD_LOOP, ADD_LOOP_2,

    Db3, Db3, Db3, Db3, Db3, Db3, Db3, Db3,
    SIL, SIL, SIL, SIL, SIL, SIL, SIL, SIL,
    SIL, SIL, SIL, SIL, SIL, SIL, SIL, SIL,
    SIL, SIL, SIL, SIL, SIL, SIL, SIL, SIL,


// ...

    END
};

#define DRUM_LOOP \
    dKi, dSI, dSI, dSI, dSI, dSI, dKi, dSI, \
    dSn, dSI, dSI, dSI, dKi, dSI, dSI, dSI  \

static const enum drums over_drums[] = {
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,
    DRUM_LOOP,


// ...

    dEND
};

static_assert(sizeof(over_notes)  == sizeof(over_notes2), "music loops need to be same length");
static_assert(sizeof(over_notes2) == sizeof(over_drums),  "music loops need to be same length");
static_assert(sizeof(over_notes)  == sizeof(over_drums),  "music loops need to be same length");

const struct music music_over = {
    .notes = over_notes,
    .notes2 = over_notes2,
    .drums = over_drums,
    .duration = 120,
    .repeat = MUSIC_NO_REPEAT,
};

Link to the complete file "sound_over.c" (alt 1)

over_notes and over_notes2 are the frequencies for the two pulse channels. over_drums has the IDs of different pre-defined settings for the noise channel.

The snd_play() function in sound.c is then walking through this list after the note duration has elapsed, filling the sound hardware registers as needed.

BANKREF(sound)

const uint16_t frequencies[SILENCE] = {
      44,  156,  262,  363,  457,  547,  631,  710,  786,  854,  923,  986, //  0 .. 11
    1046, 1102, 1155, 1205, 1253, 1297, 1339, 1379, 1417, 1452, 1486, 1517, // 12 .. 23
    1546, 1575, 1602, 1627, 1650, 1673, 1694, 1714, 1732, 1750, 1767, 1783, // 24 .. 35
    1798, 1812, 1825, 1837, 1849, 1860, 1871, 1881, 1890, 1899, 1907, 1915, // 36 .. 47
    1923, 1930, 1936, 1943, 1949, 1954, 1959, 1964, 1969, 1974, 1978, 1982, // 48 .. 59
    1985, 1988, 1992, 1995, 1998, 2001, 2004, 2006, 2009, 2011, 2013, 2015  // 60 .. 71
};

static volatile struct music const * music = NULL;
static volatile uint8_t bank;
static volatile uint8_t duration;
static volatile uint16_t off = 0;
static volatile uint16_t last_t = 0;

struct snds {
    uint8_t bank;
    struct music const * snd;
};

static const struct snds snds[SND_COUNT] = {
    { .bank = BANK(sound_menu), .snd = &music_menu }, // SND_MENU
    { .bank = BANK(sound_game), .snd = &music_game }, // SND_GAME
    { .bank = BANK(sound_over), .snd = &music_over }, // SND_GAMEOVER
};

#define CALL_FREQ_HZ 256

static void play_note(enum notes note) NONBANKED {
    if (note < SILENCE) {
        uint16_t freq;
        START_ROM_BANK(BANK(sound)) {
            freq = frequencies[note];
        } END_ROM_BANK

        NR11_REG = 0x80 | duration; // 50% duty, higher value is shorter time (up to 0x3F)
        NR12_REG = (conf_get()->music_vol << 4) | 0x00; // given volume, no change
        NR13_REG = freq & 0xFF; // given frequency
        NR14_REG = 0x80 | 0x40 | ((freq >> 8) & 0x07); // trigger, enable length, upper freq bits
    }
}

static void play_note2(enum notes note) NONBANKED {
    if (note < SILENCE) {
        uint16_t freq;
        START_ROM_BANK(BANK(sound)) {
            freq = frequencies[note];
        } END_ROM_BANK

        NR21_REG = 0x80 | duration; // 50% duty, higher value is shorter time (up to 0x3F)
        NR22_REG = (conf_get()->music_vol << 4) | 0x00; // given volume, no change
        NR23_REG = freq & 0xFF; // given frequency
        NR24_REG = 0x80 | 0x40 | ((freq >> 8) & 0x07); // trigger, enable length, upper freq bits
    }
}

static void play_drum(enum drums drum) NONBANKED {
    switch (drum) {
        case dKick:
            NR41_REG = 0x2F; // length timer, higher value is shorter time (up to 0x3F)
            NR42_REG = (conf_get()->music_vol << 4) | 0x00; // initially full volume, no volume changes over time
            NR43_REG = 0x11; // frequency distribution
            NR44_REG = 0xC0; // trigger and enable length
            break;

        case dSnare:
            NR41_REG = 0x10; // length timer, higher value is shorter time (up to 0x3F)
            NR42_REG = (conf_get()->music_vol << 4) | 0x02; // initially full volume, then fade sound out
            NR43_REG = 0x46; // frequency distribution
            NR44_REG = 0xC0; // trigger and enable length
            break;

        default:
            break;
    }
}

void snd_init(void) BANKED {
    NR52_REG = 0x80; // sound on
    NR51_REG = 0xFF; // all channels on left and right

#ifdef DEBUG
    NR50_REG = 0x33; // left and right on half volume
#else
    NR50_REG = 0x77; // left and right on full volume
#endif
}

void snd_music_off(void) BANKED {
    CRITICAL {
        music = NULL;
    }
}

void snd_note_off(void) BANKED {
    play_note(SILENCE);
    play_note2(SILENCE);
}

static uint16_t snd_duration(enum SOUNDS snd) NONBANKED {
    uint16_t r;
    START_ROM_BANK(snds[snd].bank) {
        r = snds[snd].snd->duration;
    } END_ROM_BANK
    return r;
}

void snd_music(enum SOUNDS snd) BANKED {
    if (snd >= SND_COUNT) {
        return;
    }

    CRITICAL {
        music = snds[snd].snd;
        bank = snds[snd].bank;
        duration = 0x3F - MIN((snd_duration(snd) >> 2) + 1, 0x3F);
        off = 0;
        last_t = timer_get();
    }
}

void snd_play(void) NONBANKED {
    if (!music) {
        return;
    }

    START_ROM_BANK(bank) {
        uint16_t diff = timer_get() - last_t;
        if (diff >= music->duration) {
            if (music->notes) {
                if (music->notes[off] != END) {
                    play_note(music->notes[off]);
                } else {
                    if (music->repeat != MUSIC_NO_REPEAT) {
                        off = music->repeat;
                        snd_play();
                        goto end;
                    } else {
                        music = NULL;
                        goto end;
                    }
                }
            }

            if (music && music->notes2) {
                if (music->notes2[off] != END) {
                    play_note2(music->notes2[off]);
                } else {
                    if (music->repeat != MUSIC_NO_REPEAT) {
                        off = music->repeat;
                        snd_play();
                        goto end;
                    } else {
                        music = NULL;
                        goto end;
                    }
                }
            }

            if (music && music->drums) {
                if (music->drums[off] != dEND) {
                    play_drum(music->drums[off]);
                } else {
                    if (music->repeat != MUSIC_NO_REPEAT) {
                        off = music->repeat;
                        snd_play();
                        goto end;
                    } else {
                        music = NULL;
                        goto end;
                    }
                }
            }

            off++;
            last_t += music->duration;
        }

end:
    } END_ROM_BANK
}

Link to the complete file "sound.c" (alt 1)

For the sound effect sample player I've transcribed the assembly ISR from the GBDK examples to C, which was a fun little exercise in SM83 assembly.

#if 1

// TODO C version has a slight 'beep' always? and much worse at lower volumes?

void sample_isr(void) NONBANKED {
    if (play_length == 0) {
        return;
    }

    NR51_REG = 0xBB; // turn CH3 off in left and right pan
    NR30_REG = 0x00; // turn DAC off

    START_ROM_BANK(play_bank) {
        // load waveforms
        for (uint8_t i = 0; i < 16; i++) {
            _AUD3WAVERAM[i] = *(play_sample++);
        }
    } END_ROM_BANK

    NR30_REG = 0x80; // turn DAC on
    NR31_REG = 0xFE; // length of wave, 2nd shortest
    NR32_REG = (4 - /*conf_get()->sfx_vol*/0x03) << 5;
    NR33_REG = 0x00; // low freq bits are zero
    NR34_REG = 0xC7; // start, no loop, high freq bits are 111
    NR51_REG = 0xFF; // turn all channels on

    play_length--;
}

#else

// TODO ASM version has less beep at full volume, but also beeping at lower volumes?

void sample_isr(void) NONBANKED NAKED {
    __asm
        ld hl, #_play_length    ; something left to play?
        ld a, (hl+)
        or (hl)
        ret z

        ld hl, #_play_sample
        ld a, (hl+)
        ld h, (hl)
        ld l, a                 ; HL = current position inside the sample

                                ; load new waveform
        ld a, (#__current_bank) ; save bank and switch
        ld e, a
        ld a, (#_play_bank)
        ld (_rROMB0), a

        ldh a, (_NR51_REG)
        ld c, a
        and #0b10111011
        ldh (_NR51_REG), a

        xor a
        ldh (_NR30_REG), a

        .irp ofs,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
            ld a, (hl+)
            ldh (__AUD3WAVERAM+ofs), a
        .endm

        ld a, #0x80
        ldh (_NR30_REG), a
        ld a, #0xFE             ; length of wave
        ldh (_NR31_REG), a
        ld a, #0x20             ; volume
        ldh (_NR32_REG), a
        xor a                   ; low freq bits are zero
        ldh (_NR33_REG), a
        ld a, #0xC7             ; start; no loop; high freq bits are 111
        ldh (_NR34_REG), a

        ld a, c
        ldh (_NR51_REG), a

        ld a, e                 ; restore bank
        ld (_rROMB0), a

        ld a, l                 ; save current position
        ld (#_play_sample), a
        ld a, h
        ld (#_play_sample+1), a

        ld hl, #_play_length    ; decrement length variable
        ld a, (hl)
        sub #1
        ld (hl+), a
        ld a, (hl)
        sbc #0
        ld (hl), a
        ret
    __endasm;
}
#endif

Link to the complete file "sample.c" (alt 1)

Banking

Probably the most important topic in Game Boy software development is memory banking. Take a look at the memory map of the system.

Start	End	Description
0x0000	0x3FFF	16 KiB ROM bank 00
0x4000	0x7FFF	16 KiB ROM Bank 01 – NN
0x8000	0x9FFF	8 KiB Video RAM (VRAM)
0xA000	0xBFFF	8 KiB External RAM (SRAM)
0xC000	0xCFFF	4 KiB Work RAM (WRAM)
0xD000	0xDFFF	4 KiB Work RAM (WRAM)
0xE000	0xFDFF	Echo RAM (mirrors WRAM)
0xFE00	0xFE9F	Object attribute memory (OAM)
0xFEA0	0xFEFF	Not Usable
0xFF00	0xFF7F	I/O Registers
0xFF80	0xFFFE	High RAM (HRAM)
0xFFFF	0xFFFF	Interrupt Enable register (IE)

Only the 32KiB ROM bank areas at 0x0000 - 0x7FFF and the 8KiB RAM at 0xA000 - 0xBFFF are coming from the cartridge. The cartridge RAM is usually used to store persistent savegames and configs on a battery backed SRAM. The code and data live in the first 32KiB.

Of course for many games these 32KiB are not enough, so they use some special hardware in the cartridge to map different memory chips to the same address range, depending on a configuration register. This is accomplished by Nintendos Memory Bank Controllers, most commonly (and for this game) the MBC5.

Each bank has a size of 16KiB, with the first bank (0) always mapped to the first 16KiB of the address space. The next half of the ROM area is for the switchable bank, which can be selected by writing to the MBC-internal registers.

Fortunately GBDK already contains a bunch of helper functions that make this all a bit easier. For the ROM banks we have to differentiate the following cases.

const data in a bank
functions in bank 0 (non-banked)
non-static functions in a bank
static functions (in a bank)

Also note that with the GBDK and SDCC every compilation unit (so each .c file) can only be part of one bank. Which unit goes into which bank can be decided automatically (autobanking).

First enable autobanking by passing the proper compiler flag -Wm-yoA. Now, at the start of each .c and .h files, declare a reference to the bank of this compilation unit.

/* in some_name.c */
BANKREF(some_name)

/* in some_name.h */
BANKREF_EXTERN(some_name)

Of course each unit needs a unique some_name (does not need to be the filename).

Now you can declare your non-static functions with an attribute to place them in the correct bank.

void foo(void) BANKED;
void bar(void) NONBANKED;

When you call a BANKED function a trampoline in bank 0 automatically takes care of proper bank switching for you. Only when calling static functions not marked as BANKED (case 4 from above) you need to make sure you're either already in the correct bank (by coming from a BANKED function from the same compilation unit), or to switch banks manually (when coming from a NONBANKED function).

To easily bank-switch I made some small helper macros.

#define START_ROM_BANK_2(x) __xyz_previous__bank = CURRENT_BANK; SWITCH_ROM(x); do
#define START_ROM_BANK(x) uint8_t START_ROM_BANK_2(x)
#define END_ROM_BANK while (0); SWITCH_ROM(__xyz_previous__bank);

Link to the complete file "banks.h" (alt 1)

const data has the same restrictions, so when you need to read const data from one bank in a function from another compilation unit you may need to add a small NONBANKED helper function.

static uint8_t is_conf_hw(uint8_t i) NONBANKED {
    uint8_t r;
    START_ROM_BANK(BANK(main)) {
        r = (conf_entries[i].type == HW_ALL) || (conf_entries[i].type == get_hw());
    } END_ROM_BANK
    return r;
}

Link to the complete file "window.c" (alt 1)

Of course you can never directly switch banks inside a function that is not NONBANKED as this would replace the currently executed opcodes.

Initially I started out with lots of functions marked as NONBANKED, but this turned out to be unnecessary. By properly modularizing your code and liberally using BANKED you can get the compiler to do most of the work for you.

It's also relatively easy to spot banking errors. Most of the time the VRAM will quickly fill with some regular pattern, like horizontal or vertical lines. Or a debugger shows you suddenly in the middle of nowhere. But I also had some devious cases, where the control flow jumped into some legitimate code that caused strange effects (wrong sound effects, no objects appearing, but the game still ran). These took me a while to figure out, until I noticed a return that skipped the final END_ROM_BANK of a function, thereby forgetting to switch-back the bank.

RAM banks, in comparison, can be handled more easily. I'm simply enabling and setting RAM bank 0 at the beginning, before reading the config from there, and always keep it enabled while the game is running.

void conf_init(void) BANKED {
    ENABLE_RAM;
    SWITCH_RAM(0);

    if (calc_crc() != mem.crc) {
        mem.config.debug_flags = 0;
        //mem.config.sfx_vol = 0x03;
        mem.config.music_vol = 0x07;

        if (_cpu == CGB_TYPE) {
            mem.config.game_bg = 0;
        } else {
            mem.config.game_bg = 1;
        }

        mem.config.dmg_bg_inv = 1;

        score_reset();

        mem.state.in_progress = 0;
    }
}

Link to the complete file "config.ba0.c" (alt 1)

Similar to the png2asset calls the RAM bank of a compilation unit is specified in the filename (foo.baN.c where N is the RAM bank number).

$(BUILD_DIR)/%.o: %.c $(ASSETS) Makefile
        @mkdir -p $(@D)
        @echo Compiling Code $<
        $(eval BAFLAG = $(shell echo "$<" | sed -n 's/.*\.ba\([0-9]\+\).*/\-Wf-ba\1/p'))
        @$(LCC) $(LCCFLAGS) $(BAFLAG) -c -o $@ $<

Link to the complete file "Makefile" (alt 1)

This is what the memory usage for my game looks like at the moment.

Bank         Range                Size     Used  Used%     Free  Free% 
--------     ----------------  -------  -------  -----  -------  -----
ROM_0        0x0000 -> 0x3FFF    16384    10466    64%     5918    36%
ROM_1        0x4000 -> 0x7FFF    16384    16383   100%        1     0%
ROM_2        0x4000 -> 0x7FFF    16384    16377   100%        7     0%
ROM_3        0x4000 -> 0x7FFF    16384    16383   100%        1     0%
ROM_4        0x4000 -> 0x7FFF    16384     5903    36%    10481    64%
SRAM_0       0xA000 -> 0xBFFF     8192      427     5%     7765    95%
WRAM_LO      0xC000 -> 0xCFFF     4096     1650    40%     2446    60%

So I'm using five ROM banks in total for code and data (which has to be rounded up to eight banks, or 128KiB, as cartridges only can speficy ROM bank counts that are a power of two). And a single SRAM bank (8KiB) for persistent highscores, configs and a savegame, which is the smallest number of SRAM banks possible. Take care not to fill ROM bank 0 too close to the limit, as the ROM header is not always properly taken into account in all tools.

Game Boy Printer

The GBDK already comes with a Game Boy Printer example which I cleaned up and modified. Instead of reading a converted image I'm directly getting the tile data from VRAM to print either the window or background map. The data is read in blocks of two tile rows which are blacked out after transmission as a progress indicator.

enum PRN_STATUS gbprinter_screenshot(uint8_t win, uint8_t palette) BANKED {
    static uint8_t tile_buff[2 * DEVICE_SCREEN_WIDTH * 16];
    static struct prn_config params;
    enum PRN_STATUS r = PRN_STATUS_OK;

    printer_send_command(PRN_CMD_INIT, NULL, 0);

    for (int y = 0; y < DEVICE_SCREEN_HEIGHT; y += 2) {
        for (int y2 = 0; y2 < 2; y2++) {
            for (int x = 0; x < DEVICE_SCREEN_WIDTH; x++) {
                uint8_t tile = win ? get_win_tile_xy(x, y + y2) : get_bkg_tile_xy(x, y + y2);
                win ? get_win_data(tile, 1, tile_buff + ((x + (y2 * DEVICE_SCREEN_WIDTH)) * 16))
                    : get_bkg_data(tile, 1, tile_buff + ((x + (y2 * DEVICE_SCREEN_WIDTH)) * 16));
            }

            // black out rows we have sent, to indicate transfer progress
            win ? fill_win_rect(0, y + y2, DEVICE_SCREEN_WIDTH, 1, 0)
                : fill_bkg_rect(0, y + y2, DEVICE_SCREEN_WIDTH, 1, 0);
        }

        if (win) {
            if (y == 0) {
                win_str_helper("gb printer", 0);
            } else if (y == 2) {
                win_str_helper("transmit", 2);
            } else if (y == 8) {
                win_str_helper("in", 8);
            } else if (y == 10) {
                win_str_helper("progress", 10);
            } else if (y == 16) {
                win_str_helper("printing", 16);
            }
        }

        r = printer_send_command(PRN_CMD_DATA, tile_buff, sizeof(tile_buff));
        if ((r & ~PRN_STATUS_UNTRAN) != PRN_STATUS_OK) {
            r |= PRN_STATUS_AT_DATA;
            goto end;
        }

        if (printer_check_cancel()) {
            printer_send_command(PRN_CMD_BREAK, NULL, 0);
            r |= PRN_STATUS_CANCELLED;
            goto end;
        }
    }

    printer_send_command(PRN_CMD_DATA, NULL, 0);

    params.sheets = 1;
    params.margins = PRN_FINAL_MARGIN;
    params.palette = palette;
    params.exposure = PRN_EXPO_DARK;

    printer_send_command(PRN_CMD_PRINT, (uint8_t *)&params, sizeof(struct prn_config));

    r = printer_wait(PRN_BUSY_TIMEOUT, PRN_STATUS_BUSY, PRN_STATUS_BUSY);
    if ((r & ~(PRN_STATUS_FULL | PRN_STATUS_TIMEOUT)) & PRN_STATUS_MASK_ERRORS) {
        r |= PRN_STATUS_AT_BUSY;
        goto end;
    }

    r = printer_wait(PRN_PRINT_TIMEOUT, PRN_STATUS_BUSY, 0);
    if ((r & ~PRN_STATUS_FULL) & PRN_STATUS_MASK_ERRORS) {
        r |= PRN_STATUS_AT_FINAL;
        goto end;
    }

end:
#ifdef DEBUG
    EMU_printf("%s: 0x%04x\n",  __func__, (uint16_t)r);
#endif // DEBUG
    return (r & ~PRN_STATUS_FULL);
}

Link to the complete file "gbprinter.c" (alt 1)

Here is a screencast of printing in the GBE+ emulator and a copy of the results.

And this is a recording of my actual old childhood GB Printer in action.

Physical Cartridges

To build physical cartridges I ordered two flashcarts as well as cartridge cases in black and white.

Unfortunately the flash carts use FRAM and a custom CPLD implementation to replace the mapper chip. It seems the timings or voltages or some other electrical or physical parameters are not quite correct. I can't get them to work in the GB Interceptor for example. But in my real DMG and GBC they work fine.

I'm using this clone writer, although I wouldn't really recommend it. It's very slow and can't be updated, probably due to being a chinese clone. Also the "upstream repo" is completely empty. Unfortunately all other writers supported by FlashGBX are not really free hardware or software either.

To write to the carts I'm using the DIY cart with MX29LV640 @ WR setting of FlashGBX.

I ordered three pieces of the label printed on foil, with the rounded corners cut out, at Klebefisch, for 30€ including postage, or about 10€ per label. The parameters were:

White foil
Cut outline
Not mirrored
42mm by 37mm
1.5mm corner radius

The size and finish of the sticker are great, but unfortunately the print quality is pretty bad with a low resolution (even though I sent high-res files with 2100px x 1850px).

But still the finished cartridges look and feel great! It's nice to have something physical in hand instead of "just" software.

The cost for these came out to around 15€ per piece from AliExpress, excluding the label and working hours. There are other manufacturers of new carts for homebrew games, like insideGadgets, but surprisingly they are not really much cheaper, even for larger production runs.

It's also possible to manufacture your own cartridge PCBs, but there are some caveats with this. The main problem is the memory bank controller, in my case the most common MBC5 from Nintendo. They are no longer manufactured and can not be sourced new, so you either have to salvage them from original old donor games (which hurts the archivist in me too much) or find some kind of replacement.

Different people came up with implementations based on CPLDs or microcontrollers. Some of them are even open-source, like the MBC5 CPLD code from insideGadgets or Allison's Bootleg Cart. In a modern design you can use this with an FRAM chip to avoid the need for a backup battery for savegames, although this comes with some timing incompatibilities that may give problems with some games. You can also use a design with an SRAM and a coin cell. Many different flash chips are compatible in theory, though you need to make sure it can handle 5V or add voltage translation circuitry.

Unfortunately, doing some back-of-the-envelope cost calculation, this all comes out as more expensive for small production runs. It's cheaper and faster to just buy the chinese flash carts.

But to be honest, I'm not sure how much interest people would have in buying physical copies of this game anyway, so I shelved this idea for now. Of course you can always easily make your own if you'd like.

Asset Recreation

In order to get some inspiration from the original versions I extracted the relevant assets from the GTA:SA game files, like sprites, backgrounds, sound effects and music. I then re-created these in scaled-down versions that fit the Game Boy hardware.

Extrating the audio files can be done with Alci's SAAT GUI FrontEnd. The graphics can be extracted from .txd files with the TXD Workshop. Both of these run fine in Wine.

For the menu music I've re-created the San Andreas Theme, the game-over screen uses the victory fanfare from Final Fantasy VII. Fortunately both of these have spread very widely and there's lots of MIDI interpretations available. I used MuseScore to convert these MIDI files to sheet music and then transcribed the notes into my note lists in the source code.

The Duality in-game theme song was more difficult. It consists more of noises and some LFOs instead of clearly defined notes, so transcribing was pretty hard. In the end I used a trial version of AnthemScore in Wine to get an approximate idea of the notes, but the result is not great.

Here are some direct comparisons. First the San Andreas Theme, used as menu music.

Your browser does not support audio.

Download audio

Next the score screen music, which comes from the FF7 victory fanfare.

Your browser does not support audio.

Download audio

And the in-game music, from the original Duality.

Your browser does not support audio.

Download audio

Summary

I started working on this project at the end of May 2025, and basically finished it (to the state described here) at the end of July 2025, so in a span of about two months. Of course this was only a side-project in my free time, outside my real job that pays the bills. For this relatively short time I'm pretty happy with the results.

As always there is still lots of room for improvements.

The code needs to be optimized so it runs full-speed on the DMG, maybe by improving object handling and rendering, which has some 𝒪(𝓃²) behavior.

I also started working on a multiplayer mode, but due to me only having a single GBC and DMG to test each, I didn't really progress much there.

And the background map scrolling could be improved. I played around with mirroring the map when overflowing on the sides, like some kind of endless scrolling, but haven't gotten far unfortunately.

Working on a well-documented and well-designed retro game system like this was really lots of fun. In the future I hope to also take a closer look at other retro platforms.

License

The Duality source code is licensed under the GNU General Public License v3.

Copyright (C) 2025 Thomas Buck <thomas@xythobuz.de>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

See <http://www.gnu.org/licenses/>.

Duality uses the GBDK-2020 libraries and is based on their example code. The files sgb_border.c and sgb_border.h are copied directly from their sgb_border example.

The util/cvtsample.py script is based on a GBDK example.

The 8x8 font is public domain.

The included cartridge label graphic in artwork/cart_label.xcf is based on the 'Cartridge-Label-Templates' by Dinierto licensed as CC0.

The included cartridge graphic in artwork/cartridge.xcf is based on the 'Front-End-Assets' by Duimon.

AutoBrightness

Sat, 07 Sep 2024 12:00:00 -0000

One of my two ~10 year old 23" 1080p main displays died recently. So I finally upgraded to two used 27" 1440p displays. These are now the first displays on my desktop that allow adjustments of the backlight from software. So I tried to find out how to go about that.

Turns out on laptops both the display backlight intensity and the ambient light sensors are controlled via ACPI, with proper kernel support already available (see eg. the Arch Wiki).

But on desktops no standard for ambient light sensors seems to be established. Instead of ACPI, the backlight of some desktop monitors can be controlled using DDC/CI.

There are some projects, both hardware and software, available for this already. But as usual I decided to make my own.

Prototype Hardware

Initially I tought I could just go the most simple route and use an LDR on the ADC of an MCU. I already had a Digispark Rev. 3 clone, LDR, resistor and potentiometer on hand.

But deep down I already knew this would not be good.

The range of LDRs is far too big to easily measure the human eye dynamic range with an ADC. You can extend the range by switching different resistor values into your voltage divider using GPIOs, but I didn't want to go that far. Instead I added a 1M potentiometer to manually adjust the measurement range.

This gave me an opportunity to play around with integer low pass filters using bit shifts, as described here (which I got from here).

So as suspected, the resulting values were not able to measure both a dark room at night and a sunny day.

Proper Hardware

To get usable values I had to use a "real" sensor.

The final hardware is just a Digispark Rev. 3 clone with a GY-302 breakout board (for the BH1750 sensor) connected to it.

The BH1750 is a nice small ambient light sensor and very easy to use. This is literally the whole driver I wrote.

void luxInit(void) {
    twiWrite(LUX_ADDR, OP_POWER_ON); // reset registers
    twiWrite(LUX_ADDR, OP_CONT_0_5X); // continuous measurement at 0.5lx resolution
}

uint16_t luxGet(void) {
    uint16_t val = twiRead(LUX_ADDR); // read measurement
    return val;
}

USB Communication

The Digispark has the USB D+ and D- signals directly connected to GPIOs of the AtTiny85. So the USB protocol is bit-banged using the V-USB library. Because I did not use the Arduino Cores already available, I had to do some fiddling to configure the library properly for this device.

The code is based on the custom-class example from V-USB. This abuses USB control transfers to transmit data.

On the PC side I'm using PyUSB instead of going to libusb directly, as in the example.

CUSTOM_RQ_GET = 2 # get ldr value

def is_target_device(dev):
    if dev.manufacturer == "xythobuz.de" and dev.product == "AutoBrightness":
        return True
    return False

dev = usb.core.find(idVendor=0x16c0, idProduct=0x05dc, custom_match=is_target_device)
dev.set_configuration()

r = dev.ctrl_transfer(usb.util.CTRL_TYPE_VENDOR | usb.util.CTRL_IN, CUSTOM_RQ_GET, 0, 0, 2)
val = int.from_bytes(r, "little")

To run this without root permissions you need to add a udev rule (in eg. /etc/udev/rules.d/49-autobrightness.rules).

SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05dc", ATTRS{manufacturer}=="xythobuz.de", ATTRS{product}=="AutoBrightness", MODE:="0666"

I'm using the shared V-USB vendor and product IDs, so I have to always do the matching using my manufacturer and product strings as well.

Prototype Client

With the hardware side out of the way the next step was adjusting the display brightness. I made a short prototype using ddcutil to set the values.

To calculate the resulting values I made some measurements at midday (~500 lux) and night (~50 lux). And I thought about my habits (the MSI display seems ~10% brighter than the HP).

c_in = 0.6, -60.0, # in_a, in_b
calibration = {
    "HPN:HP 27xq:CNK1072BJY": [
        1.0, 30.0, # out_a, out_b
    ],

    "MSI:MSI G27CQ4:": [
        1.0, 20.0, # out_a, out_b
    ],
}

def cal(v, c):
    # out = out_b + out_a * in_a * max(0, in_b + in)
    return c[1] + c[0] * c_in[0] * max(0, c_in[1] + v)

This simple formula gives surprisingly good results. To avoid noticable noisy changes I do some simple low-pass filtering of the sensor values.

filter_fact = 0.9

def filter_lux(old, new):
    return (old * filter_fact) + (new * (1.0 - filter_fact))

All this just runs once per second.

Unfortunately, using ddcutil to adjust the brightness causes a noticable stutter of the whole system each time the value is changed. So this is not a good long-term solution.

Telling ddcutil to directly talk to the I2C bus helped a bit, but it still stutters slightly.

To alleviate this a bit I'm now using a KWin script to check for a full-screen app so I can pause brightness updates.

var win = workspace.activeWindow;
var name = win.caption;
var pid = win.pid;
var state = (win.bufferGeometry == win.output.geometry);
var obj = { name: name, pid: pid, fullscreen: state };
print(JSON.stringify(obj));

As usual I'm also sending all these values to my local InfluxDB.

Proper Client

My initial idea for the client was to use the ambient light sensor to also "calibrate" the two displays to each other. To do this, a white square could be shown on both screens. Then the sensor can be placed in front of each display to measure their brightness "ramps". This could then give the calibration dictionary shown above.

To determine the c_in values the room brightness has to be measured at day and night.

This should automate the process I've done manually to determine the calibration values.

But as you may have noticed, I'm more the prototype kind of guy and don't really do finished products on here. So...

To Do 😅

Update after a year (2025-07)

I have now been running this little gadget for nearly a year. It has been working great, and the calibration features above really seem unnecessary.

To improve usability slightly I've now also made a system-tray application.

License

The AutoBrightness project is licensed under the GNU General Public License.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

See <http://www.gnu.org/licenses/>.

Game Boy Color modding and experiments

Sun, 16 Mar 2025 12:00:00 -0000

I recently pulled out my old childhood Game Boy Color from a drawer to play around with it. The idea is to use LSDJ to accompany LARS. Unfortunately I kinda forgot how bad the GBC screen is, without any backlight.

So I looked around AliExpress a bit and found the store of HISPEEDIDO. They offer many nice modding kits for old consoles, so I got the OLED screen and USB-C battery replacements.

The installation is very easy, you just need to solder a single wire according to their manual and it all worked out fine.

I also found my old Game Boy printer, a small thermal printer that can be used with some games and, most importantly, the Game Boy camera.

I didn't have my old Game Boy camera, as I took it apart and used the sensor many years ago for my robot. So I got a used one on eBay.

Here are some photos I took for testing.

As you can tell, Ares has better contrast compared to Aphrodite 😄

And you really need to take the lighting situation into consideration.

To get the pictures off the cartridge I built an ESP8266-based WiFi printer emulator. I ordered these PCBs and soldered them to a LILYGO TTGO D1 mini as mentioned in the README of the PCB repo. The OLED screen was still left over from my E-Cig repair. The software running on there is the wifi-gbp-emulator.

To get back to the original topic of creating sounds though, there are multiple options. The most popular one, as mentioned, is LSDJ. This is basically a tracker or sequencer for the sound hardware in the Game Boy. Using external hardware, it can either sync on incoming MIDI signals or output MIDI notes for other devices. For the other way round, playing the Game Boy using incoming MIDI notes, the mGB synthesizer can be used.

The hardware to interface with these is called Arduinoboy, but I used the ProMicroGal fork with an ATmega32u4 that can interface to MIDI devices via USB, so I left out the hardware MIDI interface. You can get (backwards-compatible) GBA link cable sockets from AliExpress. To easily be able to solder them, I ordered the GB-BRK-LINK-B PCBs from the gb-hardware repo. I also was lazy and used pio to build the firmware.

To run LSDJ or mGB you can either use a EEPROM cartridge and write the ROM to it with a USB programmer, or get an Everdrive. Unfortunately they are really expensive, so I got a chinese clone (that is unfortunately no longer available, but you may be able to find others). It works fine with all games I tested and also both LSDJ and mGB.

And it's great fun, all GB and GBC games ever released come in at less than 2GB combined 🕵️

Pico BLE Vape Remote

Sat, 07 Dec 2024 12:00:00 -0000

Like many modern devices, some of the medical vaporizer devices from S&B (the Crafty, Venty and the Volcano Hybrid) offer Bluetooth connectivity and an app to control them.

Unfortunately the official mobile apps have / had some problems. The iOS version is no longer available after Apple decided to remove "drug related" Apps. So understandably the company no longer developed either their iOS or Android apps, instead releasing a web app that uses the Chrome Bluetooth APIs.

Yet all of these variants are problematic in different ways. The Android app offers customizable workflows for the Volcano Hybrid. But the Bluetooth implementation is very wonky, sometimes simply missing steps in the workflow. And because there's no error checking, the workflow simply continues in a broken state. The webapp doesn't have this problem, but instead the workflows are no longer customizable, instead just offering a small number of hard-coded pre-defined workflows.

This is not satisfying, of course, and also presented itself as a great opportunity to play around with BLE.

Fortunately the official web app is made with non-minimized an unobfuscated JavaScript, so the BLE protocol for the different devices can easily be reverse engineered. I wrote a small script that helps with downloading and beautifying the official sources.

As a first attempt I implemented the Volcano workflow functionality in Python on the PC. I had some problems, so I made two implementations, with bleak and SimplePyBLE. Turns out my difficulties came from having multiple bluetooth adapters on my Linux machine. Now the scripts both work fine for me.

Then I implemented the same thing on a Raspberry Pi Pico W, with a Waveshare Pico LCD 1.3 display. I first did this in MicroPython but ran into issues as well. It works fine but I couldn't include all the functionality I wanted.

So I made a fourth iteration, this time in C with the plain Pico SDK. It can interact with the Volcano Hybrid, the Crafty and the Venty. Everything can be controlled using on-screen menus on the device itself. It even has a WiFi capable OTA bootloader to support wireless firmware upgrades.

To contain everything I designed a snug little 3D-printed case in OpenSCAD. It contains the Pico W, a Pico LiPo Shim and a "80mAh / 20 x 11 x 5mm / 501220" LiPo battery. The Pi is mounted with four screws and the battery is held onto it with a drop of hot glue. Then the LCD board just plugs on top to close it.

This is what the final result looks like.

I'm quite happy with it, especially the software part. It has many things I expect from nice modern embedded projects, and I've used a bunch of libraries to achieve these:

Pico SDK for working with the Pico
- TinyUSB for the USB device implementation
- BTstack for the Bluetooth connection
FatFS for the USB filesystem
MCUFont for rendering text
st7789 for interacting with the LCD
picowota bootloader (modified to work with the Flash config storage and LCD)

As usual you can find everything on Codeberg and on GitHub.

iStick Pico 25 OLED Replacement

Mon, 16 Sep 2024 12:00:00 -0000

Years ago I bought a cheap chinese E-Cigarette 510 box mod, the Eleaf iStick Pico 25. It's running the ArcticFox custom firmware which sadly seems to be no longer available. I never really used it for anything, but for reasons I want to get it going again. Unfortunately the display is so dim that it can no longer be used. So I wanted to repair the device.

I found this comment on Reddit explaining that it's just a standard SSD1306 128x32 0.91" OLED display. This guy says initially Eleaf used ribbon cable connectors, making the replacement easy, and one shouldn't try without them. But actually soldering on a replacement is very easy.

First open the device and carefully remove the plastic display mount and desolder the ribbon cable.

The most difficult part for me was getting the replacement OLED removed from the breakout board. I used some lighter fuel to dissolve the glue and carefully levered and cut it off, trying not to break the glass or destroy the ribbon PCB.

Then just solder it on like any other SMD part.

Works great!

LARS v2

Sat, 07 Sep 2024 12:00:00 -0000

So you may have read about our project LARS. As mentioned I didn't have any hardware in the end to finish firmware development. So I slightly updated the circuitry, layed out a new board, had it manufactured in China and assembled at home.

This is LARS v2, the second iteration of the same idea.

It's basically the same device, just with five additional switches. This allows for some more freedom in the user interface design. Now the loop mode can mute individual tracks. There's also USB MIDI support.

As usual I've added auto-generated documentation, including interactive 3D renders of the PCB and some usage hints. The gerber files and BOM to order your own are also available.

Unfortunately I'm kind of in the same situation now as with LARS v1. I've gone much further with the firmware, it's now mostly usable. But I've also given the hardware away again, so I can't finish it.

~~I should assemble another one soon...~~

Assembly Guide

You want to build your own LARS v2 and have all the parts ready to go? Then let's build it!

In general you want to go from SMD / SMT (surface mount) parts to THT (through-hole), going from large to small for the SMD parts, and small to large for the THT parts.

First place the SMD Raspberry Pi Pico module so all pads are properly aligned.

Now first solder on one corner, then go through both rows.

The battery holder snaps in with two plastic clips. Soldering the pads can be a bit tricky. Even though there is a hole for the solder to flow through to the pad, you can not see it well. Try to apply a bit of pressure to get the pads to connect reliably.

Now place all the pushbuttons and solder them in. Their legs have a snap fit so they will hold on properly.

Next the resistors. I'm bending their legs slightly so they stay in place when turning the board over.

The diodes and LEDs can be placed next, with the same leg-bending trick as before.

The encoder snaps in as well. For the switch and OLED, make sure to apply a bit of pressure when turning the board over, so they are firmly in place.

The pins of the MOSFET module screw-terminals fit into the board holes and can be soldered on directly. For the small logic pins use a bit of the cut-off legs from the LEDs or resistors.

For the regulator I'm using standard pins like they probably came with your Pico. But you could also use some more of the cut-off legs from the previous steps.

The charger pad does not quite fit the connections of the module. So I'm using two pins per connection in a 90 degree angle.

And that's it.

Good luck and have fun!

xyBeast

Mon, 17 Jul 2017 12:00:00 -0000

...back to Flying RC Vehicles overview

Not being totally happy with the power available with my 2S xyAurora90 I decided to build a 3S Aurora100 in July 2017. The total weight with a 3S 450mAh battery is around 131g.

Here are some recordings of the FPV footage. Be aware that these videos are recorded from the received signal on the ground. Not only can you see lots of interference and other HF problems, the loss of quality from the video recorder and the YouTube encoding is also very noticeable. In real-life, the picture doesn't look that bad.

Initially I tried the 1104 7000KV DYS motors, but they had problems with vibrations I couldn't fix with any soft-mounting solutions I've tried, and after tuning the filters with a blackbox. I then swapped to the Eachine motors listed below, with them everything works perfectly with stock PID settings.

Also, at first I was using the Eachine 25mW AIO Cam with this build. However, because I flew often simultaneously with friends, we decided to all switch to RunCams and TBS transmitters, as listed below.

Parts List

These are the prices as recorded by Rotorbuilds. To be honest, I have no clue if they are what I paid back when I built this copter.

Part	Description	Cost
Frame	Eachine Aurora 100 100MM Mini Brushless FPV Multirotor Racing Frame 14.5g Carbon Fiber	11.99$
Spare	Eachine Aurora 100 Mini Brushless FPV Racer Spare Part 2mm 2.5mm Bottom Plate 3K Carbon Fiber	5.39$
FC	Eachine Minicube 20x20mm F4 OSD Compatible Frsky Flysky DSM RX Blheli_S 10A For Aurora 68 90 100	60.99$
Motors	4 x Eachine Upgrade Motor 1104 6500KV Brushless Motor 1-3S For Eachine Aurora 90 100 RC Drone FPV Racing	35.56$
Props	10 Pairs Racerstar 1935 50mm 5 Blade Racing Propeller 1.5mm Mounting Hole For Micro FPV Frame	8.29$
Cam	RunCam Micro Sparrow 2.1mm	31.97$
VTx	TBS Unify Pro V3 5V	54.74$
Bats	Tattu 450mAh 11.1V 75C 3S1P Lipo Battery Pack- Long Size for H Frame	15.89$
Misc	4 PCS Eachine Propeller Guard For Aurora 100 Mini FPV Racing RC Drone 1102 1103 1104 1105 Brushless Motor	2.49$
	Sum	227.31$

This write-up was first published on Rotorbuilds.

You can find my Betaflight configuration dumps here.

xyLX5

Wed, 01 Nov 2017 12:00:00 -0000

...back to Flying RC Vehicles overview

At the end of 2017 I had to give in to the urge of building a bigger more powerful copter. After my first failed attempts with large copters, gaining some experience with smaller frames seemed useful. But I had built up some skills and was ready for the next step. So I built a 220mm frame copter with 2205 motors.

It has all the bells-and-whistles available at the time, like DShot, Betaflight OSD, Smartaudio, as well as S-Bus and Smartport for two-way communication.

Using a 3D printed baseplate, I mounted the FrSky Rx as the third/top level of the PCB stack. To fit in the VTx as well, I simply zip-tied it to the bottom side of this plate.

To protect the remote control antennas, I added two zip-ties to the cockpit frame, trimmed to the length of the antennas, and shrinkwrapped the antenna coax cables to the whole zip-tie. This works very well as crash protection, I never managed to destroy an antenna with this setup.

The VTx Antenna pigtail is comfortably mounted with a special 3D printed piece. This way, the 5.8GHz Antenna (I'm using a Padoga v2) can easily be changed after crashes and removed for transportation.

For the bottom most level of the PCB stack I used rubber vibration-insulating stand-offs. I'm not sure if they are really necessary, but they don't seem to hurt either. Everything else is mounted with rigid spacers.

Parts List

These are the original prices I paid back when I initially bought the parts.

Part	Description	Cost
Frame	GEP-LX5 Leopard Frame, Green Color	47.20€
FC	Hobbywing XRotor Omnibus F4 Flight Controller	34.08€
ESCs	Hobbywing XRotor Micro 40A 2-5S 4 in 1 ESC	52.44€
Motors	4x Emax RS2205 2300KV CW/CCW Motor	46.32€
Props	10 Pairs Racerstar S5048 PC 3-blade Propeller 5.0mm Mounting Hole	10.48€
Cam	RunCam Micro Sparrow 2.1mm	26.22€
VTx	TBS Unify Pro V3 5V	44.90€
Rx	FrSky XSR	13.98€
Battery	SLS Quantum 1300mAh 4S1P 14,8V 65C/130C	26.00€
	Sum	301.62€

I have 3D printed the following parts for this copter:

You can find my Betaflight configuration dumps here.

Auto-generated project docs with 3D preview

Sun, 05 May 2024 12:00:00 -0000

A recurring problem I ran into with my projects is documentation. Especially with 3D printed parts or PCBs it's often required to generate preview images or PDFs so someone interested can take a look without having to clone the repo and install some development tools to open the original files. Doing this manually is time-consuming and repetitive. So it should be automated.

I've come across a couple of similar projects recently, like this or these. But they mostly spit out non-interactive images. So I've decided to go a slightly different and more interactive route.

Using GitHub Actions and GitHub Pages, I'm creating a static documentation website using mdBook. To visualize KiCad schematics and 2D board designs I'm exporting them as svg images and display them interactively using svg-pan-zoom. KiCad PCBs are also exported in 3D as VRML files and displayed using three.js.

To generate these files I'm mostly using shell scripts in the project repository.

generate_stls.sh is creating STL files from OpenSCAD sources
generate_fab.sh is creating Gerber files to order PCBs
generate_plot.sh is creating the 2D and 3D files for KiCad projects
generate_docs.sh is creating the static website using the output from the previous scripts

Then the workflows can be kept relatively short, just installing the required dependencies, running the proper script and putting the resulting files where they are needed. This way the coupling to the proprietary GitHub features is not that thight and can hopefully be ported to other providers with relative ease.

cmake.yml is creating firmware archives (also usable for OTA updates)
scad.yml to create the STL files
kicad.yml to generate board gerber files
docs.yml to create the static documentation pages

The whole workflow is relatively customizable. So for some projects I'm for example creating special board previews for etching PCBs at home.

I've implemented this workflow in a couple of projects now:

Take a look there for the implementation details.

Example Implementation

Here are the basics to get you started.

1) mdBook dependency

Fetch the pre-built mdBook binary and place it in your PATH.

2) mdBook initialization

Add a docs directory to your project, either by copying it from one of my repos, or creating a new one and adapting the resulting book.toml config.

mdbook init docs

3) svg-pan-zoom dependency

If you want to visualize SVG images for KiCad schematics and boards, add svg-pan-zoom as a subrepo.

cd docs
git submodule add https://github.com/bumbu/svg-pan-zoom
mkdir -p src/js
cd src/js
ln -s ../../svg-pan-zoom/dist/svg-pan-zoom.js svg-pan-zoom.js
ln -s ../../svg-pan-zoom/dist/svg-pan-zoom.min.js svg-pan-zoom.min.js

4) Generating docs

Add the docs/generate_docs.sh script and adapt the config and calls to other script at the beginning, as needed for your project:

Here is an example generate_docs.sh file.

#!/bin/bash

# SPDX-FileCopyrightText: 2024 Thomas Buck <thomas@xythobuz.de>
# SPDX-License-Identifier: CERN-OHL-S-2.0+
#
#  ------------------------------------------------------------------------------
# | Copyright (c) 2024 Thomas Buck <thomas@xythobuz.de>                          |
# |                                                                              |
# | This source describes Open Hardware and is licensed under the CERN-OHL-S v2  |
# | or any later version.                                                        |
# |                                                                              |
# | You may redistribute and modify this source and make products using it under |
# | the terms of the CERN-OHL-S v2 (https://ohwr.org/cern_ohl_s_v2.txt)          |
# | or any later version.                                                        |
# |                                                                              |
# | This source is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,          |
# | INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A         |
# | PARTICULAR PURPOSE. Please see the CERN-OHL-S v2 (or any later version)      |
# | for applicable conditions.                                                   |
# |                                                                              |
# | Source location: https://git.xythobuz.de/thomas/drumkit                      |
# |                                                                              |
# | As per CERN-OHL-S v2 section 4, should You produce hardware based on this    |
# | source, You must where practicable maintain the Source Location visible      |
# | on the external case of the Gizmo or other products you make using this      |
# | source.                                                                      |
#  ------------------------------------------------------------------------------

INSCH="../pcb/drumkit.kicad_sch ../pcb2/lars2.kicad_sch"
INPCB="../pcb/drumkit.kicad_pcb ../pcb2/lars2.kicad_pcb"

cd "$(dirname "$0")"

if [ "$1" = "build" ] ; then
    echo "Generating plots"
    ../pcb/generate_plot.sh
    echo
    echo "Generating fab"
    ../pcb/generate_fab.sh
    echo

    echo "Generating plots 2"
    ../pcb2/generate_plot.sh
    echo
    echo "Generating fab 2"
    ../pcb2/generate_fab.sh
    echo

    echo "Generating stls"
    ../3dprint/generate_stls.sh
    echo
fi

rm -rf src/plot
cp -r ../pcb/plot src
cp -r ../pcb2/plot/* src/plot/
cp ../pcb/fab.zip src/plot/fab_pcb.zip
cp ../pcb2/fab.zip src/plot/fab_pcb2.zip

rm -rf src/stl
cp -r ../3dprint/stl src

INSTL=`ls ../3dprint/stl/*.stl`

for path in $INSCH
do
    IN=`echo $path | sed "s:../pcb.\\?/::g"`
    o="src/inc_$IN.md"
    echo "Include for $IN at $o"

    rm -rf $o
    echo "<script src=\"js/svg-pan-zoom.js\" charset=\"UTF-8\"></script>" >> $o

    for f in `ls src/plot/$IN.svg/*.svg | sort -r`; do
        file=`echo $f | sed 's:src/:./:g'`
        name=`echo $f | sed "s:src/plot/$IN.svg/::g" | sed 's:.svg::g'`
        echo "Sheet at $name"

        echo "<h2>$name</h2>" >> $o
        echo "<div style=\"background-color: white; border: 1px solid black;\">" >> $o
        echo "<embed type=\"image/svg+xml\" src=\"$file\" id=\"pz_$name\" style=\"width:100%;\"/>" >> $o
        echo "<script>" >> $o
        echo "document.getElementById('pz_$name').addEventListener('load', function(){" >> $o
        echo "svgPanZoom(document.getElementById('pz_$name'), {controlIconsEnabled: true, minZoom: 1.0});" >> $o
        echo "})" >> $o
        echo "</script>" >> $o
        echo "</div>" >> $o
        echo >> $o
        echo "[Direct link to \`$name\`]($file)." >> $o
        echo >> $o
    done

    echo
done

plot_3d() {
    echo '<script type="importmap">' >> $1
    echo '    {' >> $1
    echo '        "imports": {' >> $1
    echo '            "three": "https://cdn.jsdelivr.net/npm/three@0.163.0/build/three.module.js",' >> $1
    echo '            "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.163.0/examples/jsm/"' >> $1
    echo '        }' >> $1
    echo '    }' >> $1
    echo '</script>' >> $1
    echo "<p>Status: \"<span id=\"3d_info_$2\">Preparing 3D model...</span>\"</p>" >> $1
    echo "<div id=\"3d_viewer_$2\" style=\"width: 100%; height: 100%; background-color: white; border: 1px solid black; position: relative;\"></div>" >> $1
    echo '<script type="module">' >> $1
    echo "    var info = document.getElementById(\"3d_info_$2\");" >> $1
    echo "    var view = document.getElementById(\"3d_viewer_$2\");" >> $1
    echo '    view.style.height = Math.floor(view.clientWidth * 0.707) + "px";' >> $1
    echo '    import { init_3d } from "./js/3d.js";' >> $1
    echo "    init_3d(\"$3\", view, info, view.clientWidth, view.clientHeight);" >> $1
    echo '</script>' >> $1
}

for path in $INPCB
do
    IN=`echo $path | sed "s:../pcb.\\?/::g"`
    o="src/inc_$IN.md"
    file="plot/$IN.wrl"
    name=`echo $file | sed "s:plot/::g" | sed 's:.wrl::g'`
    echo "Include for $IN at $o, $file, $name"
    rm -rf $o

    plot_3d $o $name $file
done
echo

for IN in $INSTL
do
    o=`echo $IN | sed "s:../3dprint/stl/:src/inc_:g" | sed "s:.stl:.stl.md:g"`
    file=`echo $IN | sed "s:../3dprint/::g"`
    name=`echo $file | sed "s:stl/::g" | sed 's:.stl::g'`
    echo "Include for $IN at $o, $file, $name"
    rm -rf $o

    plot_3d $o $name $file
done
echo

echo "Generating docs"
if [ "$1" = "serve" ] ; then
    mdbook serve --open
elif [ "$1" = "build" ] ; then
    mdbook build
else
    echo "Invalid command. 'build' or 'serve'."
fi

5) Auto-generating and publishing docs

Add the .github/workflows/docs.yml script:

Here is an example docs.yml file.

# SPDX-FileCopyrightText: 2024 Thomas Buck <thomas@xythobuz.de>
# SPDX-License-Identifier: CERN-OHL-S-2.0+
#
#  ------------------------------------------------------------------------------
# | Copyright (c) 2024 Thomas Buck <thomas@xythobuz.de>                          |
# |                                                                              |
# | This source describes Open Hardware and is licensed under the CERN-OHL-S v2  |
# | or any later version.                                                        |
# |                                                                              |
# | You may redistribute and modify this source and make products using it under |
# | the terms of the CERN-OHL-S v2 (https://ohwr.org/cern_ohl_s_v2.txt)          |
# | or any later version.                                                        |
# |                                                                              |
# | This source is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,          |
# | INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A         |
# | PARTICULAR PURPOSE. Please see the CERN-OHL-S v2 (or any later version)      |
# | for applicable conditions.                                                   |
# |                                                                              |
# | Source location: https://git.xythobuz.de/thomas/drumkit                      |
# |                                                                              |
# | As per CERN-OHL-S v2 section 4, should You produce hardware based on this    |
# | source, You must where practicable maintain the Source Location visible      |
# | on the external case of the Gizmo or other products you make using this      |
# | source.                                                                      |
#  ------------------------------------------------------------------------------

name: Docs

# only build single instance of docs for latest main branch
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: write
      pages: write
      id-token: write

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Checkout repo submodules
        run: git submodule update --init

      - name: Install dependencies
        run: |
          sudo add-apt-repository --yes ppa:kicad/kicad-8.0-releases
          sudo apt update
          sudo apt install -y --install-recommends kicad pipx libfuse2 libegl1 poppler-utils openscad zip

      - name: Install latest mdbook
        run: |
          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
          mkdir mdbook
          curl -sSL $url | tar -xz --directory=./mdbook
          echo `pwd`/mdbook >> $GITHUB_PATH

      - name: Build Book
        run: docs/generate_docs.sh build

      - name: Setup Pages
        uses: actions/configure-pages@v2

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: 'docs/book'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

And don't forget to set the GitHub Pages source in the repo settings to GitHub Actions:

6) STL 3D visualization

If you want to visualize 3D print files, do the same with 3dprint/generate_stls.sh and .github/workflows/scad.yml:

Here is an example generate_stls.sh file.

#!/bin/bash

# ----------------------------------------------------------------------------
# Copyright (c) 2023 Kauzerei (openautolab@kauzerei.de)
# Copyright (c) 2023 Thomas Buck (thomas@xythobuz.de)
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# See <http://www.gnu.org/licenses/>.
# ----------------------------------------------------------------------------

# space separated list of scad files (without extension)
MODULES="actuator beam enclosure tamb_mount"
OUTDIR="stl"

# enter directory of script (case)
cd "$(dirname "$0")"

# Detect OS
if [[ "$OSTYPE" == "darwin"* ]]; then
    echo "Mac OS X detected"
    SCAD="open -n -a OpenSCAD --args"
else
    echo "Linux detected"
    SCAD="openscad"
fi

echo "deleting previous build output"
rm -rf $OUTDIR
mkdir -p $OUTDIR

for MODULE in $MODULES
do
    PARTS=$(grep -o "part.*//.*\[.*]" ${MODULE}.scad | sed 's/,/ /g' | sed 's/.*\[\([^]]*\)\].*/\1/g')
    echo "generating from ${MODULE}"

    for PART in ${PARTS}
    do
        if [[ "${PART}" != "OPT_"* ]]; then
            echo ${PART}
            FILENAME=$(echo $OUTDIR/${MODULE}_${PART}.stl | tr '[:upper:]' '[:lower:]')
            $SCAD $(pwd)/${MODULE}.scad --D part=\"${PART}\" --o $(pwd)/${FILENAME}
        fi
    done
done

Here is an example scad.yml file.

# SPDX-FileCopyrightText: 2024 Thomas Buck <thomas@xythobuz.de>
# SPDX-License-Identifier: CERN-OHL-S-2.0+
#
#  ------------------------------------------------------------------------------
# | Copyright (c) 2024 Thomas Buck <thomas@xythobuz.de>                          |
# |                                                                              |
# | This source describes Open Hardware and is licensed under the CERN-OHL-S v2  |
# | or any later version.                                                        |
# |                                                                              |
# | You may redistribute and modify this source and make products using it under |
# | the terms of the CERN-OHL-S v2 (https://ohwr.org/cern_ohl_s_v2.txt)          |
# | or any later version.                                                        |
# |                                                                              |
# | This source is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,          |
# | INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A         |
# | PARTICULAR PURPOSE. Please see the CERN-OHL-S v2 (or any later version)      |
# | for applicable conditions.                                                   |
# |                                                                              |
# | Source location: https://git.xythobuz.de/thomas/drumkit                      |
# |                                                                              |
# | As per CERN-OHL-S v2 section 4, should You produce hardware based on this    |
# | source, You must where practicable maintain the Source Location visible      |
# | on the external case of the Gizmo or other products you make using this      |
# | source.                                                                      |
#  ------------------------------------------------------------------------------

name: STLs

# build for each push and pull request
on: [push, pull_request]

jobs:
  render:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Checkout repo submodules
        run: git submodule update --init

      - name: Install dependencies
        run: |
          sudo apt update
          sudo apt-get install -y openscad zip

      - name: Render STLs
        run: |
          ./3dprint/generate_stls.sh

      - name: Upload part files
        uses: actions/upload-artifact@v4.0.0
        with:
          name: drumkit-stl
          path: 3dprint/stl
          if-no-files-found: error

      - name: Archive release files
        if: startsWith(github.ref, 'refs/tags/')
        run: |
          cd 3dprint
          zip -r drumkit-stl stl

      - name: Upload release files
        if: startsWith(github.ref, 'refs/tags/')
        uses: softprops/action-gh-release@v1
        with:
          files: 3dprint/drumkit-stl.zip

And then add something like this to the mdBook sources where you want the visualization to appear:

\{{#include inc_enclosure_bottom.stl.md}}

[Direct link to this file](./stl/enclosure_bottom.stl).

7) PCB gerber files

If you want to generate gerber files from PCBs, do something similar with pcb/generate_fab.sh and .github/workflows/kicad.yml:

Here is an example generate_fab.sh file.

#!/bin/bash

# SPDX-FileCopyrightText: 2024 Thomas Buck <thomas@xythobuz.de>
# SPDX-License-Identifier: CERN-OHL-S-2.0+
#
#  ------------------------------------------------------------------------------
# | Copyright (c) 2024 Thomas Buck <thomas@xythobuz.de>                          |
# |                                                                              |
# | This source describes Open Hardware and is licensed under the CERN-OHL-S v2  |
# | or any later version.                                                        |
# |                                                                              |
# | You may redistribute and modify this source and make products using it under |
# | the terms of the CERN-OHL-S v2 (https://ohwr.org/cern_ohl_s_v2.txt)          |
# | or any later version.                                                        |
# |                                                                              |
# | This source is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,          |
# | INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A         |
# | PARTICULAR PURPOSE. Please see the CERN-OHL-S v2 (or any later version)      |
# | for applicable conditions.                                                   |
# |                                                                              |
# | Source location: https://git.xythobuz.de/thomas/drumkit                      |
# |                                                                              |
# | As per CERN-OHL-S v2 section 4, should You produce hardware based on this    |
# | source, You must where practicable maintain the Source Location visible      |
# | on the external case of the Gizmo or other products you make using this      |
# | source.                                                                      |
#  ------------------------------------------------------------------------------

cd "$(dirname "$0")"

INFILE="lars2.kicad_pcb"
INFILE_SCH="lars2.kicad_sch"
OUTDIR="fabrication"
OUTZIP="fab"

echo "Creating output directory"
rm -rf $OUTDIR
mkdir -p $OUTDIR

echo "Exporting drill files"
#kicad-cli pcb export drill -o $OUTDIR/ --format excellon --generate-map --map-format pdf $INFILE
kicad-cli pcb export drill -o $OUTDIR/ --format gerber --generate-map --map-format gerberx2 $INFILE

echo "Exporting gerber files"
#kicad-cli pcb export gerbers -o $OUTDIR/ $INFILE
kicad-cli pcb export gerbers -o $OUTDIR/ -l F.Cu,B.Cu,F.Mask,B.Mask,F.Paste,B.Paste,F.Silkscreen,B.Silkscreen,Edge.Cuts $INFILE

echo "Exporting BOM files"
kicad-cli sch export python-bom -o $OUTDIR/bom.xml $INFILE_SCH

# TODO convert BOM XML to proper format for JLCPCB

echo "Compressing archive"
rm -rf $OUTZIP.zip
zip -r $OUTZIP fabrication

Here is an example kicad.yml file.

# SPDX-FileCopyrightText: 2024 Thomas Buck <thomas@xythobuz.de>
# SPDX-License-Identifier: CERN-OHL-S-2.0+
#
#  ------------------------------------------------------------------------------
# | Copyright (c) 2024 Thomas Buck <thomas@xythobuz.de>                          |
# |                                                                              |
# | This source describes Open Hardware and is licensed under the CERN-OHL-S v2  |
# | or any later version.                                                        |
# |                                                                              |
# | You may redistribute and modify this source and make products using it under |
# | the terms of the CERN-OHL-S v2 (https://ohwr.org/cern_ohl_s_v2.txt)          |
# | or any later version.                                                        |
# |                                                                              |
# | This source is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,          |
# | INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A         |
# | PARTICULAR PURPOSE. Please see the CERN-OHL-S v2 (or any later version)      |
# | for applicable conditions.                                                   |
# |                                                                              |
# | Source location: https://git.xythobuz.de/thomas/drumkit                      |
# |                                                                              |
# | As per CERN-OHL-S v2 section 4, should You produce hardware based on this    |
# | source, You must where practicable maintain the Source Location visible      |
# | on the external case of the Gizmo or other products you make using this      |
# | source.                                                                      |
#  ------------------------------------------------------------------------------

name: PCB

# build for each push and pull request
on: [push, pull_request]

jobs:
  fabrication:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Checkout repo submodules
        run: git submodule update --init

      - name: Install dependencies
        run: |
          sudo add-apt-repository --yes ppa:kicad/kicad-8.0-releases
          sudo apt update
          sudo apt install -y --install-recommends kicad
          sudo apt-get install -y zip

      - name: Generate fabrication files
        run: |
          ./pcb/generate_fab.sh
          ./pcb2/generate_fab.sh

      - name: Upload board files
        uses: actions/upload-artifact@v4.0.0
        with:
          name: prototype-pcb
          path: pcb/fabrication

      - name: Upload board files
        uses: actions/upload-artifact@v4.0.0
        with:
          name: v2-pcb
          path: pcb2/fabrication

      - name: Rename release files
        if: startsWith(github.ref, 'refs/tags/')
        run: |
          mv pcb/fab.zip fab_proto.zip
          mv pcb2/fab.zip fab_v2.zip

      - name: Upload release files
        if: startsWith(github.ref, 'refs/tags/')
        uses: softprops/action-gh-release@v1
        with:
          files: fab_proto.zip fab_v2.zip

8) PCB visualization

If you want to visualize KiCad schematics and PCBs in 2D and 3D, add pcb/generate_plot.sh:

Here is an example generate_plot.sh file.

#!/bin/bash

# SPDX-FileCopyrightText: 2024 Thomas Buck <thomas@xythobuz.de>
# SPDX-License-Identifier: CERN-OHL-S-2.0+
#
#  ------------------------------------------------------------------------------
# | Copyright (c) 2024 Thomas Buck <thomas@xythobuz.de>                          |
# |                                                                              |
# | This source describes Open Hardware and is licensed under the CERN-OHL-S v2  |
# | or any later version.                                                        |
# |                                                                              |
# | You may redistribute and modify this source and make products using it under |
# | the terms of the CERN-OHL-S v2 (https://ohwr.org/cern_ohl_s_v2.txt)          |
# | or any later version.                                                        |
# |                                                                              |
# | This source is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,          |
# | INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A         |
# | PARTICULAR PURPOSE. Please see the CERN-OHL-S v2 (or any later version)      |
# | for applicable conditions.                                                   |
# |                                                                              |
# | Source location: https://git.xythobuz.de/thomas/drumkit                      |
# |                                                                              |
# | As per CERN-OHL-S v2 section 4, should You produce hardware based on this    |
# | source, You must where practicable maintain the Source Location visible      |
# | on the external case of the Gizmo or other products you make using this      |
# | source.                                                                      |
#  ------------------------------------------------------------------------------

INSCH="lars2.kicad_sch"
INPCB="lars2.kicad_pcb"
OUTDIR="plot"
LAYER_F="F.Cu,F.Mask,F.Paste,F.Silkscreen,Edge.Cuts,User.Drawings"
LAYER_B="B.Cu,B.Mask,B.Paste,B.Silkscreen,Edge.Cuts,User.Drawings"
LAYER_MANUAL="B.Cu,Edge.Cuts"

cd "$(dirname "$0")"
rm -rf $OUTDIR
mkdir -p $OUTDIR

#  --------------
# | 2D Schematic |
#  --------------

for IN in $INSCH
do
    echo "Exporting schematic $IN"

    for TYPE in pdf svg
    do
        echo "Exporting schematic $TYPE"
        rm -rf $OUTDIR/$IN.$TYPE
        kicad-cli sch export $TYPE \
            -t "KiCad Default" \
            -o $OUTDIR/$IN.$TYPE \
            $IN
        echo
    done
done

for IN in $INPCB
do
    echo "Exporting board $IN"

    #  -----------
    # | 2D Layout |
    #  -----------

    for TYPE in pdf svg
    do
        rm -rf $OUTDIR/$IN.$TYPE

        echo "Exporting board $TYPE"
        kicad-cli pcb export $TYPE \
            -t "KiCad Classic"  \
            -l $LAYER_F,$LAYER_B \
            -o $OUTDIR/$IN.$TYPE \
            $IN
        echo

        echo "Exporting DIY board $VAR"
        rm -rf $OUTDIR/${IN}_diy.$TYPE
        kicad-cli pcb export $TYPE \
            -t "KiCad Default"  \
            -l $LAYER_MANUAL \
            --black-and-white \
            --negative \
            -o $OUTDIR/${IN}_diy.$TYPE \
            $IN
        echo
    done

    #  -----------
    # | 3D Layout |
    #  -----------
    echo "Exporting board 3D"
    kicad-cli pcb export vrml \
        -o $OUTDIR/$IN.wrl \
        $IN
    echo
done

Then include this where you want the 2D schematic visualization to appear:

You can also view the [schematics as PDF](./plot/lars2.kicad_sch.pdf).

\{{#include inc_lars2.kicad_sch.md}}

And this where you want to visualize the 2D PCB layout:

You can also view the [2D PCB layout as PDF](./plot/lars2.kicad_pcb.pdf).

<script src="js/svg-pan-zoom.js" charset="UTF-8"></script>
<div style="background-color: white; border: 1px solid black;">
    <embed type="image/svg+xml" src="./plot/lars2.kicad_pcb.svg" id="pz_drumkit0" style="width: 100%;"/>
    <script>
        document.getElementById('pz_drumkit0').addEventListener('load', function(){
            svgPanZoom(document.getElementById('pz_drumkit0'), {controlIconsEnabled: true, minZoom: 1.0});
        })
    </script>
</div>

[Direct link to this file](./plot/lars2.kicad_pcb.svg).

And add this where you want to visualize the 3D PCB layout:

\{{#include inc_lars2.kicad_pcb.md}}

That should more or less be all that's required.

Of course, adapt paths as needed to match your project layout. And test locally by calling the scripts manually on your machine:

./pcb/generate_plot.sh
./3dprint/generate_stls.sh

./docs/generate_docs.sh serve

Hope this helps.

LARS - Looping Automated Rhythm Station

Mon, 25 Mar 2024 12:00:00 -0000

For the recent birthday party of one of our DrinkRobotics and musician friends, Kauzerei had the great idea to build a DIY drummachine as a present, to allow them to play the bass without having to gather a jam session group. He recruited me for some electronics design brainstorming and to write the firmware.

It is mainly made out of repurposed old parts from the recycling bin. The drum body consists of a tambourine with a 3D printed frame attached, with three hand-wound solenoids mounted on there. The positioning and different hammers create some (slightly) differing sounds.

The electronics are made with a Raspberry Pi Pico (or Pico W in this case, although WiFi or BT are not used yet). This keeps the future option of a USB Midi input open. The user interface consists of four buttons, each with an LED above, and a clickable rotary encoder, as well as a power switch and an 128x64 SSD1306 OLED display. To drive the solenoids, three step-up converters create ~16V from the single Li-Ion 18650 cell. Their output is then switched to the solenoids using MOSFETs. A small TP4056 module handles recharging the battery.

All of this is mounted on a custom hand-etched PCB.

We only came three hours late to the birthday party due to finishing the LARS hardware, and I spent some more time at the party putting some final work into the firmware. It actually was functionally usable on the party evening, even before everyone was too drunk to care 🥴

Unfortunately there was no time yet to take good pictures or a video of LARS in action.

As usual all 3D print files, PCB layout design and firmware source code is available in the repo. You can also order the PCB pre-fabricated from an online supplier, the repo includes a script to generate the gerber files.

The software is not quite finished yet, but without access to the hardware I'm not really able to work on it further.

For now...

More Pictures

Some more photographs I didn't use above.

Toolbox Markdorf anniversary

Sat, 09 Mar 2024 12:00:00 -0000

Last saturday our local hackerspace, the Toolbox Markdorf, held it's 10 year anniversary celebrations with an open-door-day.

I set up my tents in the E-Lab 2 to show off some projects, mainly the Oscilloscope Music player and the LED Matrix as well as my Quadcopter stuff.

Outside, in the afternoon, I also did a bit of FPV flying with a TV and receiver setup for the spectators.

We had a surprisingly large number of visitors. Hopefully this will help get things going again after the Covid dull.

More Pictures

Some more photographs I didn't use above.

Oscilloscope Music Player

Sun, 11 Feb 2024 12:00:00 -0000

Soon our local hackerspace Toolbox Bodensee has its 10-year anniversary, and it will also be present at the IBO fair 2024 in Friedrichshafen. Some five or six years ago I already prepared a small setup at one of the Toolbox open-door-days with an oscilloscope and a laptop playing Jerobeam Fendersons Oscilloscope Music. But it never looked quite right. So I decided to tackle the topic again this year.

Want to build your own player? Skip to the interesting part then!

Introduction

An oscilloscope usually displays one or more waveforms of an electrical signal. To achieve this a single dot is moved across the screen, with the voltage or amplitude of the signal controlling the vertical deflection (Y axis), and time controlling the horizontal deflection (X axis), meaning the dot automatically moves from left to right with a pre-configured speed. But most oscilloscopes can also be configured in something called XY mode, where the horizontal deflection is no longer controlled by time, but instead by another voltage. This turnes the oscilloscope into a vector display, where a single dot can be moved across the screen. Note that the brightness can not be controlled, it is fixed. Some oscilloscopes have a third input that can be used for that, but this is not needed here.

A common way to achieve digital to analog conversion (DAC) of a signal, with hardware usually available in every household, is using the soundcard of a PC. The stereo line output channels are basically connected directly to a DAC chip, with only some filtering hardware in between.

Now combining these concepts, one can connect the two audio output channels of a PC or similar device to the two inputs of an oscilloscope in XY mode. This enables a kind of visualization of music, and was also used in the past in something called "audio vectorscope" to check the balance of the channels. If you have a mono signal, with both channels having the exact same contents, the scope will display a 45-degree angled line. If only one channel has contents, and the other is silent, you will see either a horizontal or a vertical line, depending on which channel is active. When one channel outputs a sine, and the other a cosine, with the same frequency and phase, you will see a circle.

Of course with normal music this doesn't look that interesting. But what if you were to specifically compose music to look good on such a device?

That's what Oscilloscope Music is.

Artists

To generate the proper sounds you usually need some kind of software or self-written code. Many people have already experimented with this, with small scripts running on a PC, or directly on a microcontroller.

In 2016 Jerobeam Fenderson released an album based on this concept. He also collaborated with Hansi Raber and they released some software to play and generate this music. You can also find high-quality recordings on his YouTube channel.

I also found Chris Allen on YouTube, another artist that offers a download of the original files.

Playback

So there are some technical challenges involved in playing these properly on an oscilloscope.

First, it is not enough to play these from YouTube or small MP3 files, as the compression algorithms remove too much of the visual contents of the music. So original WAV file downloads are required.

Second, most audio outputs are AC coupled instead of DC coupled. What does that mean? Audio is normally an AC signal without any DC bias. The spekaer membrane is more or less constantly moving around it's resting position. If there were a DC offset, this would mean the membrane has a constant offset to one side, but would then vibrate there as usual. So the sound waves generated are the same. That's why normally theres a capacitor in line with the audio signal, blocking the DC contents. But when you consider our oscilloscope, if you want to draw a straight line with an offset from the center of the screen, this looks like a DC bias on the signal, which would be filtered out by the capacitor, causing the line to appear in the middle of the screen instead. So the impact of this depends on the image shown. If it is symmetrical around the center of the screen, not much will be distorted, but in other cases the image can be completely unrecognizable.

Third, the audio files have a sample rate of 192kHz. It's usually assumed that average humans don't hear sounds above 20kHz, so according to Shannon, a sample rate of 40kHz is enough to capture all sounds interesting for humans. But to draw many interesting shapes in a short time, higher frequencies are needed. So you need a fast 192kHz DAC and the proper settings in your OS or player software to actually output this without downsampling happening somewhere in the chain.

So how can you achieve these in practice? Interestingly, most Apple devices have a DC coupled output. So when using these, you already get pretty close to the intended output.

We also tried a "proper" Behringer UMC404HD USB audio interface from the Toolbox Sound Studio, but the output was the worst of all devices tried. Even using random cheap AC coupled phone or laptop DACs looked way better.

But the best solution came in the form of the Hifiberry DACs. These are DC coupled, support 192kHz and are cheap and easy to get.

Now the image finally looks like in the YouTube videos. The only problem is, this is supposed to be used and operated at Toolbox events, so it needs to be easy to use and kind of sturdy.

Oscilloscope Settings

To get the proper picture out of your oscilloscope you need to set it up correctly. Every oscilloscope has its own kind of front panel buttons, but in general they all have more or less the same kind of settings.

You need to set the voltage range of both inputs you're using, usually CH1 and CH2, to the same value, something like 0.5V or 0.2V. This changes the size of the image on the screen, just like changing the volume on the Raspberry Pi does, too. My script has an option on top for the volume percentage. You need to adjust these values so the image properly fills your screen, without drawing outside of its borders. The output of the Pi should be put as high as possible, to reduce the influence of electrical noise. Then set the proper range of the oscilloscope, which usually has pretty big steps, so do the final fine-adjustment with the percentage in the script.

Both input channels should be set to DC coupling.

And you need to put the scope in XY mode.

Put the intensity as high as needed, but as low as possible, to maximize the lifetime of the phosphor coating of the tube.

Adjust the focus so you have the sharpest possible image.

Use the horizontal and vertical position controls to center the image on the screen.

In the case of my Tektronix 2215A, the XY mode hides as one of the steps of the right-most rotational input, the timebase or A and B SEC/DIV. In the picture below I marked all settings you may need to adjust.

Hardware

We need to consider the environments this device will be used in. Both at the Toolbox anniversary, as well as the IBO fair, it will be displayed as part of a public show, with many people walking by and maybe stopping for a short time. And I will not be there all the time, so it will be operated by other Toolbox members (setting it up, turning it on or off), or even the visitors (switching tracks).

With the part selection outlined above, the solution was kind of obvious. Have a script on the Pi, automatically starting playback of the music files, with a small OLED and some buttons to control playback, and ideally with some kind of UPS for ease of powering the device and properly shutting down to not corrupt the SD card.

Here are the parts I used and the prices I paid at the time of building this.

Part	Description	Cost
Pi	Raspberry Pi Zero 2 W	24.49€
DAC	HiFiBerry DAC+ Zero	30.99€
Batt	PiSugar 2	35.99€
OLED	SSD1306 I2C 128x64	4.40€
Btns	2x 12mm momentary switch	1.60€
Conn	2x Cinch panel mount	1.60€
Amp	Stereo amplifier module	1.40€
Spkr	Stereo speakers	5.00€
Ext	Micro-USB panel mount	7.69€
BNC	Cinch to BNC adapter	0.50€
Pot	Volume knob	0.85€
Cable	Cinch stereo cable	~2.00€
Case	Lunchbox from supermarket	~5.00€
	Sum	85.52€

Of course you also need some bits of copper wire for the internal connections inside the device. I also used a bunch of male and female 2.54mm pin headers to be able to disconnect stuff. Also M2.5 spacers to properly mount the PCBs around the Pi Zero, M2 spacers for the OLED, as well as a couple of cable-ties.

For this project I decided to use a cheap plastic lunchbox as a case. This worked relatively well. Just take care with the lid, it was quite hard in my case, causing it to crack when I tried to drill a hole that was too big. But some superglue saved the day.

Software

I've been using the Raspberry Pi OS (Legacy, 32bit) Lite image. Install it as usual, set up a user account, wireless network connection and SSH login.

Prepare the environment by installing all required dependencies:

sudo sh -c 'echo "dtoverlay=hifiberry-dac" >> /boot/config.txt'
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install python3 python3-pip python3-pil libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libopenjp2-7 libtiff5 ffmpeg
curl "http://cdn.pisugar.com/release/pisugar-power-manager.sh" | sudo bash
pip install pisugar luma.oled psutil
sudo usermod -a -G spi,gpio,i2c $USER

Reboot after the last command so the new settings take effect and the power manager can do its thing. If in doubt, also take a look at the PiSugar 2 manual.

Next put the script that controls playback on the device. Here is ~/osci-pi.py.

#!/usr/bin/env python3

# IP address code taken from:
# https://github.com/rm-hull/luma.examples/blob/master/examples/sys_info_extended.py
#
# ----------------------------------------------------------------------------
# Copyright (c) 2024 Thomas Buck (thomas@xythobuz.de)
# Copyright (c) 2024 Philipp Schönberger (mail@phschoen.de)
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# See <http://www.gnu.org/licenses/>.
# ----------------------------------------------------------------------------

import sys
import os
import random
import subprocess
import signal
import glob
import socket
from collections import OrderedDict
import time

import pisugar
from luma.core.interface.serial import i2c
from luma.core.render import canvas
from luma.oled.device import ssd1306
from luma.core.error import DeviceNotFoundError
import psutil
import RPi.GPIO as GPIO
from PIL import ImageFont

basevol = "70"
debouncems = 100

#fontfile = "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"
fontfile = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
fontsize = 11

LCD_REFRESH = 5.0

BTN_ARTIST = 16
BTN_NEXT = 26

currentplaying = None
lcd = None
font = None
bat = None
songlist = None
currentfile = None
lasttime = None
currvol = basevol

vol_list = [
    ("Harley_Matthews", "100"),
    ("xythobuz", "50"),
]

basedir = sys.argv[1]
if basedir.endswith("/"):
    basedir = basedir.removesuffix("/")

def get_artist(fn):
    global currvol
    parts = fn.replace(basedir + "/", "").split(os.sep)
    artist = parts[0].replace("_", " ")
    currvol = basevol
    for i in vol_list:
        if i[0] in fn:
            currvol = i[1]
            break
    return artist

originalsongs = []
originalartists = []
for fn in glob.iglob(os.path.join(basedir, '**', '*.wav'), recursive=True):
    originalsongs.append(fn)

    artist = get_artist(fn)
    if artist not in originalartists:
        originalartists.append(artist)

artists = originalartists.copy()
random.shuffle(artists)
currentartist = artists[0]

def find_single_ipv4_address(addrs):
    for addr in addrs:
        if addr.family == socket.AddressFamily.AF_INET:  # IPv4
            return addr.address

def get_ipv4_address(interface_name=None):
    if_addrs = psutil.net_if_addrs()
    if isinstance(interface_name, str) and interface_name in if_addrs:
        addrs = if_addrs.get(interface_name)
        address = find_single_ipv4_address(addrs)
        return address if isinstance(address, str) else ""
    else:
        if_stats = psutil.net_if_stats()
        if_stats_filtered = {key: if_stats[key] for key, stat in if_stats.items() if "loopback" not in stat.flags}
        if_names_sorted = [stat[0] for stat in sorted(if_stats_filtered.items(), key=lambda x: (x[1].isup, x[1].duplex), reverse=True)]
        if_addrs_sorted = OrderedDict((key, if_addrs[key]) for key in if_names_sorted if key in if_addrs)
        for _, addrs in if_addrs_sorted.items():
            address = find_single_ipv4_address(addrs)
            if isinstance(address, str):
                return address
        return ""

def status(filename):
    try:
        with canvas(lcd) as draw:
            f = filename.replace(".wav", "")
            f = f.replace(basedir + "/", "")
            f = f.replace("/", "\n")
            f = f.replace("_", " ")

            f += "\n\n"
            f += "Bat: {:.0f}% {:.2f}V {:.2f}A".format(bat.get_battery_level(), bat.get_battery_voltage(), bat.get_battery_current())

            ip = get_ipv4_address()
            if len(ip) > 0:
                f += "\n"
                f += "IP: %s" % (ip)

            with open("/proc/asound/card0/pcm0p/sub0/hw_params", "r") as rf:
                for line in rf:
                    if line.startswith("rate:"):
                        rate = int(line.split(" ")[1])

                        f += "\n"
                        f += "Rate: {:.0f}kHz".format(rate / 1000)

            draw.multiline_text((0, 0), f, font=font, fill="white", spacing=-1)
    except Exception as e:
        pass

def stop():
    global currentplaying

    if running():
        try:
            print("Stopping running player")
            os.kill(currentplaying.pid, signal.SIGINT)
            if not currentplaying.poll():
                currentplaying = None
            else:
                print("Error stopping player")
        except ProcessLookupError as e:
            currentplaying = None
    else:
        currentplaying = None

def play(filename):
    global currentplaying
    global lcd
    global basedir
    global bat
    global currentfile

    stop()

    print('Now playing "' + filename + '"')
    currentfile = filename
    status(currentfile)

    print("volume %s " %  currvol)
    currentplaying = subprocess.Popen(["ffplay", "-hide_banner", "-nostats", "-nodisp", "-autoexit", "-volume", currvol, filename])

def running():
    global currentplaying

    if currentplaying != None:
        if currentplaying.poll() == None:
            return True
    return False

def playlist():
    global songlist
    global lasttime

    if not running():
        while True:
            if (songlist == None) or (len(songlist) <= 0):
                switch_artist()
                songlist = originalsongs.copy()
                random.shuffle(songlist)

            song = songlist.pop()
            artist = get_artist(song)
            if artist == currentartist:
                play(song)
                lasttime = time.time()
                break
    else:
        if (time.time() - lasttime) >= LCD_REFRESH:
            status(currentfile)
            lasttime = time.time()

def switch_artist():
    global artists
    global currentartist

    if len(artists) <= 0:
        artists = originalartists.copy()
        random.shuffle(artists)

    currentartist = artists.pop()

    switch_track()

def switch_track():
    stop()

def button(ch):
    val = not GPIO.input(ch)

    #name = "Unknown"
    #if ch == BTN_ARTIST:
    #    name = "BTN_ARTIST"
    #elif ch == BTN_NEXT:
    #    name = "BTN_NEXT"
    #print(name + " is now " + str(val))

    if val:
        if ch == BTN_ARTIST:
            switch_artist()
        elif ch == BTN_NEXT:
            switch_track()

def main():
    global lcd
    global font
    global bat
    global currentfile

    if len(sys.argv) <= 1:
        print("Usage:")
        print("\t" + sys.argv[0] + " PATH")
        sys.exit(1)

    os.system("killall ffplay")

    GPIO.setmode(GPIO.BCM)
    for b in [ BTN_ARTIST, BTN_NEXT ]:
        GPIO.setup(b, GPIO.IN, pull_up_down=GPIO.PUD_UP)
        GPIO.add_event_detect(b, GPIO.BOTH, callback=button, bouncetime=debouncems)

    try:
        bus = i2c(port=1, address=0x3C)
        lcd = ssd1306(bus)
        font = ImageFont.truetype(fontfile, fontsize)
    except DeviceNotFoundError as E:
        print("No LCD connected")
        lcd = None

    conn, event_conn = pisugar.connect_tcp()
    bat = pisugar.PiSugarServer(conn, event_conn)
    print(bat.get_model() + " " + bat.get_version())
    print(str(bat.get_battery_level()) + "% " + str(bat.get_battery_voltage()) + "V " + str(bat.get_battery_current()) + "A")
    print("Plug=" + str(bat.get_battery_power_plugged()) + " Charge=" + str(bat.get_battery_charging()))

    try:
        while True:
            playlist()
            time.sleep(0.05)
    except KeyboardInterrupt:
        print("Bye")
        GPIO.cleanup()
        sys.exit(0)

if __name__ == "__main__":
    main()

And you'll also need /etc/systemd/system/osci.service to start the script automatically. Adjust the username and path accordingly.

[Unit]
Description=Oscilloscope Music Player
After=multi-user.target

[Service]
Type=idle
User=thomas
ExecStart=/home/thomas/osci-music-player/osci-pi.py /home/thomas/music
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

The ExecStart line has the parameters that are passed to the Python script. This is the path of the directory that contains all the .wav files for the songs. In this top-level folder, I called it ~/music, put another level of directories named after the artist, then place the files in there.

Finally enable and start the new unit.

sudo systemctl daemon-reload
sudo systemctl enable --now osci.service

The device should now start playing the music as soon as the power is turned on. Before switching the device off, use the on-board button of the PiSugar to properly shutdown the OS, and only then move the power switch to the Off position.

You can also check out the code in its Git repository.

RGB LED Matrix visualizer

Tue, 05 Sep 2023 12:00:00 -0000

I initially bought a 32x32 RGB LED matrix in 2018. Back then the idea was to fit it onto a bag, as some kind of wearable device, for 35C3. But it never really worked out. So in preparation for CCCamp23 I noticed the LED panel again and decided to order some more of them.

These are the 32x32 4mm pitch RGB LED Matrix Panels from Pimoroni, with either the Interstate 75 W or the Adafruit RGB Matrix Bonnet to run them with a RP2040 or a Raspberry Pi, respectively.

Everything runs from a single Python codebase, either simulated in a GUI window on a development PC, on the Raspbian Python interpreter or directly on the Pico MicroPython environment.

For portability I'm simply using a voltage regulator to connect a 4S LiPo battery. I made one of them from recycled single-use vape batteries, but I also used some of my RC-model batteries.

On the software side I wrote some code to show static images, GIF animations, scroll text across the matrix, etc. I also implemented Snake, Tetris and Breakout, as well as some other utilities, like OTA updating for the Pico, a Telegram bot integration, a weather widget and a service checking if a device is reachable on the network.

Right now the 64x64 panel is placed next to the TV in my livingroom, randomly cycling through some animations and games.

I wasn't really able to get breakout into a playable state before CCCamp23. But luckily I also got a patch set (1, 2, 3, 4) from Jannis that fixed the collision behaviour of the ball in breakout! We met on the camp and had a very nice time together. And soon afterwards the patches appeared in my inbox and actually made the game playable! This was really awesome 😊💪 Thanks again!

Here are my notes for installing everything on a Raspbian OS.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install python3-pip git vim htop
git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts
cd Raspberry-Pi-Installer-Scripts
sudo ./rgb-matrix.sh
# Answer y, Bonnet, Quality (and solder the mentioned link on the board)
cd ..

git clone https://codeberg.org/xythobuz/rgb-matrix-visualizer
sudo pip3 install Pillow bdfparser "qrcode[pil]" evdev

cd Raspberry-Pi-Installer-Scripts/rpi-rgb-led-matrix/bindings/python
pip3 wheel --no-deps -w dist .
sudo pip3 install dist/rgbmatrix-0.0.1-cp39-cp39-linux_armv7l.whl

sudo apt-get install libopenjp2-7

# append isolcpus=3 to /boot/cmdline.txt
cat &lt;&lt;EOF | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
blacklist snd_bcm2835
EOF

sudo update-initramfs -u
sudo reboot

# test python bindings work
cd rgb-matrix-visualizer
sudo ./pi.py

sudo sh -c 'echo enable_uart=1 &gt;&gt; /boot/config.txt'

Although I'm currently still having some problems getting the wetterdienst dependency running on the Raspberry Pi.

I also want to give a shout-out to Pimoroni. I managed to rip-off the power connector on one of the panels. They sent a replacement without any additional cost, but I took the chance and ordered some more spare panels.

The modules bought this year have pretty consistent color reproduction. But compared to the one module I bought five years earlier, there is a very noticable difference. On these pictures both modules show the same RGB values.

I added some simple compensation to mostly adjust for this issue.

# For some reason the red and green LEDs on older Pimoroni panels
# are far brighter than on newer panels.
# Adjust this by multiplying rg channels with 0.75 and b channel
# with 0.85, depending on hard-corded coordinate ranges.
class MapperColorAdjust(MapperNull):
    def set_pixel(self, x, y, color):
        # second panel from the left, with 32 <= x,
        # is "old" type with brighter LEDs.
        # rest of panels to the left are less bright.
        # so adjust brightness of other panel channels down.
        if x >= self.gui.panelW:
            color = (int(color[0] * 0.75), int(color[1] * 0.75), color[2] * 0.85)

        self.gui.set_pixel(x, y, color)

I also planned to build a large LED matrix based on WS2812 LED strips. They can be driven easily with a Raspberry Pi.

I was even able to get a basic frame finished before CCCamp23. But that's where time ran out.

I haven't yet given up that plan completely, but I have to think of a solution for diffusing the light first. The LEDs are too small and spaced too far apart to look good in this configuration.

More Pictures

Some more photographs I didn't use above.

xythobuz.de Blog

Glove80 USB Dongle

Quick Start

Software Implementation

Hardware

Logging Battery Levels

Logitech MX Ergo switch replacement

Dry Filament Storage

E-Scooter Battery Build

Background

Build

Tools Used

Bill of Materials

Fuse Update

Oscilloscope Video Display

More Videos

CYD MQTT Touchscreen UI

Smart Meter Bridge

Duality

Introduction

Quick Start Guide

Links

Toolchain

Software

Graphics

Sound

Banking

Game Boy Printer

Physical Cartridges

Asset Recreation

Summary

License

AutoBrightness

Prototype Hardware

Proper Hardware

USB Communication

Prototype Client

Proper Client

Update after a year (2025-07)

License

Game Boy Color modding and experiments

Pico BLE Vape Remote

iStick Pico 25 OLED Replacement

LARS v2

Assembly Guide

xyBeast

Parts List

xyLX5

Parts List

Auto-generated project docs with 3D preview

Example Implementation

1) mdBook dependency

2) mdBook initialization

3) svg-pan-zoom dependency

4) Generating docs

5) Auto-generating and publishing docs

6) STL 3D visualization

7) PCB gerber files

8) PCB visualization

LARS - Looping Automated Rhythm Station

More Pictures

Toolbox Markdorf anniversary

More Pictures

Oscilloscope Music Player

Table Of Contents

Introduction

Artists

Playback

Oscilloscope Settings

Hardware

Software

RGB LED Matrix visualizer

More Pictures