pilot/docs/development_roadmap.md

Pilot v2 - Development Roadmap

Last Updated: 2025-12-30

Current Status

Pilot v2 has a complete core implementation with MQTT connectivity, configuration management, telemetry, command handling, and Home Assistant discovery. See implementation_status.md for details.

Development Phases

Phase 1: Complete Feature Parity with v1 ⚠️ IN PROGRESS

Goal: Match all functionality from Python v1

1.1 CPU Temperature Telemetry

Priority: HIGH Complexity: Medium

Tasks:

• Add sysinfo support for CPU temperature (Linux: /sys/class/thermal/, /sys/class/hwmon/)
• Add Windows temperature reading (WMI or performance counters)
• Update telemetry provider trait
• Add CPU temp sensor to HA discovery
• Add unit tests

Files to modify:

• pilot-v2/src/telemetry/mod.rs
• pilot-v2/src/ha/mod.rs

Acceptance criteria:

• Publishes pilot/<device>/state/cpu_temp with temperature in °C
• Shows in Home Assistant as sensor with correct unit
• Works on Linux and Windows

1.2 Battery Status Telemetry ✅ COMPLETE (Linux)

Priority: MEDIUM Complexity: Medium Status: ✅ Implemented for Linux, ⚠️ Windows stub

What was done:

• ✅ Read from /sys/class/power_supply/ on Linux
• ✅ Detect BAT0, BAT1, or battery devices
• ✅ Publish battery percentage (0-100)
• ✅ Publish charging state (charging/discharging/full/not_charging)
• ✅ Add battery sensors to HA discovery
• ✅ Gracefully handle devices without battery (no messages published)

Still TODO:

• ⚠️ Implement Windows battery API (GetSystemPowerStatus)

Files modified:

• pilot-v2/src/telemetry/mod.rs:47-132
• pilot-v2/src/ha/mod.rs:58-59

Published topics (only on systems with battery):

• pilot/<device>/state/battery_level (0-100)
• pilot/<device>/state/battery_state (charging/discharging/full/not_charging/unknown)

1.3 GPU Telemetry (Multi-vendor)

Priority: LOW (P1 requirement) Complexity: HIGH

Tasks:

• Add dependency: nvml-wrapper for NVIDIA
• Research AMD and Intel GPU APIs
• Implement GPU detection and selection
• Publish GPU temperature, memory usage, utilization
• Update capabilities to include GPU flag
• Make GPU support optional (feature flag in Cargo.toml)

Files to create:

• pilot-v2/src/telemetry/gpu.rs

New topics:

• pilot/<device>/state/gpu_temp
• pilot/<device>/state/gpu_memory_used_mb
• pilot/<device>/state/gpu_memory_total_mb
• pilot/<device>/state/gpu_utilization

1.4 CPU Frequency Control

Priority: LOW Complexity: Medium

Tasks:

• Add command type for CPU frequency slider
• Linux: Write to /sys/devices/system/cpu/cpu*/cpufreq/scaling_setspeed
• Windows: Use power plan APIs
• Add range validation (min/max frequency)
• Update HA discovery with number entity
• Add to allowlist and cooldown system

Files to modify:

• pilot-v2/src/commands/mod.rs
• pilot-v2/src/platform/linux/mod.rs
• pilot-v2/src/ha/mod.rs

New topics:

• pilot/<device>/cmd/cpu_frequency/set (accepts GHz value)
• pilot/<device>/state/cpu_frequency (current frequency)

Phase 2: Complete Windows Support ⚠️ PARTIAL

Goal: Full functionality on Windows platform

2.1 Windows Power Control

Priority: HIGH Complexity: Medium

Tasks:

• Implement shutdown using Windows API (InitiateSystemShutdownEx)
• Implement reboot using Windows API
• Implement sleep/suspend (SetSuspendState)
• Add proper error handling
• Test on Windows 10/11

Files to modify:

• pilot-v2/src/platform/windows/mod.rs

Dependencies to add:

• windows or winapi crate

2.2 Windows Screen Control

Priority: MEDIUM Complexity: Medium

Tasks:

• Implement screen off using SendMessage(HWND_BROADCAST, WM_SYSCOMMAND, SC_MONITORPOWER, 2)
• Implement screen on
• Handle multiple monitors
• Test on different Windows versions

Files to modify:

• pilot-v2/src/platform/windows/mod.rs

2.3 Windows Service

Priority: MEDIUM Complexity: HIGH

Tasks:

• Add Windows service support using windows-service crate
• Create service installer/uninstaller
• Handle service lifecycle (start, stop, pause)
• Configure service to run at boot
• Add logging to Event Viewer

Files to create:

• pilot-v2/src/service/mod.rs
• packaging/install-windows-service.ps1

Phase 3: Production Readiness 🔲 NOT STARTED

Goal: Deploy to production Linux systems

3.1 Systemd Service Testing

Priority: HIGH Complexity: LOW

Tasks:

• Test existing systemd service file
• Verify permissions (sudoers or polkit)
• Test automatic startup on boot
• Test graceful shutdown
• Document deployment process
• Create install script

Files to modify:

• packaging/pilot.service
• docs/deploiement.md

Files to create:

• packaging/install-linux.sh

