Firmware Architecture
Purpose
Define the embedded firmware structure for a retro-inspired connected radio with streaming audio, Bluetooth audio, a small center display, two front-panel knobs, rechargeable battery operation, and graceful behavior across plugged-in and unplugged modes.
Product Context
The product is a wood-look tabletop radio concept with a modern digital core. Firmware should support a calm appliance-like experience rather than a generic development-board style user experience.
Primary Firmware Responsibilities
- Manage boot, configuration, and normal operation states
- Provide WiFi onboarding and reconnection behavior
- Support streaming-ready audio playback architecture
- Support Bluetooth audio sink behavior
- Control display rendering and UI state transitions
- Read and interpret the two front knobs and any press actions
- Monitor battery, charging, and external power presence
- Enforce low-battery and power-saving policies
- Coordinate audio focus, source switching, and volume behavior
- Log faults and expose service/debug status where appropriate
Recommended Top-Level Architecture
Use an event-driven firmware architecture with clearly separated services and a central state manager.
Core Layers
-
Hardware abstraction layer
- GPIO
- ADC inputs
- I2C/SPI/UART buses
- audio interface
- battery and charger status lines
- display interface
- rotary encoder or potentiometer input handling
-
Platform services
- nonvolatile settings storage
- timekeeping and timers
- connectivity management
- watchdog and fault recovery
- power management
- diagnostics/logging
-
Product services
- source manager
- audio pipeline manager
- Bluetooth manager
- streaming manager
- UI manager
- display compositor
- control input manager
- battery state manager
-
Application state machine
- boot
- first-time setup
- idle
- playback
- paused
- settings
- network recovery
- low battery
- charging
- shutdown
Firmware Modules
Boot and System Manager
Responsibilities:
- Initialize clocks, buses, interrupts, and persistent settings
- Validate stored configuration
- Bring up the display quickly with a branded or status splash
- Determine whether the unit should enter normal operation, setup flow, low-battery warning, or protected shutdown
- Start background services in a staged sequence to reduce boot-time glitches
Design notes:
- Prioritize fast display feedback so the radio feels responsive
- Defer noncritical services until after basic UX is visible
- Handle unexpected reset reasons and record them for diagnostics
Connectivity Manager
Responsibilities:
- Manage WiFi onboarding, credential storage, reconnection, and signal-quality awareness
- Expose connectivity status to the UI layer
- Coordinate network-dependent services with power and source management
Expected behaviors:
- If credentials exist, attempt reconnect in the background
- If no credentials exist, enter onboarding mode with clear display prompts
- If network connection drops during streaming, show recovery state and retry gracefully
- Avoid repeated disruptive UI changes for short network interruptions
Streaming Manager
Responsibilities:
- Abstract internet audio and network playback services behind a source-agnostic interface
- Start, stop, pause, resume, and recover streams
- Provide metadata to the display layer, such as station, track, artist, bitrate, and source icon where available
Design intent:
- The product should be streaming ready, so firmware should treat streaming as a first-class source rather than an optional add-on
- Source handling should be extensible so additional services can be added later without rewriting the full UI stack
Suggested subfunctions:
- stream session controller
- metadata parser
- buffering manager
- reconnect policy manager
- playback state notifier
Bluetooth Manager
Responsibilities:
- Support Bluetooth audio receiving mode
- Manage pairing, bonded device memory, reconnection, and local device naming
- Provide link state and codec/session information to the UI layer if available
Expected UX behavior:
- Make Bluetooth entry and pairing discoverable from the front-panel UI
- Show paired, connecting, connected, and disconnected states clearly
- Preserve a simple path back to the previous source
Inter-module interactions:
- Coordinate with source manager to arbitrate active source
- Coordinate with audio pipeline manager for start/stop and volume behavior
- Coordinate with UI manager for pairing and device status prompts
Source Manager
Responsibilities:
- Maintain the current active source and the available source list
- Coordinate source switching between streaming, Bluetooth, and any future local or auxiliary sources
- Apply policy for resume behavior when power returns or after temporary interruptions
Policy examples:
- Resume last source when appropriate
- If a Bluetooth device reconnects, follow configured priority rules rather than always stealing focus
- Prevent accidental simultaneous ownership of the audio path
Audio Pipeline Manager
Responsibilities:
- Control the digital audio path from source decoding or Bluetooth ingress through DSP and output stages
- Apply volume, mute, fade, and source transition rules
- Manage sample-rate changes and minimize clicks or pops during transitions
Potential feature blocks:
- master volume control
- balance or tone presets if later desired
- startup and shutdown mute sequencing
- underrun handling during network streaming
UI Manager
Responsibilities:
- Own the user-visible product state model
- Translate physical control actions into intents
- Map system/service states into a small-screen, low-complexity interface
- Enforce consistent navigation, timeout, and return-to-now-playing behavior
UI principles:
- Appliance-like
- Low cognitive load
- Legible from a distance
- Minimal menu depth
- Fast access to playback and source switching
Display Compositor
Responsibilities:
- Render the small center display consistently
- Handle typography, iconography, layout states, update throttling, and transitions
- Present critical information first within limited screen area
Suggested display views:
- boot/status splash
- now playing
- source selection
- volume overlay
- WiFi onboarding prompt
- Bluetooth pairing screen
- battery/charging screen
- settings menus
- low battery warning
- error/recovery states
Rendering guidance:
- Avoid high-frequency unnecessary redraws
- Support temporary overlays without losing core context
- Ensure battery and connectivity indicators remain understandable at a glance
Control Input Manager
Responsibilities:
- Read two front knobs and any integrated push actions
- Debounce inputs and normalize behavior into high-level events
- Detect rotation direction, speed, click, long press, and inactivity
Suggested control model:
- Left knob: source or menu navigation, optional press for back/menu
- Right knob: volume, optional press for play/pause or select
Design requirement:
- Input semantics should remain stable across screens so the product feels intuitive
- Fast rotation should accelerate long-list navigation where appropriate
- Volume changes should always feel immediate and never get trapped behind menu layers
Battery State Manager
Responsibilities:
- Monitor battery voltage, charge state, external power presence, and low-battery thresholds supplied by the hardware design
- Estimate battery condition for user display and power policy decisions
- Coordinate charging, plugged-in mode, battery-only mode, and safe shutdown behavior
Required states:
- external power present and charging
- external power present and battery full
- battery operation normal
- battery operation low
- battery operation critical
- fault or invalid battery telemetry
Expected system actions:
- Show charging/full indicators
- Warn user before low-battery shutdown
- Reduce display intensity or background activity in low-power mode if supported
- Block battery-damaging or user-confusing behaviors near cutoff
Settings and Persistence Manager
Responsibilities:
- Store user preferences and recover them on boot
- Persist volume, source preferences, brightness, paired devices, WiFi credentials, and selected UI options
- Protect against corrupted settings and support factory reset behavior
Suggested System State Machine
1. Boot
Entry conditions:
- power applied from charger or battery
Actions:
- initialize hardware
- validate configuration
- show startup status
- determine battery and power condition
- bring up services in sequence
Exit paths:
- first-time setup
- idle
- playback restore
- low-battery protection
2. First-Time Setup
Purpose:
- establish initial connectivity and baseline preferences
Possible UX:
- language or region if needed
- WiFi onboarding path
- Bluetooth device name visibility
- initial source selection
3. Idle
Purpose:
- system awake, no active playback
Behavior:
- display clock, source-ready state, or branded idle screen
- allow quick entry to source selection and setup
- maintain network and pairing readiness within power budget
4. Playback
Purpose:
- active audio output from streaming or Bluetooth
Behavior:
- now-playing view prioritized
- overlays for volume and source changes
- metadata updates without disruptive screen flicker
5. Settings
Purpose:
- non-time-critical adjustments
Suggested settings groups:
- WiFi
- Bluetooth
- display
- power
- source behavior
- about/status
- reset options
6. Network Recovery
Purpose:
- handle interrupted or degraded network while preserving confidence
Behavior:
- show concise recovery messaging
- retry in the background
- offer fallback to another source if helpful
7. Low Battery
Purpose:
- alert the user and prepare for reduced runtime
Behavior:
- clear warning
- optional dimming or reduced updates
- preserve user data and settings
8. Charging
Purpose:
- represent plugged-in behavior clearly
Behavior:
- indicate charging progress/state
- permit normal playback unless thermal or power policy limits require otherwise
9. Shutdown / Deep Sleep
Purpose:
- protect battery and system state
Behavior:
- mute audio cleanly
- save volatile session state if needed
- blank or simplify display
- enter low-power state or full off depending on hardware capability
Source and Audio UX Rules
- Volume must always be low-latency and feel directly tied to knob movement
- Source switching should be explicit and visible
- Source changes should mute or fade cleanly to avoid pops
- Resume behavior should feel intentional, not surprising
- Metadata should enhance the experience but not block core transport controls
- If metadata is unavailable, the UI should fall back gracefully to source name and connection state
Display and Control Behavior
Home / Now Playing
Show:
- source
- title/station or device name
- playback state
- connectivity indicator
- battery or charging status
- volume overlay when active
Left Knob
Recommended default behavior:
- rotate to browse source or menu items
- press to enter source menu or go back
Right Knob
Recommended default behavior:
- rotate for volume
- press for select or play/pause depending on current context
Timeouts
- Temporary overlays should clear automatically
- Menus should return to now playing or idle after inactivity
- Critical warnings should persist long enough to be noticed
Battery and Power Policy Requirements
- System must detect external power insertion and removal cleanly
- Playback behavior on power-source transition should not confuse the user
- Low-battery thresholds should trigger user-visible warnings before forced shutdown
- Critical battery thresholds should cause orderly mute, state save, and shutdown
- Charging indications should remain understandable even when the unit is otherwise idle
Reliability and Recovery Requirements
- Watchdog coverage for major execution loops or tasks
- Recovery from transient network failures without full system reboot when possible
- Safe handling of corrupted settings
- Brownout-aware behavior if supported by the hardware platform
- Clear user-facing error states for pairing failure, WiFi failure, and battery fault conditions
Suggested Tasking Model
If an RTOS-capable platform is used, separate tasks may include:
- system supervisor
- input handling
- display rendering
- connectivity management
- streaming/audio control
- Bluetooth management
- battery monitoring
- diagnostics/logging
If a non-RTOS model is used, preserve strict module boundaries and event queues to avoid UI and audio starvation.
Data That Firmware Should Persist
- WiFi credentials and onboarding completion state
- paired Bluetooth devices
- last active source
- last user volume
- display brightness preference
- optional UI language or theme selection
- service/debug counters if needed
Open Design Decisions for Later Implementation
- exact host processor and software framework
- exact streaming service scope and protocol support
- exact display type and rendering capability
- exact knob technology: rotary encoder, potentiometer, or hybrid with push action
- exact battery gauge method: simple percentage estimate vs dedicated fuel-gauge integration
- resume behavior after power loss or battery depletion
- whether standby should keep network services partially alive
Implications for Schematic and PCB Design
Firmware architecture implies the hardware should expose:
- reliable display interface
- deterministic knob/control inputs
- battery and charging telemetry signals
- audio mute or enable control paths
- stable high-current and quiet low-noise power domains where needed
- sufficient nonvolatile storage and debug access
- status signals for charger, external power, and fault conditions if available
Verification Focus Areas
- boot-to-usable-UI time
- Bluetooth pairing and reconnect reliability
- WiFi onboarding success rate
- stream interruption recovery
- volume responsiveness under CPU/network load
- display readability in idle, playback, and warning states
- battery indication correctness across charge/discharge conditions
- orderly shutdown behavior at critical battery state