pilot/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Pilot is an MQTT-based PC control agent for Home Assistant. It publishes system telemetry (CPU, memory, battery, IP) and exposes commands (shutdown, reboot, sleep, screen control) via MQTT. The project has two versions:

• v1 (Python): Legacy implementation in main.py, main_prog.py, main-lenovo-bureau.py
• v2 (Rust): Active rewrite in pilot-v2/ with improved architecture, unified MQTT contract, and platform abstraction

The v2 rewrite aims to fix v1's hardcoded configuration, lack of authentication/TLS, missing LWT, and OS-specific logic scattered across scripts.

Development Commands

V2 (Rust - Active Development)

# Run unit tests
cd pilot-v2 && cargo test

# Build release binary
cd pilot-v2 && cargo build --release

# Run locally (auto-creates config.yaml from example)
./scripts/run_pilot.sh

# Run in pilot-v2 directory directly
cd pilot-v2 && cargo run

V1 (Python - Legacy)

# Activate Python virtual environment
source monenv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run manually (v1)
python3 main.py

# Deactivate virtual environment
deactivate

Testing

# Send MQTT commands using helper script
python3 scripts/mqtt_send.py --device <device_name> --action shutdown --value OFF
python3 scripts/mqtt_send.py --device <device_name> --action screen --value ON

# Manual MQTT testing
# See docs/tests_mqtt.md for detailed checklist

Architecture (V2)

Module Structure

The v2 codebase follows a clean modular architecture in pilot-v2/src/:

• config/: YAML configuration loading and validation
• mqtt/: MQTT client, connection handling, pub/sub logic
• ha/: Home Assistant discovery payload generation
• telemetry/: System metrics collection (CPU, memory, temperature, IP)
• commands/: Command parsing, allowlist validation, cooldown logic
• platform/: OS-specific backends for power and screen control
  • platform/linux/: logind/polkit, sudoers, GNOME busctl, X11 xset
  • platform/windows/: Windows service, WinAPI session
• runtime/: Main event loop orchestration (telemetry ticks, heartbeat, command handling)
• security/: Security utilities (future: auth/TLS validation)

MQTT Contract (V2)

Base topic: pilot/<device>/...

Topics:

• pilot/<device>/availability: online/offline (LWT support)
• pilot/<device>/status: JSON with version, OS, uptime, backends
• pilot/<device>/capabilities: JSON listing enabled features
• pilot/<device>/state/<name>: Sensor states (cpu_usage, memory, power_state, etc.)
• pilot/<device>/cmd/<action>/set: Command topics (shutdown, reboot, sleep, screen)

Home Assistant Discovery:

• Prefix: homeassistant
• Conforms to HA discovery spec with device_info, unique_id, state_topic, command_topic

Runtime Flow

The runtime/mod.rs:31-127 orchestrates:

1. Startup: Connect to MQTT, publish availability/status/capabilities, send HA discovery, subscribe to commands

2. Event Loop (tokio::select):

   • Telemetry tick: Read metrics from providers, publish to state/<name> topics
   • Heartbeat tick: Publish status and power_state
   • MQTT events: Handle incoming commands with cooldown and allowlist checks
   • Shutdown signal: Publish offline availability, disconnect gracefully

3. Command Handling: Parse action/value, check allowlist, enforce cooldown, execute via platform backend, publish state updates

Configuration (V2)

Config file locations (searched in order):

• Linux: /etc/pilot/config.yaml then ./config.yaml
• Windows: C:\ProgramData\Pilot\config.yaml then ./config.yaml

Example: config/config.example.yaml

Key fields:

• device.name: Device identifier (used in MQTT topics)
• mqtt: Broker connection details, QoS, retain settings
• features.telemetry: Enable/disable, interval
• features.commands: Enable/disable, cooldown, dry_run mode, allowlist
• power_backend.linux/windows: Backend selection (logind_polkit, sudoers, etc.)
• screen_backend.linux/windows: Backend selection (gnome_busctl, x11_xset, etc.)

Platform Backends

Backends are selected via config and abstracted behind traits:

• PowerControl: shutdown, reboot, sleep, hibernate
• ScreenControl: screen_on, screen_off

Linux backends require appropriate permissions:

• linux_sudoers: Requires sudoers entries for /sbin/shutdown, /sbin/reboot
• gnome_busctl: Requires active GNOME session and user DBus access

See docs/deploiement.md for permission setup details.

Documentation

Key docs in docs/:

• analyse_v1.md: V1 analysis (hardcoded config, security issues)
• architecture_v2.md: V2 architecture diagram and MQTT contract
• deploiement.md: Deployment guide (systemd service, permissions)
• tests_mqtt.md: Manual MQTT testing checklist
• utilisation.md: Usage instructions

Important Notes

• Active development is on v2 (Rust). Only fix critical bugs in v1 Python scripts.
• Dry-run mode: Set features.commands.dry_run: true in config to test without executing system commands
• Security: V1 lacks auth/TLS. V2 architecture supports it but not yet implemented.
• Testing: Always test commands in dry-run mode first. Use scripts/mqtt_send.py for manual testing.
• Systemd service: V1 uses mqtt_pilot.service, V2 will use packaging/pilot.service
• Backups: V1 backups are in backup_v1/