# Télécommande LED chambre — Home Assistant

## Objectif

Permettre à ma fille de piloter le ruban LED de sa chambre depuis son lecteur MP3 Android, via une page web ultra simple, **sans lui donner accès au reste de Home Assistant**.

## Matériel

- Ruban LED **RGB non adressable** : toute la longueur affiche la même couleur. Aucun effet de « vague » spatiale n'est possible, seulement des effets globaux (cycles, fondus, respiration).
- Driver **Zigbee Iderwel** (PWM), intégré à Home Assistant.
- **Dépôt public** : aucune valeur réelle (IP, ID du webhook, entité, prénom, identifiant Android) dans les fichiers versionnés. Elles sont dans `config.local.env` (non versionné, modèle : `config.example.env`). Les fichiers versionnés sont des modèles avec des marqueurs `__HA_IP__`, `__HA_PORT__`, `__WEBHOOK_ID__`, `__ENTITE__`, `__PRENOM__` ; `deploy.sh` génère `dist/` et déploie, `android/build.sh` génère `Config.java` et la config réseau. Ne jamais réintroduire de valeur réelle dans un fichier versionné.
- entity_id du ruban : `ENTITE` dans `config.local.env` (mode couleur `xy` ; `hs_color` accepté, converti par HA)
- intégration Zigbee : **Zigbee2MQTT**
- HA : HAOS sur Odroid N2, adresse `HA_IP:HA_PORT` ; accès SSH via l'alias `SSH_HOST` (**root** : lecture seule par défaut). Jeton HA de dev dans `.env` (non versionné).
- **Effets natifs du driver (`colorloop`, `breathe`…) peu fiables** : testés, ne pas les utiliser. Les effets passent par des scripts HA. Couleurs fixes, luminosité et `transition` fonctionnent bien.
- Le driver ne remonte pas l'attribut `effect` (toujours `None` dans HA).
- MP3 : **Fanvace M36, Android 13**, écran 640×1136 à 300 dpi (≈ 341 px CSS de large), WebView 108. Branché en ADB.
- **Pas de navigateur accessible** (app lock) : la page est affichée par un mini APK WebView (`android/`, code dans le paquet `app.lumiere`, identifiant installé = `APP_ID` appliqué via `--rename-manifest-package`), qui n'autorise que `http://HA_IP:HA_PORT/local/led/`. Recompiler avec `android/build.sh` (clé de debug `~/.android/debug.keystore` : garder la même pour les mises à jour), installer avec `adb install -r android/build/ma-lumiere.apk`. Si l'IP de HA change : modifier `config.local.env`, recompiler et réinstaller.

## Architecture

```
[Page HTML statique]  --POST JSON-->  [Webhook HA (local_only)]  -->  [Automatisation]  -->  light.* / scripts d'effets
 /config/www/led/          /api/webhook/<id>
 servie sur /local/led/
```

1. **Scripts d'effets** (`script.led_<nom>`) : boucles infinies (`repeat: while true`) de `light.turn_on` avec `transition`, en `mode: restart`.
2. **Automatisation webhook** : point d'entrée unique, qui ne peut agir que sur le ruban et sur une liste fermée de scripts.
3. **Page web** : gros boutons, aucune authentification, à ajouter sur l'écran d'accueil du MP3.

## Contrat du webhook (corps JSON)

| action       | champs                   | effet                                                           |
|--------------|--------------------------|-----------------------------------------------------------------|
| `off`        | —                        | arrête tous les effets et éteint le ruban (transition 1 s)      |
| `couleur`    | `teinte` (0–359)         | arrête les effets, couleur fixe `hs_color: [teinte, 100]`       |
| `luminosite` | `valeur` (5–100)         | `brightness_pct`, valeur bornée côté HA                         |
| `effet`      | `nom` (ex. `arc_en_ciel`) | arrête l'effet en cours et lance `script.led_<nom>` s'il figure dans la liste blanche |

## Contraintes et règles

- **Sécurité**
  - Webhook en `local_only: true` et `allowed_methods: [POST]`, avec un ID aléatoire long.
  - Liste blanche stricte des scripts dans l'automatisation ; ne jamais construire un entity_id arbitraire à partir du JSON.
  - Toutes les valeurs numériques sont bornées et ont un `default` côté HA.
  - Aucun jeton HA dans la page.
- **Zigbee** : ne pas inonder le réseau. Garder au moins 1 s entre deux commandes dans les scripts (idéalement 2–3 s avec `transition` égale au delay). Les fondus sont lissés par le driver.
- **Effets** : lancer un nouvel effet ou une couleur fixe arrête toujours l'effet en cours.
- **Pas de retour d'état** : le webhook ne renvoie rien. La page ne connaît pas l'état du ruban et l'UI ne doit pas faire semblant de le connaître (pas de toggle on/off avec un état affiché).
- **Page web**
  - Un seul fichier HTML autonome (CSS et JS inline), sans dépendance externe ni CDN.
  - JS compatible avec un vieux navigateur Android : ES5 de préférence, ou au minimum sans syntaxe récente (`?.`, `??`, etc.). Utiliser `fetch` s'il est disponible, sinon `XMLHttpRequest`.
  - Pensée pour un petit écran tactile en portrait : grandes cibles tactiles, peu de texte, très visuelle (pastilles de couleur, icônes d'effets), retour visuel immédiat au tap.
  - Balises `<meta name="viewport">` et `apple-mobile-web-app` / `manifest` minimal pour que le raccourci sur l'écran d'accueil ressemble à une appli.
  - Interface en français, pour une enfant.

## Effets (en place dans `packages/led_chambre.yaml`)

- Calmes (≥ 2 s entre commandes) : `arc_en_ciel` (pas de 30°, 3 s), `respiration` (10 ↔ 100 %, 3 s), `coucher_de_soleil` (5 s), `ocean` (4 s), `veilleuse` (orange 5 %, extinction en fondu après 30 min).
- Boum (1 commande/s, le minimum) : `disco` (sauts de couleur), `boum` (flash 100 % puis fondu à 25 %), `tourbillon` (arc-en-ciel rapide). Pas de stroboscope.
- Le webhook remet 100 % quand on sort d'un effet qui baisse la luminosité (veilleuse, respiration, boum) ou quand le ruban est éteint.
- Piège : dans une palette en `variables`, une teinte `0` arrive vide dans `hs_color` et fait planter le script → utiliser `360` pour le rouge.
- Ajouter un effet = script `led_<nom>` + entrée dans `effets` et `tous_les_effets` de l'automatisation + tuile dans la page ; déployer avec `./deploy.sh` (copie, `ha core check`, `script.reload` / `automation.reload`, pas de redémarrage).

## Livrables attendus

1. `scripts.yaml` : les scripts d'effets
2. `automations.yaml` : l'automatisation webhook (ou un package `packages/led_chambre.yaml` regroupant les deux)
3. `www/led/index.html` : la page
4. Procédure de test :
   - `curl -X POST -H "Content-Type: application/json" -d '{"action":"effet","nom":"arc_en_ciel"}' http://<ha>:8123/api/webhook/<id>`
   - tester chaque action avec curl **avant** de toucher à la page
5. APK « Ma lumière » (`android/`) installé via ADB, à autoriser dans l'app lock

## Ordre de travail

1. Scripts d'effets, testés depuis Outils de développement → Actions
2. Automatisation webhook, testée avec curl
3. Page web, testée d'abord sur desktop en vue mobile, puis sur le MP3