docs(home-assistant): documenter l'intégration présence Home Assistant
Guide complet de configuration de l'intégration Home Assistant avec l'API REST de présence : prérequis, secrets, rest_command, zones, automatisations et dépannage. Co-authored-by: OpenAI/GPT-5.6-Luna-Pro <vibecoder@antoineve.me>
This commit is contained in:
143
docs/home-assistant.md
Normal file
143
docs/home-assistant.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Documentation Home Assistant (Intégration Présence)
|
||||
|
||||
Ce document fournit le guide complet et exact pour configurer une intégration Home Assistant avec l'API REST de présence du **Tableau de bord pro**. L'automatisation s'appuie sur le suivi d'une entité de type `person` et d'une zone géographique dédiée pour enregistrer automatiquement les arrivées et départs sur le lieu de travail.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prérequis
|
||||
|
||||
Avant de configurer les automatisations dans Home Assistant, assurez-vous des éléments suivants :
|
||||
|
||||
1. **Zone géographique** : Home Assistant doit posséder une zone dont l'identifiant (ID) exact est `lieu_de_travail` (dans l'interface ou `zones.yaml`). Le nom de l'entité de zone doit correspondre à `zone.lieu_de_travail`.
|
||||
2. **URL HTTPS** : L'application Flask (exposée via HAProxy en production) doit être accessible par Home Assistant via une URL HTTPS valide (ex: `https://tableau-de-bord-pro.example.com/api/v1/workplace-presence`).
|
||||
3. **Jeton d'authentification (`secrets.yaml`)** : Le jeton secret (`WORKLOG_API_TOKEN`) généré pour l'API doit être stocké de manière sécurisée dans le fichier `secrets.yaml` de Home Assistant.
|
||||
4. **Vérification SSL** : L'utilisation de `verify_ssl: true` est obligatoire pour garantir la sécurité des échanges HTTPS.
|
||||
|
||||
---
|
||||
|
||||
## 2. Configuration des Secrets (`secrets.yaml`)
|
||||
|
||||
Dans le fichier `secrets.yaml` de votre instance Home Assistant, ajoutez votre jeton d'API :
|
||||
|
||||
```yaml
|
||||
worklog_api_token: "votre_jeton_api_securise_ici"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Configuration de la Commande REST (`rest_command`)
|
||||
|
||||
Déclarez la commande REST dans votre fichier `configuration.yaml` (ou dans votre fichier de configuration des commandes REST) pour permettre à Home Assistant d'effectuer les requêtes `POST` vers l'API.
|
||||
|
||||
```yaml
|
||||
rest_command:
|
||||
worklog_presence:
|
||||
url: "https://tableau-de-bord-pro.example.com/api/v1/workplace-presence"
|
||||
method: "post"
|
||||
headers:
|
||||
authorization: "Bearer !secret worklog_api_token"
|
||||
content_type: "application/json"
|
||||
payload: '{"event": "{{ event }}", "occurred_at": "{{ occurred_at }}", "idempotency_key": "{{ idempotency_key }}"}'
|
||||
verify_ssl: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Automations Home Assistant
|
||||
|
||||
Les deux automatisations ci-dessous surveillent l'entité `person.<nom>` (à adapter selon votre configuration, par exemple `person.antoine`) par rapport à la zone `zone.lieu_de_travail`.
|
||||
|
||||
### Règle d'idempotence et de cohérence temporelle :
|
||||
Pour éviter toute divergence entre l'horodatage (`occurred_at`) et la clé d'idempotence (`idempotency_key`), les automatisations utilisent des variables locales basées sur l'horodatage du déclenchement (`trigger.to_state.last_updated`). **Ne jamais utiliser `now()` de manière éclatée ou divergente** à plusieurs endroits d'un même payload.
|
||||
|
||||
---
|
||||
|
||||
### A. Automation d'Arrivée
|
||||
|
||||
Cette automatisation se déclenche lorsque la personne entre dans la zone `lieu_de_travail` (l'état passe à `lieu_de_travail`).
|
||||
|
||||
```yaml
|
||||
alias: "Travail - Enregistrer Arrivée"
|
||||
description: "Enregistre automatiquement l'arrivée sur le lieu de travail via l'API REST."
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: person.antoine
|
||||
to: "lieu_de_travail"
|
||||
action:
|
||||
- variables:
|
||||
event_timestamp: "{{ trigger.to_state.last_updated.isoformat() }}"
|
||||
idempoteno: "{{ trigger.to_state.last_updated.strftime('%Y%m%d-%H%M%S') }}"
|
||||
idempotency: "ha-arrival-{{ idempoteno }}"
|
||||
- service: rest_command.worklog_presence
|
||||
response_variable: response
|
||||
data:
|
||||
event: "arrival"
|
||||
occurred_at: "{{ event_timestamp }}"
|
||||
idempotency_key: "{{ idempotency }}"
|
||||
- choose:
|
||||
- conditions: "{{ response.status not in [200, 201] }}"
|
||||
sequence:
|
||||
- service: persistent_notification.create
|
||||
data:
|
||||
title: "Échec Arrivée - Tableau de bord pro"
|
||||
message: >
|
||||
L'enregistrement de l'arrivée a échoué (Statut HTTP : {{ response.status }}).
|
||||
Vérifiez les journaux de l'application.
|
||||
mode: single
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### B. Automation de Départ
|
||||
|
||||
Cette automatisation se déclenche lorsque la personne quitte la zone `lieu_de_travail` (l'état quitte `lieu_de_travail`, par exemple vers `not_home` ou un autre lieu).
|
||||
|
||||
```yaml
|
||||
alias: "Travail - Enregistrer Départ"
|
||||
description: "Enregistre automatiquement le départ du lieu de travail via l'API REST."
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: person.antoine
|
||||
from: "lieu_de_travail"
|
||||
action:
|
||||
- variables:
|
||||
event_timestamp: "{{ trigger.to_state.last_updated.isoformat() }}"
|
||||
idempoteno: "{{ trigger.to_state.last_updated.strftime('%Y%m%d-%H%M%S') }}"
|
||||
idempotency: "ha-departure-{{ idempoteno }}"
|
||||
- service: rest_command.worklog_presence
|
||||
response_variable: response
|
||||
data:
|
||||
event: "departure"
|
||||
occurred_at: "{{ event_timestamp }}"
|
||||
idempotency_key: "{{ idempotency }}"
|
||||
- choose:
|
||||
- conditions: "{{ response.status not in [200, 201] }}"
|
||||
sequence:
|
||||
- service: persistent_notification.create
|
||||
data:
|
||||
title: "Échec Départ - Tableau de bord pro"
|
||||
message: >
|
||||
L'enregistrement du départ a échoué (Statut HTTP : {{ response.status }}).
|
||||
Vérifiez les journaux de l'application.
|
||||
mode: single
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Gestion des Réponses et de la Sécurité
|
||||
|
||||
- **Succès (200 / 201)** : Les codes de succès sont validés silencieusement. En cas de rejeu (réseau instable), l'API renvoie un statut `200` avec le statut `"replayed"`, ce qui est géré sans erreur par l'automatisation.
|
||||
- **Erreurs et Notifications** : Si l'API renvoie un code d'erreur (`400`, `401`, `404`, `405`, `409`, `413`, `415`, `422`, `429`, `500`, `503`), une notification persistante est créée dans Home Assistant. **Le jeton d'authentification n'est jamais inclus** dans les messages de notification pour des raisons évidentes de sécurité.
|
||||
|
||||
---
|
||||
|
||||
## 6. Limites, Risques et Points de Vigilance
|
||||
|
||||
1. **Maximum d'une arrivée ouverte** : L'application métier n'autorise qu'une seule arrivée ouverte (`time_slot_id IS NULL`) simultanément. Si une arrivée précédente n'a pas été fermée (ou en cas de faux départ/réarrivée manqués), une tentative de nouvelle arrivée provoquera un conflit `409` (`ArrivalAlreadyOpenError`).
|
||||
2. **Précision GPS et Oscillations (Doublons / Faux déclenchements)** : Les capteurs de géolocalisation (GPS mobile, intégration companion app) peuvent osciller aux abords de la zone `lieu_de_travail` (mauvaise réception GPS, rebonds d'antenne). Cela peut générer des micro-entrées et sorties successives. Bien que la clé d'idempotence et la règle chronologique protègent contre les doublons stricts basés sur le même horodatage, des entrées/sorties rapprochées multiples peuvent nécessiter des corrections manuelles dans l'interface web du Tableau de bord pro.
|
||||
3. **Limitation de débit (Rate-limit)** : L'API applique une limite stricte de **30 requêtes par fenêtre de 60 secondes** par processus. En usage normal avec un unique tracker `person`, cette limite ne risque pas d'être atteinte, mais un dysfonctionnement d'automatisation en boucle pourrait déclencher un blocage `429`.
|
||||
4. **Alignement des fuseaux horaires** : Le fuseau horaire configuré dans la section `[home_assistant]` de `config.toml` (ex: `Europe/Paris`) doit être cohérent avec celui de l'instance Home Assistant pour que les conversions d'horodatages ISO 8601 avec offset (`occurred_at`) s'alignent parfaitement avec les journées de travail locales.
|
||||
5. **Disponibilité de l'API (404 / 503)** :
|
||||
- Si la section `[home_assistant]` est absente de `config.toml`, l'API renvoie `404`.
|
||||
- Si la variable d'environnement `WORKLOG_API_TOKEN` n'est pas définie sur le serveur Flask, l'API renvoie `503`.
|
||||
6. **Sécurité et Traces Administrateur** : Les administrateurs de l'instance Home Assistant ont accès aux fichiers `secrets.yaml` et aux journaux de traces (traces d'exécution des automatisations). Veillez à ne jamais consigner le jeton d'API en clair dans les messages de log personnalisés ou les notifications.
|
||||
Reference in New Issue
Block a user