# 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):**
- [x] GATT server starts successfully with bless library
- [x] All 4 services registered (PM3, WiFi, System, Update)
- [x] Server stops cleanly
- [x] BlueZ D-Bus integration working

**Pi Hardware Testing (2025-12-30):**
- [x] bless library installed on Pi (v0.3.0)
- [x] Standalone bless test script runs successfully (30s advertising, no errors)
- [x] GATT services registered in BlueZ (visible via `bluetoothctl show`)
- [x] BLE manager integrated with dangerous-pi service
- [x] Bluetooth auto-enable configured in `/etc/bluetooth/main.conf`
- [x] Scan from nearby phone/laptop to verify discovery (confirmed via Ubuntu BT settings)
- [x] Connect via gatttool and browse GATT services - all 4 services discovered
- [x] Read characteristics successfully (PM3 STATUS, WiFi MODE, etc.)
- [x] 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 |