blerc

Development Guide

Prerequisites

Raspberry Pi (target):

• Raspberry Pi 3B+ or newer (or any Linux with BlueZ 5.50+)
• BlueZ installed: sudo apt install bluez
• Raspberry Pi OS Bullseye or newer (glibc 2.31+)

Development machine:

• Rust 1.83+ (due to ICU crate dependencies)
• Node.js 18+ and Yarn 4.x
• Docker (for cross-compilation from non-ARM hosts)

Building

Rust Binary (blerc)

cd blerc

# Native build (on Pi or ARM)
cargo build --release

# Cross-compile for Raspberry Pi (from x86_64/ARM64)
# Option 1: Using Docker via Makefile (recommended)
make build           # Default: Bullseye-compatible
make build-bookworm  # Bookworm-compatible

# Option 2: Using cross tool
cargo install cross
cross build --target armv7-unknown-linux-gnueabihf --release

# Option 3: Manual toolchain (x86_64 only)
rustup target add armv7-unknown-linux-gnueabihf
sudo apt install gcc-arm-linux-gnueabihf
cargo build --target armv7-unknown-linux-gnueabihf --release

Webapp

cd webapp

# Install dependencies
yarn install

# Development server (hot reload)
yarn dev

# Production build
yarn build
# Output: dist/

Running

# Start BLE server
./blerc

# With debug logging
./blerc --debug

# Custom config file
./blerc --config /path/to/config.toml

Deploying

Rust Binary

Copy the built binary to your Pi:

scp blerc/target/armv7-unknown-linux-gnueabihf/release/blerc pi@raspberrypi:~/

Webapp

The webapp builds to static files:

cd webapp
yarn build

Serve options:

• Copy dist/ to any web server
• Deploy to GitHub Pages, Netlify, Vercel, etc.
• Local testing: python -m http.server -d dist

Note: WebBluetooth requires HTTPS in production. Localhost is exempt for development.

Systemd Service

Create /etc/systemd/system/blerc.service:

[Unit]
Description=BLE Remote Control
After=bluetooth.target

[Service]
Type=simple
User=pi
ExecStart=/home/pi/blerc
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable blerc
sudo systemctl start blerc

Project Structure

blerc/
├── blerc/              # Rust binary
│   ├── src/
│   │   ├── main.rs
│   │   ├── config.rs   # Configuration parsing
│   │   ├── apps/       # App registry & execution
│   │   ├── ble/        # BLE GATT server
│   │   └── http/       # HTTP client for HTTP apps
│   ├── Cargo.toml
│   └── Makefile        # Cross-compilation targets
├── webapp/             # PWA webapp
│   ├── src/
│   │   ├── main.ts     # Entry point
│   │   ├── ble.ts      # WebBluetooth client
│   │   └── style.css
│   └── package.json
├── config/             # Example configuration
├── docs/               # Documentation
└── openspec/           # Specifications & proposals

Dependency Management

See dep_versions.md for:

• Current tool versions
• Update procedures
• Minimum version requirements
• Target OS compatibility matrix