New async version of samsungtheframe

docs/samsungtheframeasync.md

@@ -0,0 +1,84 @@
+# SamsungTheFrameAsync
+
+Alternative asynchrone à `apps/samsungtheframe.py`. La classe reste
+`SamsungTheFrame` et utilise les mêmes entrées, sorties, consignes, événements
+de volume, services de réveil et fichier `apps/theframe_token.txt`.
+
+## Basculement manuel
+
+Dans `apps/global/homecinema.yaml`, remplacer uniquement :
+
+```yaml
+module: samsungtheframe
+```
+
+par :
+
+```yaml
+module: SamsungTheFrameAsync
+```
+
+Conserver `class: SamsungTheFrame`. Revenir au nom de module précédent pour
+restaurer l'ancienne implémentation. Ne pas lancer les deux apps simultanément :
+elles piloteraient la même TV et les mêmes capteurs. Le YAML n'a pas été modifié
+lors de l'ajout de ce module.
+
+## Fonctionnement
+
+- Les callbacks AppDaemon transmettent les demandes à la boucle asyncio et
+  retournent immédiatement, sans communication réseau avec la TV.
+- Une connexion WebSocket Art reste ouverte tant que la TV est alimentée et que
+  sa consommation dépasse le seuil. Un lecteur unique reçoit notifications et
+  réponses, corrélées par identifiant de requête.
+- `art_mode_changed`, `artmode_status`, `go_to_standby` et `wakeup` sont traités.
+  Les notifications mettent à jour les capteurs sans attendre le prochain relevé
+  de consommation. Leur disponibilité dépend du modèle et du firmware.
+- Une connexion télécommande distincte est ouverte à la première commande puis
+  réutilisée. Les commandes sont sérialisées ; une touche maintenue est relâchée
+  même si la transition est annulée.
+- Une lecture Art de secours a lieu toutes les 60 secondes. Les fluctuations de
+  consommation réveillent le moniteur sans multiplier ces lectures.
+- Une perte réseau conserve les derniers états connus. Une consommation sous
+  le seuil ou une prise explicitement éteinte confirme l'arrêt et ferme les
+  connexions. Une consommation indisponible n'est pas assimilée à un arrêt.
+- Après un échec de lecture, reconnexion avec attente progressive : 5, 10, 20,
+  40, puis 60 secondes. Les événements de consommation ne contournent pas cette
+  attente. Les transitions échouées sont revérifiées après 30 secondes.
+- Les cinq consignes sont conservées : `manual`, `art_mode`, `tv_off`, `hdmi`,
+  `power_off`. Une nouvelle consigne annule la transition précédente, y compris
+  l'attente de 5 secondes avant coupure électrique. Une commande Power échouée
+  n'est pas immédiatement rejouée : l'état est relu avant une nouvelle action.
+- Les répétitions de volume en attente expirent après une seconde ; la file est
+  limitée à huit événements. Les échecs ne sont pas rejoués.
+- À l'arrêt/rechargement, les tâches sont annulées et les connexions fermées.
+
+Les sockets utilisent `aiohttp`, déjà fourni par AppDaemon. Aucun thread de
+réseau supplémentaire n'est créé. Les seules opérations envoyées à un executor
+sont la lecture et l'écriture du petit fichier de token.
+
+## Réglages facultatifs
+
+Ces clés peuvent être ajoutées à l'app ; elles ne sont pas nécessaires au
+basculement :
+
+```yaml
+network_timeout: 2       # secondes, connexion/autorisation et requêtes TV
+reconnect_delay: 5       # attente initiale, doublée jusqu'à 60 secondes
+fallback_refresh: 60    # intervalle de lecture de secours, en secondes
+power_threshold: 35     # watts, même seuil que l'ancienne app
+```
+
+Le timeout s'applique à chaque opération, pas à une transition complète. Les
+attentes de réveil/confirmation et l'appui long Power utilisent `asyncio` et
+n'occupent pas les threads de callbacks AppDaemon.
+
+## Vérification
+
+```sh
+python -m unittest discover -s tests -p 'test_samsungtheframe_async.py' -v
+```
+
+Les tests simulent les messages et sockets TV : persistance, notifications,
+concurrence, délais, reconnexion, transitions et annulation. Ils ne contactent pas
+la TV réelle. La réception des événements et les commandes doivent encore être
+validées sur le téléviseur lors du basculement manuel.