Hardware Setup & Requirements
Relevant source files
The following files were used as context for generating this wiki page:
This page details the specific hardware components and configuration requirements for the BT Speaker Studio project. The system is designed around a Raspberry Pi Zero 2 W acting as the central display and server, interacting with peripheral audio and lighting hardware while being controlled by a mobile companion application.
Sources: README.md:1-8, CLAUDE.md:3-10
Core System Components
The project utilizes a specific set of hardware to achieve high-performance audio visualization and playback. The Raspberry Pi Zero 2 W is the primary compute module, chosen for its quad-core ARM capabilities.
Raspberry Pi Configuration
The Raspberry Pi serves as the host for the pi_app, which runs using flutter-pi. This environment is unique because it operates without a standard X server, using DRM/KMS for direct rendering to the display.
| Component | Specification | Purpose |
|---|---|---|
| SoC | Quad-core ARM Cortex-A53 @ 1 GHz | Primary Processing |
| RAM | 512 MB | System Memory |
| Architecture | armv7 (32-bit) | Target Build Architecture |
| Runtime | flutter-pi | DRM/KMS Graphics Rendering |
| Hostname | Base27 (192.168.1.70) | Network Identification |
Sources: README.md:12-14, CLAUDE.md:20-25
Peripheral Hardware
The system integrates several specialized peripherals for outputting audio and visual signals.
- HDMI Display: Used to render the Flutter visualizer UI.
- WS2812B 16-LED Ring: An addressable RGB ring used for beat-synced lighting effects.
- MAX98357A I2S Amp: (Phase 2) A dedicated I2S DAC/amplifier for high-quality audio output.
Sources: README.md:15-18
Hardware Interfacing & Wiring
The Raspberry Pi communicates with peripherals through specific GPIO pins and protocols. The LED ring, in particular, requires high-speed communication via the Serial Peripheral Interface (SPI).
The diagram shows the physical connection paths between the Raspberry Pi and the specialized output hardware.
Sources: README.md:12-18, CLAUDE.md:65-68
Connectivity Requirements
The hardware setup requires a stable local network connection to facilitate WebSocket communication between the phone client and the Pi server.
- Server Port: The Pi host runs a WebSocket server on port
8080. - Protocol: Typed JSON messages (
beat,eq,led,now_playing). - Constraint: The Pi app is designed to reject a second client with an HTTP 503 error to ensure stable performance on the Zero 2 W hardware.
Sources: CLAUDE.md:31-35, README.md:28-32
Software Environment Requirements
To support the hardware, specific software versions and build configurations must be maintained. Both the pi_app and phone_app are built using Flutter, but they target different execution environments.
Toolchain and Dependencies
The project is managed as a Melos monorepo, requiring Dart SDK version ^3.11.5.
| Package | Key Dependencies | Target Platform |
|---|---|---|
| pi_app | bt_speaker_core, flutter_bloc | Linux (flutter-pi) |
| phone_app | app_links, flutter_secure_storage, http | iOS / Android |
| bt_speaker_core | flutter | Shared Library |
Sources: apps/pi_app/pubspec.yaml:22-31, apps/phone_app/pubspec.yaml:37-51, packages/bt_speaker_core/pubspec.yaml:8-13
Build Configuration for Raspberry Pi
Deployment to the hardware requires specific flags to match the ARM Cortex-A53 architecture. Developers must use the flutterpi_tool for builds.
# Command for hardware deployment
flutterpi_tool build --arch=arm --cpu=generic --release
Sources: CLAUDE.md:24-25
Conclusion
The Hardware Setup for BT Speaker Studio is optimized for the Raspberry Pi Zero 2 W. By utilizing flutter-pi for direct DRM/KMS rendering and standardizing on I2S and SPI for peripherals, the system achieves the low-latency response required for real-time audio visualization and LED synchronization.