Embedded WebSocket Server
Relevant source files
The following files were used as context for generating this wiki page:
The Embedded WebSocket Server is the core communication hub of the BT Speaker project. It resides within the pi_app running on the Raspberry Pi Zero 2 W, acting as a bridge between the companion phone_app and the hardware-integrated display and LED systems. Its primary purpose is to ingest real-time control data and metadata to drive the visualizer and speaker settings.
Sources: CLAUDE.md:28-28, README.md:22-24
Architecture and Protocol
The server operates on port 8080 of the Raspberry Pi. The communication flow is currently unidirectional (Phone to Pi), where the phone acts as the client and the Pi acts as the server. To ensure stability and resource management on the Pi Zero 2 W, the server enforces a single-client policy, rejecting subsequent connection attempts with an HTTP 503 (Service Unavailable) response.
Sources: CLAUDE.md:29-33, README.md:22-23
Communication Flow Diagram
The following diagram illustrates the unidirectional data flow from the Phone Client to the Raspberry Pi WebSocket Server.
Sources: CLAUDE.md:28-33, README.md:25-32
Data Models and Message Types
Messages sent over the WebSocket are JSON-encoded and include a mandatory type field. These messages are defined as shared models in the bt_speaker_core package to ensure consistency between the client and server.
Message Types
| Type | Data Model | Purpose |
|---|---|---|
beat | BeatData | Live FFT frequency bars, BPM, and pulse intensity for the visualizer. |
eq | EqSettings | Real-time equalizer settings including bass, mid, and treble. |
led | LedCommand | Commands for the WS2812B LED ring (modes and colors). |
now_playing | NowPlaying | Metadata for current track (title, artist, album art, progress). |
Sources: CLAUDE.md:31-32, README.md:16-16, README.md:26-32
Integration with State Management
The Pi application uses the flutter_bloc pattern to handle incoming data from the WebSocket server. Once the server parses a JSON message into a typed event, the events are broadcast to specific feature BLoCs that manage the application state.
Server-to-BLoC Mapping
The following sequence diagram shows how a message is received by the server and distributed to the internal BLoC layers.
Sources: README.md:25-32, README.md:34-36, CLAUDE.md:46-46
Configuration and Technical Implementation
Port and Network Details
- Default Port: 8080
- Pi IP Address: 192.168.1.70 (Host: Base27)
- Error Handling: Returns HTTP 503 if a client is already connected.
- Serialization: Models utilize
toJson()andfromJson()methods for cross-package compatibility.
Sources: CLAUDE.md:14-14, CLAUDE.md:29-33
Project Dependencies
The WebSocket implementation relies on core infrastructure defined across the monorepo:
packages/bt_speaker_core: Defines the sharedBeatData,NowPlaying,EqSettings, andLedCommandobjects.apps/pi_app: Implements the server hosting and state distribution logic.apps/phone_app: Implements the client-side connection and message dispatching.
Sources: apps/pi_app/pubspec.yaml:20-21, apps/phone_app/pubspec.yaml:38-39, packages/bt_speaker_core/pubspec.yaml:1-5
Summary
The Embedded WebSocket Server acts as the high-performance backbone of the BT Speaker Studio. By leveraging a typed JSON protocol and the BLoC pattern, it allows the Raspberry Pi to render low-latency audio visualizations (~30–60 Hz) and manage hardware peripherals like LED rings based on remote commands from the phone companion app.
Sources: README.md:34-36, CLAUDE.md:28-33