Custom Hardware Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Custom Hardware Integration system enables the BT Speaker Studio to function as a dedicated embedded Bluetooth speaker display using a Raspberry Pi Zero 2 W. The integration facilitates high-performance audio visualization, real-time lighting control via addressable LEDs, and high-fidelity audio output through specialized I2S amplification.
This system leverages a monorepo architecture where a central pi_app runs on the Pi hardware, receiving commands and metadata from a companion phone_app via a WebSocket-based communication layer. The integration is designed to run in a resource-constrained environment using a specialized Flutter embedder.
Sources: README.md:1-21, CLAUDE.md:5-12
Hardware Components and Interfaces
The project integrates several specific hardware modules to achieve its functionality as a smart speaker.
| Component | Interface | Description |
|---|---|---|
| Raspberry Pi Zero 2 W | N/A | Central processing unit (Quad-core ARM Cortex-A53, 512 MB RAM). |
| HDMI Display | DRM/KMS | Output for the Flutter-based visualizer UI. |
| WS2812B LED Ring | GPIO 10 (SPI) | 16-LED addressable RGB ring for beat-synced lighting effects. |
| MAX98357A Amp | I2S | Digital-to-analog converter and amplifier for audio output (Phase 2). |
Sources: README.md:10-18, CLAUDE.md:17-21, CLAUDE.md:65-71
Raspberry Pi Target Environment
The hardware integration targets the armv7 (32-bit) architecture. The system does not use a standard desktop Flutter embedder or X server; instead, it utilizes flutter-pi, which interfaces directly with the Linux DRM/KMS (Direct Rendering Manager / Kernel Mode Setting) subsystem.
Sources: CLAUDE.md:17-25, README.md:12-13
Architecture and Data Flow
Hardware integration is managed through a layered architecture. The bt_speaker_core package defines the shared models that represent hardware states and commands, while the pi_app translates these models into physical outputs.
The diagram shows the unidirectional flow of control data from the mobile application to the custom hardware components on the Raspberry Pi.
Sources: README.md:23-45, CLAUDE.md:27-32
Messaging Protocol
Communication with the hardware is facilitated through typed JSON messages. The pi_app parses these into specific events to drive hardware state changes:
BeatData: High-frequency FFT frequency bars and intensity data (~30–60 Hz).EqSettings: Equalizer parameters (bass, mid, treble).LedCommand: Commands for LED modes and colors.NowPlaying: Metadata including track title, artist, and progress.
Sources: README.md:31-45, CLAUDE.md:27-32
Specific Implementation Details
Audio Visualization
The visualizer is optimized for the Pi Zero 2 W's quad-core ARM processor. It bypasses the standard Flutter AnimationController to reduce overhead, instead using a CustomPainter to draw FFT frequency bars directly to the Canvas at the rate data is received from the WebSocket.
Sources: README.md:47-51, CLAUDE.md:9-11
LED Ring Control
The 16-LED WS2812B ring is integrated via the SPI interface on GPIO 10. Implementation plans involve using the dart_periphery library to handle the low-level SPI communication required to drive the addressable RGB LEDs in synchronization with the BeatData.
Sources: README.md:14-15, README.md:58, CLAUDE.md:69
Build and Deployment
Deploying to the custom hardware requires specific toolchains to target the ARM architecture:
# Build command for Raspberry Pi target
flutterpi_tool build --arch=arm --cpu=generic --release
Sources: CLAUDE.md:23-24
Dependency Management
The hardware integration relies on a specific set of Dart packages to facilitate communication and state management.
| Package | Purpose |
|---|---|
bt_speaker_core | Local package containing shared hardware data models. |
flutter_bloc | Manages state for specific hardware features (LedBloc, EqBloc). |
dart_periphery | (Planned) Provides GPIO and SPI access for hardware peripherals. |
Sources: apps/pi_app/pubspec.yaml:26-33, README.md:53-59, CLAUDE.md:36-41
Conclusion
Custom Hardware Integration in the BT Speaker project bridges the gap between high-level Flutter UI and low-level Linux hardware interfaces. By utilizing flutter-pi for rendering and specialized BLoCs for state management, the system provides a responsive environment for audio visualization and peripheral control on limited-resource hardware like the Raspberry Pi Zero 2 W.