Docs · Firmware
Firmware reference.
The program on the ESP32 draws the keys, reads the touch screen, stores the pictures and talks to the app over USB. Prebuilt images on this site were built on 2026-10-16.
Building it yourself
Download the firmware source (and, for an offline setup, the libraries).
- Board packageesp32 by Espressif, version 3.x (2.x does not compile)
- BoardESP32-WROOM-DA Module (
esp32:esp32:esp32da) - Partition schemeNo OTA (2MB APP/2MB SPIFFS),
PartitionScheme=no_ota - LibrariesTFT_eSPI, AnimatedGIF
- TFT_eSPI setupyour display driver and the pins; leave
TFT_BACKLIGHT_ONundefined; the firmware dims the backlight itself - 320 × 240 panelsset
BTN_W/BTN_H52,BTN_R10,GAP6,OFFSET_X18,OFFSET_Y36 - IPS panelsadd
tft.invertDisplay(true);right aftertft.init();
Flash layout
The firmware uses the No OTA layout: about 2 MB for the program and 1.9 MB for key pictures and the touch calibration (LittleFS). The app, the web flasher and the Arduino settings above all use the same layout, so updating the firmware keeps your pictures.
Firmware from before October 2026 used a different layout. The first update from it clears the pictures and the calibration once: calibrate on the deck, and the app sends the pictures again.
When the storage runs full, the deck first removes pictures that no key shows any more.
Touch calibration
On its first start the deck asks for calibration: tap the highlighted keys: the four corners, then the middle one. It says Touch ready when the result is stored. Run it again any time from the app (Settings → General → Calibrate) or with the CALIB command.
Console commands
Type these in the app's Serial console. The deck answers on the same line feed.
| Command | What it does |
|---|---|
| PING | Is the deck answering? Replies PONG_WDECK_DIY. |
| CAPS | Firmware abilities: protocol version, chip, model, free memory and storage. |
| HW_INFO | Which display controller the firmware found and the pins it was built with. |
| TEST | Screen test: colour fields and touch, with an exit button. |
| CALIB | Starts the touch calibration on the deck. |
| TOUCHDBG:1 | Reports the raw position of every touch (TOUCHDBG:0 stops it). |
| BRIGHT:0–255 | Sets the backlight. |
| RESET | Restarts the deck. |
How the app talks to it
- Text commands over USB serial, starting at 250 000 baud; on USB-UART boards the app and deck agree on a faster speed and verify it.
- On connect the app asks for
CAPSand gets the chip ID, so each deck keeps its own layout. - Pictures are sent as binary blocks with a CRC check and written only when complete; the app sends only the keys that changed.
- The deck reports
TOUCH,HOLDandRELfor each key; the app runs the action on release, or the long-press action on hold.
The source of the app and the firmware is MIT licensed, see Downloads.