pi-pm3/REFACTORING_ROADMAP.md

Dangerous Pi - Refactoring Roadmap

Last Updated: 2025-12-30 Overall Status: ✅ 100% Complete - All Sprints Done

This document consolidates all refactoring efforts into a single source of truth.

---

Executive Summary

Refactor	Status	Details
Service Layer Pattern	✅ Complete	REST + BLE share 100% business logic
BLE GATT Handlers	✅ Complete	22+ characteristics, all handlers ready
Multi-PM3 Device Manager	✅ Complete	Discovery, enumeration, status tracking
Multi-PM3 API Endpoints	✅ Complete	6 device management endpoints
Multi-PM3 Frontend	✅ Complete	DeviceSelector component
SessionManager Per-Device	✅ Complete	Per-device sessions working
Switch to SWIG Worker	✅ Complete	SWIG bindings working on Pi
BLE/BlueZ Integration	✅ Complete	bless library, BlueZGATTAdapter

---

Completed Work (Reference Only)

1. Service Layer Pattern ✅

Completed: 2025-11-26

All business logic centralized in service layer. Both REST API and BLE GATT use identical code paths.

Files created:

• app/backend/services/pm3_service.py - PM3 command execution
• app/backend/services/system_service.py - System operations
• app/backend/services/wifi_service.py - WiFi management
• app/backend/services/update_service.py - Software updates
• app/backend/services/container.py - Dependency injection

Test coverage: 115+ tests, 94% coverage

See: docs/archive/REFACTORING_PLAN.md for original design

2. BLE GATT Handlers ✅

Completed: 2025-11-26

All GATT characteristic handlers implemented as thin adapters calling service layer.

Files created:

• app/backend/ble/gatt_server.py - 22+ characteristic handlers
• app/backend/ble/characteristics.py - UUID definitions

See: docs/archive/BLUETOOTH_REFACTORING_COMPLETE.md for details

3. Multi-PM3 Device Manager ✅

Completed: 2025-11-26

Full device discovery, status tracking, and management.

Files created:

• app/backend/managers/pm3_device_manager.py - Device management
• app/frontend/app/components/DeviceSelector.tsx - UI component
• Database schema: devices, sessions.device_id, firmware_flash_log tables

See: docs/archive/MULTI_PM3_REFACTORING_PLAN.md for design decisions

---

All Sprints Complete

All refactoring work has been completed. The following sections document what was done for reference.

Sprint A: SessionManager Per-Device Support ✅

Completed: Per-device session isolation for multi-PM3 support.

Sprint B: Switch to SWIG Worker ✅

Completed: SWIG bindings for faster PM3 communication.

Sprint C: BLE/BlueZ Integration ✅

Completed: 2025-12-30

Full BLE GATT server operational with BlueZ via the bless library.

Implementation:

• Added bless>=0.2.5 to requirements.txt
• Created app/backend/ble/bluez_adapter.py - BlueZGATTAdapter class using add_gatt() dictionary pattern
• Fixed UUID format in characteristics.py (was generating invalid 13-char segments)
• Integrated with existing ble_manager.py for seamless startup
• All 4 GATT services registered (PM3, WiFi, System, Update)
• Notification sending implemented via bless
• Automatic fallback to basic advertising if bless unavailable

Tested: Successfully started/stopped GATT server on local machine with BlueZ

Service UUIDs:

• PM3: d4c3b2a1-0000-1000-8000-00805f9b0000
• WiFi: d4c3b2a1-0000-1000-8000-00805f9b0010
• System: d4c3b2a1-0000-1000-8000-00805f9b0020
• Update: d4c3b2a1-0000-1000-8000-00805f9b0030

Files created/modified:

• requirements.txt - Added bless dependency
• app/backend/ble/bluez_adapter.py - New BlueZ adapter
• app/backend/ble/characteristics.py - Fixed UUID format
• app/backend/ble/__init__.py - Updated exports
• app/backend/managers/ble_manager.py - Integrated GATT adapter

---

Hardware Testing Checklist

