Set it up

What you need, how to build, flash and pair the boards, and how the firmware is put together.

Set-up

What you need

Build and flash

git clone https://github.com/nicenemo/nachtgespenst.git
cd nachtgespenst
.pio/venv/bin/pio run -e core2     # about 12 minutes; PlatformIO lives inside the project
jbang tools/Flash.java core2       # writes the image and waits until the board is back
.pio/venv/bin/pio run -e cores3
jbang tools/Flash.java cores3      # does the 1200-baud touch into the ROM bootloader itself

Pair the board from the host's Bluetooth settings; it advertises as ๐ŸŒ™๐Ÿ‘ป-c2 or ๐ŸŒ™๐Ÿ‘ป-cs3. Over USB the CoreS3 simply appears as a keyboard.

Change the keymap

Layers live in include/Keymap.h as an array of GridLayer (title, bindings, rows, columns, LED colour). Edit, rebuild, flash.

Test it

jbang tools/SerialTest.java --board S3    # 29 checks, including USB and BLE routing
jbang tools/SerialTest.java --board C2    # 11 checks
jbang tools/SerialTest.java --shot shots  # screenshots of every page
jbang tools/LedCam.java colours --port /dev/ttyUSB0 --out cam --crop x0,y0,x1,y1

Regenerate the HID vocabulary

cd tools
jbang FetchHut.jsh          # only when updating to a newer USB HID Usage Tables PDF
jbang GenerateHeaders.jsh
cp -r include/. ../include/

Full instructions, the sandbox set-up used for Claude Code and the decision records are in the docs folder.

How it works