## 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.