gilles/pilot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
pilot/analyse_version_1.md
Gilles Soulier c5381b7112 Pilot v2: Core implementation + battery telemetry 
Major updates:
- Complete Rust rewrite (pilot-v2/) with working MQTT client
- Fixed MQTT event loop deadlock (background task pattern)
- Battery telemetry for Linux (auto-detected via /sys/class/power_supply)
- Home Assistant auto-discovery for all sensors and switches
- Comprehensive documentation (AVANCEMENT.md, CLAUDE.md, roadmap)
- Docker test environment with Mosquitto broker
- Helper scripts for development and testing

Features working:
✅ MQTT connectivity with LWT
✅ YAML configuration with validation
✅ Telemetry: CPU, memory, IP, battery (Linux)
✅ Commands: shutdown, reboot, sleep, screen (dry-run tested)
✅ HA discovery and integration
✅ Allowlist and cooldown protection

Ready for testing on real hardware.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-30 06:23:00 +01:00

121 lines
7.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 2.1 Résumé exécutif
- Objectif de l’app : exposer via MQTT (Home Assistant autodiscovery) des entites de telemetrie PC + commandes (shutdown, reboot, ecran, CPU freq).
- OS supportes : Linux (systemd, sudo, /sys, busctl GNOME). Windows : Non trouve.
- Dependances majeures : Python, paho-mqtt, psutil, pynvml.
- Mode d’execution : script Python en CLI, ou service systemd via `mqtt_pilot.service`.
## 2.2 Architecture
Diagramme textuel (ASCII) :
[systemd service] -> [main_prog.py/main.py] -> [paho-mqtt client] -> [MQTT broker]
|-> [psutil/pynvml] (telemetrie)
|-> [subprocess/busctl/sudo] (actions)
Points d’entree, modules, flux de donnees :
- Points d’entree : `main.py`, `main_prog.py`, `main-lenovo-bureau.py` (variantes), service systemd via `mqtt_pilot.service` -> `main_prog.py`.
- MQTT : publication d’entites Home Assistant (discovery + availability) + publication d’etats capteurs.
- Actions systeme : shutdown, reboot, extinction/allumage ecran, changement de frequence CPU.
## 2.3 MQTT
### 2.3.1 Connexion
- Broker : 10.0.0.3:1883
- Auth : username/password vides (Non trouve pour TLS)
- TLS : Non trouve
- client_id : non defini (paho-mqtt genere un ID)
- keepalive : 60
- LWT : Non trouve (availability publie manuellement)
### 2.3.2 Topics
Le projet contient plusieurs variantes avec topics differents (noms d’hote ou `device_name`).
Tableau (main_prog.py - device_name = "yoga14") :
Topic | Direction | QoS | Retain | Payload | Action/usage
- `homeassistant/switch/yoga14/shutdown_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery switch shutdown
- `homeassistant/switch/yoga14/reboot_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery switch reboot
- `homeassistant/switch/yoga14/screen_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery switch ecran
- `homeassistant/sensor/yoga14/battery_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery batterie
- `homeassistant/binary_sensor/yoga14/charging_status_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery charge
- `homeassistant/sensor/yoga14/cpu_temperature_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery temp CPU
- `homeassistant/sensor/yoga14/cpu_usage_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery usage CPU
- `homeassistant/sensor/yoga14/memory_usage_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery usage RAM
- `homeassistant/sensor/yoga14/cpu_frequency_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery freq CPU
- `homeassistant/sensor/yoga14/ip_address_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery IP
- `homeassistant/number/yoga14/cpu_frequency_slider_yoga14/config` | out | defaut | true | JSON discovery | autodiscovery slider freq
- `pilot/yoga14/shutdown/set` | in | defaut | - | "ON"/"OFF" | OFF -> shutdown
- `pilot/yoga14/reboot/set` | in | defaut | - | "ON"/"OFF" | OFF -> reboot
- `pilot/yoga14/screen/set` | in | defaut | - | "ON"/"OFF" | OFF/ON -> busctl display
- `pilot/yoga14/cpu_frequency_slider/set` | in | defaut | - | "<float>" GHz | set freq CPU
- `pilot/yoga14/*/state` | out | defaut | true | valeurs numeriques/strings | etats capteurs/switch
- `pilot/yoga14/*/available` | out | defaut | true | online/offline | availability
Tableau (main.py / main-lenovo-bureau.py - hostname dynamique) :
- `homeassistant/switch/<hostname>/shutdown_<hostname>/config` | out | defaut | true | JSON discovery | autodiscovery shutdown
- `homeassistant/sensor/<hostname>/cpu_temp_<hostname>/config` | out | defaut | true | JSON discovery | autodiscovery CPU temp
- `homeassistant/sensor/<hostname>/memory_used_<hostname>/config` | out | defaut | true | JSON discovery | autodiscovery RAM used
- `homeassistant/sensor/<hostname>/cpu_usage_<hostname>/config` | out | defaut | true | JSON discovery | autodiscovery CPU usage
- `homeassistant/sensor/<hostname>/gpu_temp_<hostname>/config` | out | defaut | true | JSON discovery | autodiscovery GPU temp (main.py)
- `homeassistant/sensor/<hostname>/gpu_memory_usage_<hostname>/config` | out | defaut | true | JSON discovery | autodiscovery GPU mem (main.py)
- `pilot/<hostname>/shutdown/available` | in | defaut | - | "ON"/"OFF" | OFF -> shutdown
- `pilot/<hostname>/shutdown` | out | defaut | true | "ON"/"OFF" | etat switch
- `pilot/<hostname>/<sensor>` | out | defaut | true | valeurs numeriques | capteurs
- `pilot/<hostname>/<sensor>/available` | out | defaut | true | online/offline | availability
### 2.3.3 Commandes supportees
- Shutdown : payload "OFF" sur `pilot/<device>/shutdown/set` (main_prog.py) ou `pilot/<hostname>/shutdown/available` (main.py / main-lenovo-bureau.py).
- Reboot : payload "OFF" sur `pilot/<device>/reboot/set` (main_prog.py).
- Ecran on/off : payload "ON"/"OFF" sur `pilot/<device>/screen/set` (main_prog.py).
- Slider frequence CPU : payload float en GHz sur `pilot/<device>/cpu_frequency_slider/set`.
- Telemetrie : batterie, charge, CPU temp/usage/freq, RAM, IP, GPU temp, GPU mem (selon variante).
## 2.4 Commandes systeme executees
- Shutdown : `sudo shutdown -h now`
- Reboot : `sudo reboot`
- Ecran : `busctl --user set-property org.gnome.Mutter.DisplayConfig ... PowerSaveMode i 1/0`
- CPU freq : ecriture dans `/sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed`
Risques securite + mitigations actuelles :
- Risques : execution de commandes privilegiees via MQTT sans validation, topics previsibles, pas d’auth/TLS.
- Mitigations : aucune au niveau code; README recommande `sudoers` NOPASSWD.
## 2.5 Configuration
Sources : hardcode dans scripts Python.
Parametres et defaults (tableau) :
- mqtt_broker_ip_address : 10.0.0.3
- mqtt_port : 1883
- mqtt_username/mqtt_password : ""
- discovery_prefix : homeassistant
- device_name / hostname : "yoga14" ou hostname systeme
- update_interval : multiples (5/10/20/60) selon entite
Secrets : Non trouve (pas de gestion de secrets, valeurs en clair).
## 2.6 Stockage / etat
- Pas de base de donnees ni fichiers d’etat.
- Etat publie via MQTT, souvent en retained (availability + states).
- Persistence : non (hors retained MQTT).
## 2.7 Deploiement actuel
- Installer : venv python + `pip install -r requirements.txt`.
- Lancer : `python3 main.py` ou `python3 main_prog.py`.
- Service : `mqtt_pilot.service` + `install.sh` (systemd).
- Update : Non trouve (pas de script d’update).
- Rollback : Non trouve.
## 2.8 Points faibles / dettes techniques
- P0 : Pas d’auth/TLS MQTT; commandes privilegiees sans validation; allowlist absente.
- P1 : Config hardcodee (broker, topics, device_name); duplication de code entre scripts.
- P1 : Availability publiee en boucle sans LWT; pas de QoS/retours d’erreurs robustes.
- P2 : Pas de tests, pas de logs structurels, pas de packaging.
- P2 : Compatibilite Windows non traitee; dependances GPU/psutil non verifiees.
Elements manquants / non trouves :
- Fichier de configuration externe (.env/yaml/json).
- TLS, ACL broker, signature de messages.
- Definition formelle de schema de payload.
## 2.9 Suggestions de refonte (sans coder)
- Quick wins : centraliser config (env/yaml), ajouter LWT + heartbeat, factoriser modules MQTT/sensors/commands.
- Architecture cible probable : core MQTT + module commands + module sensors + config + logging; separation OS (Linux/Windows).
- Axes securite : auth/TLS broker, allowlist commandes, validation payloads, limitation topics, journalisation des actions.
Reference in New Issue View Git Blame Copy Permalink