Phone WebSocket Client
Relevant source files
The following files were used as context for generating this wiki page:
The Phone WebSocket Client is the companion mobile application component of the BT Speaker Studio project. Its primary purpose is to act as a remote controller for the Raspberry Pi-based speaker system, facilitating the transmission of control data including equalizer settings, LED commands, and media metadata. In the current architecture (Phase 1), the phone application operates as a dedicated client that establishes a unidirectional communication stream toward the Pi hardware.
Sources: CLAUDE.md:21-25, README.md:1-5
System Architecture
The client is built using the Flutter framework and is designed to target both iOS and Android platforms. It functions within a Melos monorepo environment, specifically residing in the apps/phone_app/ directory. The client relies heavily on the bt_speaker_core package for shared data models to ensure that JSON serialization and deserialization remain consistent between the mobile client and the Raspberry Pi server.
Sources: CLAUDE.md:8-13, apps/phone_app/pubspec.yaml:33-35
Component Relationship
The following diagram illustrates the relationship between the Phone Client, the shared core models, and the Pi Server.
The client sends control signals to the Pi, which manages the hardware visualizer and LED ring.
Sources: CLAUDE.md:21-25, README.md:23-28
Communication Protocol
The Phone Client connects to the Raspberry Pi over a WebSocket connection on port 8080. The Pi server is configured to accept only one connection at a time, rejecting additional clients with an HTTP 503 status code. Communication is strictly typed using a JSON-based protocol where every message includes a type field to identify the payload.
Sources: CLAUDE.md:21-26, README.md:29-31
Message Types and Data Models
The client utilizes four primary data models defined in the shared core package to communicate state changes to the Pi.
| Message Type | Data Model | Description |
|---|---|---|
beat | BeatData | FFT frequency bars, BPM, and intensity for the visualizer. |
eq | EqSettings | Equalizer adjustments for bass, mid, and treble. |
led | LedCommand | Commands for the WS2812B LED ring (modes and colors). |
now_playing | NowPlaying | Metadata including track title, artist, and progress. |
Sources: CLAUDE.md:24-25, README.md:36-40
Connection Flow
The following sequence diagram represents the interaction between the Phone Client and the Pi-based server during a typical control session.
The Phone Client initiates the connection; once established, it pushes state updates to the Pi.
Sources: CLAUDE.md:23-26, README.md:29-31
Implementation Details
Dependency Configuration
The client application integrates several key Flutter packages to manage its operations. It specifically avoids naming collisions between flutter/material.dart and dart:async by hiding the standard ConnectionState when necessary.
dependencies:
bt_speaker_core:
path: ../../packages/bt_speaker_core
flutter_bloc: ^9.1.1
flutter_secure_storage: ^9.2.4
http: ^1.2.2
url_launcher: ^6.3.1
Sources: apps/phone_app/pubspec.yaml:33-43, CLAUDE.md:28-34
State Management
The client follows a BLoC-per-feature pattern using the flutter_bloc library. This architecture ensures that different control aspects (such as EQ, LEDs, and Connection status) are isolated into specific business logic components. Although the phone app implementation is part of the ongoing roadmap (Phase 4), it is designed to mirror the event-driven architecture of the Pi application.
Sources: CLAUDE.md:37-41, README.md:33-40
Conclusion
The Phone WebSocket Client serves as the primary interface for user interaction within the BT Speaker Studio ecosystem. By utilizing a shared core library and a strictly typed WebSocket protocol, it provides a low-latency control mechanism for the Raspberry Pi's audio visualization and LED hardware. Its implementation ensures that complex audio and lighting states can be managed remotely from a mobile device with high technical accuracy.
Sources: README.md:5-10, CLAUDE.md:54-58