Extending the Event Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The Event Protocol serves as the communication backbone for the BT Speaker Studio project, facilitating unidirectional message flow from the phone_app (client) to the pi_app (server) over a WebSocket connection on port 8080. This protocol enables real-time synchronization of audio visualization data, equalizer settings, LED hardware commands, and media metadata across the distributed system components.
Sources: CLAUDE.md:32-37, README.md:21-25
Protocol Architecture and Data Flow
The protocol utilizes a typed JSON messaging system defined within the bt_speaker_core package. Messages are categorized by a mandatory type field, which the Pi app uses to route data to the appropriate BLoC for state management. The current architecture supports four primary event categories, with the capacity for extension through a sealed class hierarchy.
The following sequence diagram illustrates the flow of a protocol event from the mobile interface to the Raspberry Pi hardware components:
The Pi application manages a single-client connection; if a second client attempts to connect, the server issues an HTTP 503 response.
Sources: CLAUDE.md:32-37, README.md:27-35
Core Data Models
Shared models reside in packages/bt_speaker_core and implement toJson() and fromJson() methods for serialization. These models define the schema for all exchanged events.
Message Types and Schema
| Event Type | Model Class | Purpose | Key Data Fields |
|---|---|---|---|
beat | BeatData | Live audio analysis | FFT bars, BPM, intensity |
eq | EqSettings | Audio frequency adjustment | Bass, Mid, Treble |
led | LedCommand | Peripheral visual control | Mode, Color |
now_playing | NowPlaying | Media metadata | Title, Artist, Album art, Progress |
Sources: CLAUDE.md:32-35, README.md:27-35
Implementation of New Events
To extend the protocol, developers must follow a multi-package workflow within the Melos monorepo. This ensures that both the sender (phone) and receiver (Pi) share a unified definition of the new event type.
Step 1: Core Model Definition
New models must be defined in packages/bt_speaker_core and include serialization logic.
// Example of a new event definition structure
// Located in packages/bt_speaker_core/lib/src/models/
class NewFeatureCommand {
final String type = 'new_feature';
final Map<String, dynamic> data;
Map<String, dynamic> toJson() => {'type': type, ...data};
}
Sources: CLAUDE.md:35-36, packages/bt_speaker_core/pubspec.yaml
Step 2: BLoC Integration in Pi App
The pi_app utilizes flutter_bloc to handle incoming events. Each feature maintains its own BLoC which subscribes to the shared WebSocket stream.
New events are integrated into the Pi's state management by adding them to the sealed class hierarchy and implementing a corresponding BLoC listener.
Sources: CLAUDE.md:46-49, README.md:27-35
Constraints and Hazards
When extending the protocol or UI elements, developers must adhere to specific technical constraints:
- Naming Hazards: If a new event involves
ConnectionState, thedart:asyncimport must be hidden to avoid conflicts withflutter/material.dart. - Hardware Architecture: The Raspberry Pi target is armv7 (32-bit). Any protocol extensions requiring native libraries must be compatible with this architecture.
- Performance: Visual data (like
BeatData) is processed at 30–60 Hz. Protocol extensions should not introduce blocking operations that interfere with theCustomPainterrendering cycle.
Sources: CLAUDE.md:14-16, CLAUDE.md:39-44, README.md:42-45
Summary
Extending the Event Protocol involves updating the shared bt_speaker_core models, implementing serialization, and registering new event types within the pi_app BLoC architecture. This centralized approach ensures type safety and consistent communication between the companion phone application and the Pi-based display system.