WebSocket Protocol & Communication

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• packages/bt_speaker_core/pubspec.yaml
• apps/pi_app/pubspec.yaml
• apps/phone_app/pubspec.yaml

The WebSocket Protocol & Communication system serves as the primary data exchange layer between the pi_app (server) and the phone_app (client). This system enables real-time control of audio visualization, equalizer settings, and LED hardware connected to a Raspberry Pi Zero 2 W. The architecture is designed to support low-latency updates required for synchronizing a visualizer UI and LED ring with audio playback.

Communication is primarily unidirectional in its initial implementation, with the phone acting as the controller that pushes state changes and metadata to the Pi-based speaker. The protocol uses typed JSON messages derived from shared data models to ensure consistency across the monorepo.

Sources: CLAUDE.md:27-33, README.md:20-23

Architecture & Topology

The communication architecture follows a strict Client-Server model over a local network. The Raspberry Pi host (pi_app) initiates a WebSocket server on a dedicated port, while the companion mobile device (phone_app) acts as the exclusive controller.

• Host: Raspberry Pi Zero 2 W (IP: 192.168.1.70).
• Server Port: 8080.
• Concurrency: The server is restricted to a single connection; subsequent client connection attempts are rejected with an HTTP 503 (Service Unavailable) status.

Sources: CLAUDE.md:14, CLAUDE.md:27-31

Communication Flow

The following diagram illustrates the unidirectional flow of control messages from the phone to the Pi hardware and UI.

The Pi app utilizes flutter_bloc to distribute incoming WebSocket messages to specific feature modules. Each BLoC subscribes to a shared event stream generated by the WebSocket server.
Sources: CLAUDE.md:27-31, README.md:25-33

Message Protocol Definition

All communication occurs via JSON-encoded strings. Each message must include a type field which determines how the payload is parsed and routed within the Pi app's state management layer.

Message Types and Models

Message Type	Shared Model Class	Purpose
beat	BeatData	Live audio data (FFT bars, BPM, intensity) for visualizer.
eq	EqSettings	Real-time equalizer adjustments (Bass, Mid, Treble).
led	LedCommand	Commands for the WS2812B LED ring (Mode, Color).
now_playing	NowPlaying	Track metadata (Title, Artist, Album Art, Progress).

Sources: CLAUDE.md:27-31, README.md:20-33

Data Handling Sequence

When a message is received by the pi_app, it undergoes a transformation from raw JSON to typed events.

Package Integration

The communication system relies on the bt_speaker_core package to provide the serialization logic used by both applications. This prevents schema drift between the client and server.

• bt_speaker_core: Contains toJson() and fromJson() implementations for all message types.
• pi_app: Implements the server and maps incoming messages to a sealed class hierarchy of events (BeatEvent, LedEvent, EqEvent, NowPlayingEvent).
• phone_app: Implements the client and serializes user inputs into the defined JSON format.

Sources: CLAUDE.md:30-31, README.md:20-23, packages/bt_speaker_core/pubspec.yaml

Implementation Constraints

• Platform Specifics: The Pi app runs on flutter-pi using DRM/KMS without an X server. WebSocket communication must handle high-frequency data (30–60 Hz for beat data) to ensure smooth rendering in the VisualizerPainter.
• Naming Hazards: Developers must hide ConnectionState when importing material.dart if a custom connection state is used, as dart:async and flutter/material.dart both export this identifier.
• Testing: Integration tests for the communication layer utilize real WebSocketServer instances bound to port 0 (OS-assigned) to verify the networking handshake and data parsing.

Sources: CLAUDE.md:12-13, CLAUDE.md:34-38, CLAUDE.md:46-49, README.md:35-37

Conclusion

The WebSocket Protocol & Communication system provides a robust, typed infrastructure for real-time interaction between the phone controller and the Raspberry Pi speaker. By centralizing data models in a shared package and utilizing a single-connection server model, the project ensures reliable, low-latency control of both the visual interface and hardware peripherals.