Environment: Raspberry Pi Zero 2 W with PM3 Easy (Iceman firmware)

Basic Validation

• Device discovery: curl http://localhost:8000/api/pm3/devices
• Command execution: curl -X POST http://localhost:8000/api/pm3/command -d '{"command":"hw version"}'
• Session creation with device_id
• Session timeout and auto-release

LED Identification

• Test hw led --led a --brightness 100 on real hardware
• Verify LED control works for device identification
• Document any firmware-specific quirks

BLE Testing

Local Testing (completed on dev machine):

• GATT server starts successfully with bless library
• All 4 services registered (PM3, WiFi, System, Update)
• Server stops cleanly
• BlueZ D-Bus integration working

Pi Hardware Testing (2025-12-30):

• bless library installed on Pi (v0.3.0)
• Standalone bless test script runs successfully (30s advertising, no errors)
• GATT services registered in BlueZ (visible via bluetoothctl show)
• BLE manager integrated with dangerous-pi service
• Bluetooth auto-enable configured in /etc/bluetooth/main.conf
• Scan from nearby phone/laptop to verify discovery (confirmed via Ubuntu BT settings)
• Connect via gatttool and browse GATT services - all 4 services discovered
• Read characteristics successfully (PM3 STATUS, WiFi MODE, etc.)
• Write to PM3 COMMAND characteristic successfully
• Receive notification with command result (requires PM3 attached)
• Test with actual PM3 device attached

API Compatibility Fixes (2025-12-30):

• bless 0.3.0 changed callback registration: on_read → read_request_func, on_write → write_request_func
• bless 0.3.0 changed update_value() from async to sync
• Fixed UUID case sensitivity (UUIDs must be lowercase to match our definitions)
• Fixed async deadlock: BLE callbacks cannot block on event loop, so reads return cached values
• Fixed GATT handler to handle multi-device PM3 response format

Known Issues:

• Bluetooth was blocked by rfkill on first boot; fixed by adding AutoEnable=true to BlueZ config
• Pi Zero 2 W has limited BLE range (~5-10m indoors) - ensure proximity during testing
• Standard bluetoothctl connect tries classic Bluetooth, not BLE - use gatttool for LE connections

---

Quick Reference: Key Files

Service Layer

• app/backend/services/pm3_service.py
• app/backend/services/container.py

Device Management

• app/backend/managers/pm3_device_manager.py
• app/backend/managers/session_manager.py

BLE (full GATT server)

• app/backend/ble/gatt_server.py - GATT handlers
• app/backend/ble/bluez_adapter.py - bless integration
• app/backend/managers/ble_manager.py - startup/lifecycle

API Endpoints

• app/backend/api/pm3.py

Database

• app/backend/models/database.py

---

Configuration Decisions

Recorded from user during planning session:

Decision	Choice	Rationale
PM3 Worker Type	SWIG Bindings	Faster, direct hardware access
Session Model	Per-device	Allow concurrent use of multiple PM3s
BLE Priority	High	Mobile app and field use without WiFi
PM3 Firmware	Iceman/RRG	Has hw led commands for identification

---

Archived Documents

Moved to docs/archive/ - can be deleted when no longer needed:

Document	Content
docs/archive/REFACTORING_PLAN.md	Service layer design
docs/archive/REFACTORING_SUMMARY.md	Service layer summary
docs/archive/BLUETOOTH_REFACTORING_COMPLETE.md	BLE handlers details
docs/archive/MULTI_PM3_REFACTORING_PLAN.md	Multi-PM3 design (86KB)
docs/archive/MULTI_PM3_PROGRESS.md	Old progress tracker

---

Version History

Date	Changes
2025-12-30	Deployed and tested BLE on Pi hardware; bless works, configured auto-enable
2025-12-30	Fixed UUID format in characteristics.py, tested BLE server locally
2025-12-30	Sprint C complete: BLE/BlueZ integration with bless library
2025-12-30	Created unified roadmap, consolidated 5 documents
2025-11-26	Service layer + BLE handlers completed
2025-11-26	Multi-PM3 device manager + API completed