Raspberry Pi Build & Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The Raspberry Pi Build and Deployment system for the BT Speaker project focuses on targeting a headless, embedded Linux environment using Flutter. The primary goal is to deploy the pi_app to a Raspberry Pi Zero 2 W to drive an HDMI visualizer and control peripheral hardware like LED rings. Unlike standard Flutter deployments, this project utilizes a custom embedder to interface directly with the hardware's display capabilities without a traditional windowing system.
Sources: CLAUDE.md:1-20, README.md:1-15
Target Hardware and Environment
The deployment targets the Raspberry Pi Zero 2 W, utilizing its quad-core ARM processor for real-time audio visualization. The environment is optimized for performance by bypassing the X server and using direct rendering.
Hardware Specifications
| Feature | Details |
|---|---|
| CPU | Quad-core ARM Cortex-A53 @ 1 GHz |
| RAM | 512 MB |
| Architecture | armv7 (32-bit) |
| Display Interface | DRM/KMS via HDMI |
Sources: CLAUDE.md:18-21, README.md:7-12
Runtime and Embedder
The system uses flutter-pi, a light-weight Flutter engine embedder for Raspberry Pi that does not require an X server or Wayland. It communicates directly with the DRM/KMS (Direct Rendering Manager / Kernel Mode Setting) to render the UI.
Sources: CLAUDE.md:22, README.md:10
Build Configuration
The build process for the Pi application is strictly defined to ensure compatibility with the 32-bit ARM architecture of the Pi Zero 2 W. The application is built using the flutterpi_tool.
Build Commands and Architecture
Developers must target armv7 specifically; aarch64 is not supported for this hardware target. The release build is optimized for the generic ARM CPU features available on the Cortex-A53.
# Standard build command for Pi deployment
flutterpi_tool build --arch=arm --cpu=generic --release
Sources: CLAUDE.md:20-23
Cross-Compilation Logic
The project includes Linux-specific CMake configurations to handle cross-building and resource bundling. The build system manages a root filesystem (SYSROOT) for cross-building when the FLUTTER_TARGET_PLATFORM_SYSROOT flag is provided.
if(FLUTTER_TARGET_PLATFORM_SYSROOT)
set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
# ... configuration for cross-building ...
endif()
Sources: apps/pi_app/linux/CMakeLists.txt:19-27
Deployment Workflow
Deployment involves compiling the Flutter application into a specialized bundle and transferring it to the target device. The Pi is identified by the hostname Base27 and IP 192.168.1.70.
Deployment Architecture
The following diagram illustrates the flow from the development machine to the Raspberry Pi environment.
The diagram shows the transition from source code to direct hardware rendering on the Raspberry Pi.
Sources: CLAUDE.md:20-24, README.md:7-12
Application Bundling
The build system creates a relocatable bundle in the build/bundle directory. This bundle contains the executable, ICU data, Flutter library, and assets. The installation step ensures that AOT (Ahead-of-Time) libraries are included for non-debug builds to maximize performance.
Sources: apps/pi_app/linux/CMakeLists.txt:77-118
Monorepo Management for Build
The project uses Melos to manage builds and tests across the monorepo. This allows for unified linting and testing before deployment to the Pi.
Relevant Melos Scripts
| Script | Description |
|---|---|
melos run analyze | Runs static analysis on all packages to ensure code quality. |
melos run test | Executes the test suite, ensuring WebSocket and BLoC logic is sound. |
Sources: pubspec.yaml:22-55
Network Configuration
The Pi application acts as a WebSocket server, listening on port 8080. During deployment and runtime, it allows only a single client connection, typically from the phone_app.
The sequence diagram demonstrates the connection lifecycle between the companion app and the deployed Pi instance.
Sources: CLAUDE.md:27-33
Conclusion
The Raspberry Pi Build & Deployment system leverages specialized tools like flutter-pi and flutterpi_tool to deliver high-performance visualizers on low-power hardware. By using a DRM/KMS approach and strictly targeting the armv7 architecture, the project ensures the Pi Zero 2 W can maintain a high frame rate for FFT-based audio visualization while serving as a WebSocket control hub.
Sources: CLAUDE.md:18-23, README.md:39-44