Skip to content

Firmware Development

This section covers the internals of the Cyber Fidget firmware — how to build it, how it's structured, and the design decisions behind the major subsystems.

What is this?

The Cyber Fidget runs custom firmware on an ESP32 microcontroller. The firmware handles everything: buttons, display, LEDs, sound, Bluetooth, SD card, and the app framework that ties it all together. If you've read the Concepts section, you know how apps work from the outside. This section shows how things work on the inside.

Firmware

The firmware ships as a single unified build on main — all apps (games, screensavers, tools, music player, web portal) are included. The BT A2DP audio stack initially caused an IRAM overflow, but this was solved by patching the linker script to move unused libc functions out of IRAM. No apps needed to be removed.

Build system

The firmware uses PlatformIO with the pioarduino platform (ESP-IDF 5.1.4 + Arduino ESP32 3.0.3).

platform = https://github.com/pioarduino/platform-espressif32/releases/...
board = adafruit_feather_esp32_v2
framework = arduino

Key build flags for the BT audio stack:

  • -DAUDIOTOOLS_NO_ANALOG / NO_PWM / NO_ADC / NO_DAC — Strip unused audio backends
  • -DCONFIG_ESP32_WIFI_IRAM_OPT=0 — Move WiFi fast-path code out of IRAM
  • -DA2DP_SPP_SUPPORT=1 — Enable SPP alongside A2DP on IDF 5.x
  • build_type = release — Debug builds add ~4KB of IRAM overhead

Architecture overview

┌─────────────────────────────────────────────┐
│              AppManager (singleton)          │
│  Owns lifecycle: begin() → update() → end() │
├──────────┬──────────┬───────────────────────┤
│ MenuMgr  │ PowerMgr │ MusicPlayerApp  ...   │
├──────────┴──────────┴───────────────────────┤
│                    HAL                       │
│  Display · Buttons · Slider · LEDs · Audio  │
├─────────────────────────────────────────────┤
│          ESP-IDF / Arduino / FreeRTOS       │
├─────────────────────────────────────────────┤
│                 ESP32 Hardware               │
│  OLED · Buttons · NeoPixels · I2S · BT · SD│
└─────────────────────────────────────────────┘
  • AppManager schedules one active app at a time. Every 20ms, it calls the active app's update().
  • HAL wraps all hardware access behind a consistent API.
  • Apps are self-contained classes registered via APP_ENTRY macros in AppManifest.h.

See How an App Works for the app-level view.

In this section