Set-up
What you need
- An M5Stack Core2 and/or CoreS3, ideally with the M5GO base for the LED bar.
- PlatformIO (the project keeps its own copy under
.pio/; seedocs/wiki/tooling.md). - JBang for the Java tools (header generator, serial tests, camera tool); it downloads the right JDK itself.
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
- Generated HID vocabulary.
tools/GenerateHeaders.jshreads the USB HID Usage Tables (as JSON extracted from the official PDF) and renders FreeMarker templates into usage constants and shortcut macros such askp_Aandcp_MUTE. Nothing ininclude/hid_*is edited by hand. - Binding model. A
Bindingis a HID page, a usage, a modifier mask and a label. Chord helpers (lcs,lmeh,lhyp) wrap macros the way ZMK does. - Keymap and UI.
Keymap.hholds the layers;src/ui.cppdraws the current layer, handles touch, mirrors the host LEDs on the bar and dims the backlight after a minute of idleness. - HID transports.
HIDManagerowns BLE (NimBLE) and, on the CoreS3, USB (TinyUSB). Reports go through a non-blocking press queue with release retry;PREFERandONLYcommands choose which transport receives them. - Serial protocol.
PING,INFO,STATE?,LAYER,TAP,KEY,SHOT,PREFER,ONLY: enough for automated tests and for the screenshots above.