How joshua12-5/macropad works
RP2040 Macropad combines a desktop configurator with USB HID firmware for a programmable 12-key pad. The user edits profiles, macros, or idle animations in the configurator, then connects to the device to upload or manage configuration; the firmware stores it and runs the pad as a keyboard, with an OLED menu and optional app-driven profile switching. The graph includes the documented editing, backup, animation, and auto-switch capabilities. Some feature modules were not sampled, so their internal call relationships are omitted; README-supported links are identified as such.
Main entry points: main.c Firmware loop · device.py Device API · widgets Task editors · frames.py Protocol frames
Components 29
Desktop configurator
- App entry
configurator/macropad_config/app.py - Configurator window
configurator/macropad_config/main_window.py - Task editors
configurator/macropad_config/widgets - Pad preview
configurator/macropad_config/widgets/pad_preview.py - Auto-switch
configurator/macropad_config/autoswitch - Device backup
configurator/macropad_config/device_backup.py
Configuration data
- Profile model
configurator/macropad_config/models/profile.py - Macro model
configurator/macropad_config/models/macro.py - Data schema
configurator/macropad_config/models/schema.py - Animation tools
configurator/macropad_config/animation - Profile encoding
configurator/macropad_config/protocol/profile_blob.py - Macro encoding
configurator/macropad_config/protocol/macro_blob.py - Animation encoding
configurator/macropad_config/animation/codec.py - Protocol frames
configurator/macropad_config/protocol/frames.py - Device API
configurator/macropad_config/protocol/device.py
Firmware runtime
- Firmware loop
firmware/src/main.c - Config protocol
firmware/src/config_protocol.c - Flash storage
firmware/src/storage.c - Profile runtime
firmware/src/profiles.c - Macro engine
firmware/src/macros.c - Action engine
firmware/src/actions.c - USB keyboard
firmware/src/usb_hid_app.c - Keys and encoder
firmware/src/matrix.c
On-device features
- OLED menu
firmware/src/device_menu.c - OLED display
firmware/src/oled_ui.c - Idle animation
firmware/src/anim.c
Other components
- User
- USB HID device
- Device flash
Connections 37
- User → App entry: starts
README.md - App entry → Configurator window: opens GUI
README.md - User → Task editors: edits configuration
README.md - Configurator window → Task editors: presents tasks
README.md - Configurator window → Pad preview: shows layout
configurator/macropad_config/main_window.py - Task editors → Profile model: edits profiles
configurator/macropad_config/widgets/pad_preview.py - Task editors → Macro model: edits macros
configurator/macropad_config/widgets/pad_preview.py - Task editors → Animation tools: edits animations
configurator/macropad_config/widgets/pad_preview.py - Auto-switch → Device API: sets active profile
configurator/macropad_config/autoswitch/service.py - Auto-switch → USB HID device: switches profile
README.md - Device backup → Device API: backs up device
- Profile model → Data schema: validates against
configurator/macropad_config/models/profile.py - Macro model → Data schema: validates against
configurator/macropad_config/models/macro.py - Profile encoding → Protocol frames: uses framing
configurator/macropad_config/protocol/profile_blob.py - Macro encoding → Protocol frames: uses framing
configurator/macropad_config/protocol/macro_blob.py - Animation encoding → Protocol frames: uses frame format
configurator/macropad_config/animation/codec.py - Device API → Protocol frames: exchanges frames
configurator/macropad_config/protocol/device.py - Device API → Profile encoding: transfers profiles
configurator/macropad_config/protocol/device.py - Device API → Macro encoding: transfers macros
configurator/macropad_config/protocol/device.py - Device API → Animation encoding: transfers animations
configurator/macropad_config/protocol/device.py - Device API → USB HID device: communicates over HID
configurator/macropad_config/protocol/device.py - USB HID device → Config protocol: sends configuration
README.md - Firmware loop → Config protocol: runs protocol
firmware/src/main.c - Firmware loop → Keys and encoder: polls inputs
firmware/src/main.c - Firmware loop → Action engine: runs actions
firmware/src/main.c - Firmware loop → Macro engine: runs macros
firmware/src/main.c - Firmware loop → OLED menu: runs menu
firmware/src/main.c - Firmware loop → OLED display: updates display
firmware/src/main.c - Firmware loop → Idle animation: runs animation
firmware/src/main.c - Firmware loop → Flash storage: persists state
firmware/src/main.c - Keys and encoder → Action engine: triggers actions
- Action engine → USB keyboard: emits key actions
- Config protocol → Flash storage: reads and writes
- Flash storage → Device flash: persists configuration
firmware/src/storage.c - OLED menu → Profile runtime: switches profiles
- Idle animation → Device flash: stores animation frames
- Firmware loop → USB keyboard: updates HID reports
firmware/src/main.c