Skip to content
TypixNode Wiki

Flashing Firmware

TypixDeck has three pieces of firmware you may want to flash:

Firmware Chip File
Linux Raspberry Pi CM4 / CM5 (eMMC version) Raspberry Pi OS image
Co-processor ESP32-S3 typixdeck_esp32s3_full_YYYYMMDD.bin (single full image)
Keyboard STM32F042 (QMK) keebdeck_6r11c_default_YYYYMMDD.bin

Recommended workflow: install Linux first, then flash the ESP32 and the keyboard from the device’s own Linux command line. No PC, no switch flipping and no side debug port needed for those two.

0. Buttons and switches

Section titled “0. Buttons and switches”

Numbers refer to the orange / grey markers on the board layout.

Name Looks like Function
Power switch (orange 1) Slide switch, top-right, ON / OFF Main power, including the 3.3 V rail for the ESP32 and keyboard MCU
ESP32 BOOT (orange 2) Small rectangular side-mounted key on the top edge Hold while resetting = ESP32 download mode; a short press in normal use toggles the display between Pi and ESP32
ESP32 RESET (orange 3) Round key, silkscreen S3_EN Resets the ESP32
Pi BOOT (orange 4) Round key, silkscreen Boot, next to S3_EN Hold at power-on = compute module eMMC exposed over USB
USB mode switch (grey 3) Slide switch, top-left, Host / Device Leave at Host. Only set to Device while flashing eMMC

1. Linux on the compute module (CM4 / CM5 with eMMC)

Section titled “1. Linux on the compute module (CM4 / CM5 with eMMC)”

Lite modules (no eMMC) skip this section: write the image to a microSD card with Raspberry Pi Imager on any computer and insert it.

eMMC modules are flashed through rpiboot, which exposes the eMMC as a USB drive:

  1. Power switch OFF.

  2. USB mode switch to Device.

  3. Connect the bottom USB-C power port (blue 3) to your computer.

  4. Hold the Pi BOOT key, slide the power switch ON, keep holding for 3 seconds, then release.

  5. Run rpiboot on the computer; the module appears as a USB drive:

    Terminal window
    # macOS / Linux, built from raspberrypi/usbboot (do not use the Homebrew build on macOS)
    sudo ./rpiboot -d mass-storage-gadget64

    The command is the same for CM4 and CM5.

  6. Write the OS image to that drive with Raspberry Pi Imager (or dd). Eject and unplug.

  7. USB mode switch back to Host, power OFF → ON.

Notes: remove the microSD card while flashing a CM5 eMMC; on macOS rpiboot must run in the foreground.

2. ESP32-S3 co-processor (from the device’s Linux)

Section titled “2. ESP32-S3 co-processor (from the device’s Linux)”

The firmware is one full image written at offset 0.

2.1 Enter download mode (pick one)

Section titled “2.1 Enter download mode (pick one)”

  • Firmware running normally — send the magic string, the ESP32 reboots into download mode by itself:

    Terminal window
    echo "EGGFLY_REBOOT_TO_BOOT_MODE" | sudo tee /dev/ttyACM0

  • Buttons — hold ESP32 BOOT (orange 2), tap S3_EN (orange 3), release S3_EN first, then BOOT.

  • Cold start — power OFF, hold ESP32 BOOT, slide power ON, keep holding for 2 seconds. The ESP32 waits in download mode until Linux is up.

Check:

Terminal window
lsusb | grep 303a

303a:1001 or 303a:0009 means download mode.

2.2 Flash

Section titled “2.2 Flash”
Terminal window
sudo apt install esptool
esptool --no-stub --chip esp32s3 -p /dev/ttyACM0 -b 460800 \
  write_flash 0x0 typixdeck_esp32s3_full_YYYYMMDD.bin

The esptool shipped by Raspberry Pi OS is old; --no-stub is required.

2.3 Reset

Section titled “2.3 Reset”
  • Entered via magic string: reboots automatically.
  • Entered via buttons / cold start: tap S3_EN.

lsusb now shows 303a:80c3 and the boot animation appears on the display.

3. STM32 keyboard (from the device’s Linux)

Section titled “3. STM32 keyboard (from the device’s Linux)”

3.1 Enter DFU (pick one)

Section titled “3.1 Enter DFU (pick one)”
  • Keyboard working — press Fn + ◇ (diamond key) or Sym + ◇.
  • Blank chip — enters DFU automatically at power-on.
  • Bricked, no key response — power OFF, short the inner pad of the empty R58 footprint (bottom-left of the keyboard side) to 3.3 V with tweezers, slide power ON, hold for 1 second, remove (BOOT0 high → ROM DFU).

Check:

Terminal window
lsusb | grep 0483:df11

3.2 Flash

Section titled “3.2 Flash”
Terminal window
sudo apt install dfu-util
sudo dfu-util -a 0 -d 0483:df11 -s 0x08000000:leave -D keebdeck_6r11c_default_YYYYMMDD.bin

:leave jumps straight into the new firmware; no power cycle needed. lsusb shows c182:6b11 KeebDeck 6R11C.

4. Troubleshooting

Section titled “4. Troubleshooting”
Symptom Fix
No 303a device in lsusb A boot-looping ESP32 fails enumeration until the hub gives up; use the cold-start method
esptool complains about a missing stub Add --no-stub
Display blank after flashing the ESP32 Tap S3_EN, confirm lsusb shows 303a:80c3
Keyboard special keys stopped working You flashed the diag build; flash default again
rpiboot never sees the module USB mode switch at Device, cable in the bottom USB-C port, Pi BOOT held before power-on
Keep ESP32 settings (language, theme) The full image wipes settings; flash only the app: write_flash 0x10000 app.bin

5. Downloads

Section titled “5. Downloads”