Deployment Guide

Prerequisites

Raspberry Pi 4 with BlueOS installed
ESP32-WROOM-32UE DevKit-C v4
PlatformIO CLI or VSCode with PlatformIO extension
Docker (included in BlueOS)
Git

ESP32 Firmware Deployment

1. Install PlatformIO

# Option A: CLI
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o get-platformio.py
python3 get-platformio.py

# Option B: VSCode extension
# Install "PlatformIO IDE" extension

2. Flash Firmware

cd esp32-sensor-hub
pio run --target upload --upload-port /dev/ttyUSB0

Troubleshooting flash:

If port not found: ls /dev/tty* and check USB connection
If permission denied: sudo usermod -a -G dialout $USER (logout/login)
If ESP32 not detected: Hold BOOT button while connecting USB

3. Verify Serial Output

pio device monitor --baud 115200

Expected output:

[SERIAL] Opening /dev/ttyUSB0 @ 115200...
[MS5837] OK C1=46372 C2=42768
[TSYS01] OK k0=63258
[IMU] HWT905 ready
[KOGGER] A: UART1 ready
[KOGGER] B: UART2 ready

Docker Services Deployment

1. Clone Repository

ssh pi@192.168.0.174
cd /home/workspace
git clone ssh://git@192.168.0.82:10022/floppyrj45/bluerov-slam.git slam

2. Build Docker Images

cd slam/blueos-extension
docker build -t bluerov-slam-hub:latest .

cd ../kogger-viewer
docker build -t bluerov-kogger-viewer:latest .

3. Create docker-compose.yml

Create /home/workspace/slam/docker-compose.yml:

version: "3.8"

services:
  slam-hub:
    image: bluerov-slam-hub:latest
    container_name: slam-hub
    restart: unless-stopped
    network_mode: host
    privileged: true
    environment:
      - SERIAL_PORT=/dev/ttyUSB0
      - BAUD=115200
      - WS_PORT=8766
      - HTTP_PORT=8099
      - MAVLINK_ENABLED=1
      - MAVLINK_TARGET=192.168.2.2
      - MAVLINK_PORT=14401
    devices:
      - /dev:/dev
    volumes:
      - /usr/blueos/extensions/slam-hub:/app/logs

  kogger-viewer:
    image: bluerov-kogger-viewer:latest
    container_name: kogger-viewer
    restart: unless-stopped
    network_mode: host
    environment:
      - HTTP_PORT=8100
      - WS_PORT=8101
      - UDP_PORT_A=14555
      - UDP_PORT_B=14556

4. Start Services

docker compose up -d

5. Check Status

docker compose ps
docker compose logs -f slam-hub
docker compose logs -f kogger-viewer

# API health checks
curl http://localhost:8099/health
curl http://localhost:8100/health

Rebuild & Update

Update Code

cd /home/workspace/slam
git pull origin master

Rebuild Images

docker compose down
docker compose build --no-cache
docker compose up -d

Rebuild ESP32 Only

cd esp32-sensor-hub
pio run --target upload

View Logs

Docker Logs

# Real-time logs
docker compose logs -f slam-hub
docker compose logs -f kogger-viewer

# Last 100 lines
docker compose logs --tail=100 slam-hub

JSONL Session Logs

# On Pi
ls -lh /usr/blueos/extensions/slam-hub/

# View latest session
tail -f /usr/blueos/extensions/slam-hub/session_*.jsonl | jq

Serial Monitor (ESP32)

pio device monitor --baud 115200

Monitoring & Health Checks

Service Status

curl http://192.168.0.174:8099/api/status | jq
curl http://192.168.0.174:8100/api/status | jq

Expected healthy output:

{
  "frames": 12345,
  "serial_connected": true,
  "ws_port": 8766,
  "crc_errors": 0
}

WebSocket Test

# Install websocat
cargo install websocat

# Listen to sensor frames
websocat ws://192.168.0.174:8766

# Listen to waterfall pings
websocat ws://192.168.0.174:8101

Automatic Startup

BlueOS Extension (Recommended)

Register as BlueOS extension (UI or manifest)
Auto-starts on boot via BlueOS extension manager

Systemd Service (Alternative)

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

[Unit]
Description=BlueROV SLAM Services
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/workspace/slam
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl daemon-reload
sudo systemctl enable slam.service
sudo systemctl start slam.service

Production Checklist

Before Deployment

[ ] ESP32 firmware flashed and tested
[ ] Serial port permissions configured (/dev/ttyUSB0 accessible)
[ ] Docker images built successfully
[ ] Health endpoints return 200 OK
[ ] WebSocket connections stable
[ ] Sensor data flowing (check /api/latest)
[ ] Kogger sonars powered and detected
[ ] MAVLink bridge tested (if enabled)

Post-Deployment

[ ] Monitor logs for errors (first 10 minutes)
[ ] Verify waterfall display renders correctly
[ ] Check JSONL log file creation
[ ] Test auto-restart (docker compose restart)
[ ] Document any custom configuration
[ ] Backup configuration files to Git

Backup & Restore

Backup Configuration

cd /home/workspace/slam
tar czf slam-backup-$(date +%Y%m%d).tar.gz \
    docker-compose.yml \
    blueos-extension/ \
    kogger-viewer/ \
    esp32-sensor-hub/

Restore from Backup

tar xzf slam-backup-20260327.tar.gz
cd slam
docker compose up -d