3.2 TLS/SSL Support

Priority: HIGH Complexity: MEDIUM

Tasks:

• Add TLS configuration to YAML (ca_cert, client_cert, client_key)
• Configure rumqttc with TLS options
• Test with mosquitto TLS broker
• Document certificate generation
• Add TLS validation tests

Files to modify:

• pilot-v2/src/config/mod.rs
• pilot-v2/src/mqtt/mod.rs
• config/config.example.yaml

3.3 Release Builds and Packaging

Priority: MEDIUM Complexity: MEDIUM

Tasks:

• Create release build configuration
• Strip debug symbols for smaller binaries
• Create .deb package for Debian/Ubuntu
• Create .rpm package for RHEL/Fedora
• Create Windows installer (MSI or NSIS)
• Set up CI/CD pipeline (GitHub Actions)
• Create release documentation

Files to create:

• .github/workflows/release.yml
• packaging/debian/
• packaging/rpm/
• packaging/windows/

3.4 Integration Test Suite

Priority: MEDIUM Complexity: HIGH

Tasks:

• Set up test MQTT broker (mosquitto in Docker)
• Create test fixtures and helpers
• Write integration tests for:
  • MQTT connection and disconnection
  • Telemetry publishing
  • Command reception and execution
  • HA discovery payload validation
  • LWT behavior
• Add to CI/CD pipeline

Files to create:

• pilot-v2/tests/integration/
• docker-compose.test.yml

Phase 4: Enhanced Features (P1) 🔲 NOT STARTED

Goal: Implement P1 priority features

4.1 GUI Configuration Tool (GNOME)

Priority: MEDIUM Complexity: HIGH

Tasks:

• Choose GUI framework (GTK4 with Rust bindings)
• Create config editor interface
• Add MQTT broker connection testing
• Add backend selection UI
• Add feature enable/disable toggles
• Validate and save config.yaml
• Create .desktop file for Linux

New project:

• pilot-config-gui/ (separate crate)

4.2 Web Dashboard (Optional)

Priority: LOW Complexity: VERY HIGH

Tasks:

• Design web app architecture (subscribe to MQTT directly or HTTP API?)
• Create device discovery system
• Build dashboard UI (React/Vue/Svelte)
• Show real-time telemetry graphs
• Enable command sending
• Add authentication
• Deploy as Docker container or static site

New project:

• pilot-dashboard/

Phase 5: Advanced Features (P2) 🔲 NOT STARTED

Goal: Security and extended capabilities

5.1 HMAC/Signature Security

Priority: LOW Complexity: HIGH

Tasks:

• Design signature scheme for commands
• Add HMAC validation module
• Configure shared secrets in config
• Sign outgoing messages
• Validate incoming command signatures
• Add replay attack prevention
• Document security model

Files to modify:

• pilot-v2/src/security/mod.rs
• pilot-v2/src/commands/mod.rs

5.2 Extended Power States

Priority: LOW Complexity: MEDIUM

Tasks:

• Add hibernate support (Linux: systemctl hibernate, Windows: API)
• Add lock screen support (Linux: loginctl lock-session, Windows: LockWorkStation)
• Detect hibernate state
• Detect locked state
• Add to HA discovery

5.3 Proxmox Integration

Priority: LOW Complexity: VERY HIGH

Tasks:

• Research Proxmox API
• Add Proxmox client dependency
• Implement VM enumeration
• Add VM start/stop commands
• Add VM status telemetry
• Design multi-device MQTT topics
• Update HA discovery for VMs

Files to create:

• pilot-v2/src/proxmox/

New topics:

• pilot/<device>/vms/<vm_id>/state (running/stopped)
• pilot/<device>/vms/<vm_id>/cmd/power/set (start/stop)

Development Workflow

For each feature:

1. Design: Update architecture docs if needed
2. Implement: Write code following existing patterns
3. Test: Add unit tests, run cargo test
4. Document: Update relevant .md files
5. Manual test: Use dry-run mode first, then real execution
6. Commit: Clear commit messages, reference issues

Recommended order:

Immediate (complete v1 parity):

1. CPU temperature (quick win)
2. Battery status (if laptop)
3. Windows power/screen backends (if Windows support needed)

Next (production readiness):

1. Systemd service testing
2. TLS support
3. Integration tests
4. Release packaging

Later (enhanced features):

1. GUI config tool
2. GPU telemetry
3. CPU frequency control

Testing Strategy

• Unit tests: For each new module/function
• Manual tests: Use tests_mqtt.md checklist
• Integration tests: After Phase 3
• Platform tests: Test on real Linux/Windows systems
• Load tests: Multiple devices, high-frequency telemetry

Success Metrics

• ✅ Phase 1 complete: All v1 features reimplemented
• ✅ Phase 2 complete: Windows fully supported
• ✅ Phase 3 complete: Production deployment successful
• ✅ Phase 4 complete: Enhanced user experience
• ✅ Phase 5 complete: Enterprise-ready security

Resources

• Architecture
• Implementation Status
• Deployment Guide
• Testing Guide
• Usage Guide

Getting Help

• Check existing code patterns in similar modules
• Refer to CLAUDE.md for development commands
• Run tests frequently: cargo test
• Use dry-run mode: features.commands.dry_run: true