Add the DAILY_LINK_STATE and DAILY_SIGNAL_STATE cellular analyses

Explore WEISSHORN for the cellular domain, count lost sends and
messages, grade the daily RSRP and RSRQ medians on the published
Quectel grid, and record D-031.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-13 10:48:34 +02:00
1 parent 28cbec408e
commit 91ba1bd8ef
9 files changed
+428 -15

No files matched your search

@@ -0,0 +1,85 @@
# `DAILY_LINK_STATE` : état du lien 4G jour par jour
- **Statut** : prototype en place (2026-10-13). État seul, sans verdict ; pas encore de cas annotés par l'expert.
- **Script** : premier panneau de `python3 src/cellular/all_analyses.py [CSV ou dossiers]` (défaut : `data/WEISSHORN/`), qui écrit `out/<STATION>_cellular.html` et l'ouvre.
- **Code** : `src/cellular/link_state.py` (`run()`, `day_facts()`), bibliothèque standard uniquement, sans import du projet. Les séries viennent de `common.stations.load_stations`, qui charge `link` et `last_sync` comme la liste des échantillons de l'heure (D-031).
## Question posée
Chaque jour, les envois de la station sont-ils tous arrivés, complets, avec le lien 4G actif ?
- **Lien avec la question du domaine** (`docs/cellular/domaine/point-de-depart.md`) : des données qui arrivent est le premier service de la 4G. Ici, comme pour Energy, un envoi absent peut être l'anomalie elle-même.
- **Ce que l'analyse ajoute** : elle ne dépend d'aucun seuil radio ni d'aucun historique ; elle vaut dès le premier jour d'installation, comme `DAILY_BATTERY_STATE` (D-018).
## Principe
Le collecteur écrit `link = up` quand le contexte de données du modem a une adresse IP (`get_modem_info`, `docs/aimsight/collecteur_system_info.py`), et `sync` envoie un instantané toutes les 15 minutes, un message par métrique (`cmd_sync`). Deux de ces messages partent à chaque envoi, quel que soit l'état du modem : `link` (`down` si la lecture échoue) et `last_sync` (toujours le dernier). On compte, jour par jour, les envois reçus, les messages perdus dans un envoi reçu, et la valeur de `link`.
Calcul exact, pour chaque jour UTC d ayant au moins une ligne `link` :
1. Pour chaque heure, les listes des échantillons de `link` et de `last_sync` (vides ou `None` si rien n'est arrivé).
2. `n_up`, `n_down` = nombre d'échantillons `up` et `down` du jour.
3. `n_missing` = envois entiers perdus : somme, heure par heure, de `SAMPLES_PER_HOUR` − le plus grand des deux comptes (un envoi est arrivé si l'un de ses deux messages est arrivé ; jamais négatif : un doublon ne bouche pas le trou d'une autre heure).
4. `n_messages_lost` = messages perdus dans un envoi arrivé : somme, heure par heure, de |compte `link` − compte `last_sync`|. `None` si la série `last_sync` manque.
5. `up_percent` = `n_up` / (`SAMPLES_PER_HOUR` × 24), en %.
6. L'état se lit dans cet ordre (la première condition vraie l'emporte) :
| Ordre | Condition | `state` | Lecture |
|---|---|---|---|
| 1 | moins de 24 heures dans l'export | `None` (UNKNOWN) | jour coupé par l'export : le nombre d'envois attendus n'est pas connu |
| 2 | `n_down` ≥ 1 | `DOWN` | le modem a signalé le lien coupé au moins une fois, et cet envoi est quand même arrivé (remontée différée ou autre voie) |
| 3 | `n_missing` ≥ 1 ou `n_messages_lost` ≥ 1 | `MISSING` | des envois ou des messages manquent ; la cause n'est pas établie (lien, coupure d'énergie, réception côté serveur) |
| 4 | sinon | `UP` | tous les envois sont arrivés, lien actif |
Sortie (contrat commun) : un point par jour.
- `t` = dernière heure du jour présente dans la série.
- `value` = `up_percent`, en % du temps (`None` si l'état est UNKNOWN).
- `anomaly` = `None` : état seul, sans verdict. L'état est dans `facts.state`.
- `facts` = `state`, `up_percent`, `n_up`, `n_down`, `n_missing`, `n_messages_lost`, `hours`.
## Constantes et sources
| Constante | Valeur | Source |
|---|---|---|
| `SAMPLES_PER_HOUR` | 4 | Un instantané par envoi, toutes les 15 minutes : `last_sync` et 4 échantillons par heure, WEISSHORN du 03/10 au 13/10. La cadence n'est pas dans le collecteur (`cmd_sync` est lancé de l'extérieur). |
| `HOURS_PER_DAY` | 24 | Jour UTC complet. |
## Graphique
- **En haut** : `up_percent` par jour, placé à midi UTC (D-019), un marqueur par état (couleur, symbole et légende propres ; couleurs validées par le skill dataviz).
- **Dessous** : les séries du modem, et le nombre d'instantanés `up` par heure, en barres.
## Résultats sur WEISSHORN (jeu de travail)
- 04/10 au 12/10 : `UP` les 9 jours, 96 envois sur 96, aucun message perdu (960 envois sur 960 dans `last_sync`, espacés de 900 ± 1 s).
- Contrôle du compte sur des copies modifiées en mémoire (rien d'écrit) : un message `link` ou `last_sync` retiré donne `n_messages_lost` = 1 ; les deux retirés, `n_missing` = 1 ; sans série `last_sync`, `n_messages_lost` = `None`.
- 03/10 et 13/10 : UNKNOWN, jours coupés par l'export (17 et 8 heures ; la première et la dernière heure n'ont que 2 échantillons).
- Aucun cas annoté par l'expert : l'analyse n'a pas encore vu un seul `DOWN` ni `MISSING`.
## Options écartées
| Option | Pourquoi écartée |
|---|---|
| Compter les heures où le RSRP est présent | Une heure avec 1 instantané sur 4 paraît complète ; `link` donne le compte exact. |
| Comparer toutes les métriques texte | `registration`, `network_*` et `ip` sont vides, donc pas envoyés, quand la lecture du modem échoue ou que le lien tombe : leur absence n'est pas une perte. |
| Compter les messages des métriques numériques | Moyennes horaires : le nombre de messages n'est pas dans l'export. |
| Tolérer un envoi manquant par jour | Aucune donnée pour le calibrer ; le compte reste dans `facts` pour en décider avec les cas de l'expert. |
## Limites connues
1. **Aucun incident observé** : les états `DOWN` et `MISSING` n'ont jamais été vus sur des données réelles.
2. **`MISSING` ne dit pas pourquoi** : une coupure d'énergie fait aussi manquer les envois. Le croisement avec Energy reste à faire, au plus tard dans la couleur du jour.
3. **Remontée différée inconnue** : on ne sait pas si les envois perdus pendant une coupure du lien arrivent plus tard (file Redis `aimsight:sync`). Si oui, une coupure du lien apparaît comme `DOWN` ; sinon, comme `MISSING`.
4. **Un instantané toutes les 15 minutes** : une coupure plus courte entre deux envois n'est pas vue.
5. **Le jour en cours est UNKNOWN** jusqu'à sa dernière heure.
6. **Un message `link` absent n'est pas toujours perdu en route** : si le collecteur s'arrête plus de 120 s pendant que `sync` tourne, la réponse du modem expire dans Redis et `link` n'est pas envoyé. Cela compte aussi dans `n_messages_lost`.
7. **Seuls deux messages par envoi sont comptés** : la perte d'un autre message (une mesure radio, la tension) n'est pas vue.
## Pistes
- Avec les cas de l'expert : décider si un seul envoi manquant suffit à sortir de `UP`.
- `registration` (`searching`, `denied`) pourrait expliquer un `DOWN`.
## Historique
- **2026-10-13** : création, avec le chargement des métriques texte par `common.stations` (D-031).
- **2026-10-13** : ajout de `n_messages_lost` (messages perdus dans un envoi arrivé, `link` comparé à `last_sync`), qui mène aussi à `MISSING` ; `n_missing` compte désormais un envoi comme arrivé si l'un de ses deux messages est arrivé.
@@ -0,0 +1,78 @@
# `DAILY_SIGNAL_STATE` : niveau du signal 4G jour par jour
- **Statut** : prototype en place (2026-10-13). État seul, sans verdict ; pas encore de cas annotés par l'expert.
- **Script** : deuxième et troisième panneaux de `python3 src/cellular/all_analyses.py [CSV ou dossiers]` (défaut : `data/WEISSHORN/`), qui écrit `out/<STATION>_cellular.html` et l'ouvre.
- **Code** : `src/cellular/signal_state.py` (`run()`, `day_facts()`, `grade()`), bibliothèque standard uniquement, sans import du projet.
## Question posée
Chaque jour, le signal 4G reçu est-il excellent, bon, moyen ou en limite de cellule ?
- **Lien avec la question du domaine** : un signal faible ou brouillé met le lien en danger avant qu'il ne tombe. `DAILY_LINK_STATE` dit si les données arrivent ; celle-ci dit dans quelles conditions radio.
- **Deux mesures indépendantes** : le RSRP (force du signal) et le RSRQ (part du signal utile dans tout ce qui est reçu). Sur WEISSHORN, leur corrélation horaire est de −0,03 (`docs/cellular/domaine/point-de-depart.md`) : l'une ne remplace pas l'autre.
## Principe
On classe la médiane du jour de chaque mesure sur une grille publiée, et le jour prend la pire des deux classes. Seuils absolus, choisis par l'utilisateur plutôt que la comparaison au propre passé (D-031).
Calcul exact, pour chaque jour UTC d :
1. Valeurs horaires de `rsrp_dBm` et `rsrq_dB` non vides et finies (chaque heure est la moyenne de 4 instantanés).
2. `coverage` = min(heures mesurées en RSRP, en RSRQ) / 24. Si `coverage` < `MIN_COVERAGE` : `state` = `None` (UNKNOWN).
3. `rsrp_median_dbm`, `rsrq_median_db` = médianes du jour. La médiane sur 24 h écarte les décrochages de nuit du RSRP et le cycle quotidien du RSRQ.
4. Chaque médiane prend la première classe dont elle atteint le plancher : `EXCELLENT`, `GOOD`, `MID_CELL`, sinon `CELL_EDGE` → `rsrp_class`, `rsrq_class`.
5. `state` = la pire des deux classes.
Sortie (contrat commun) : un point par jour.
- `t` = dernière heure du jour présente dans les séries.
- `value` = `rsrp_median_dbm`, en dBm (`None` si UNKNOWN).
- `anomaly` = `None` : état seul, sans verdict. L'état est dans `facts.state`.
- `facts` = `state`, les deux médianes et leurs classes, `rsrp_min_dbm` (pour voir les décrochages de nuit), `coverage`.
## Constantes et sources
| Constante | Valeur | Source |
|---|---|---|
| `RSRP_FLOORS_DBM` | −80 / −90 / −100 | Grille « RF Quality » attribuée à Quectel (modem BG96) par [KORE Wireless](https://docs.korewireless.com/supersim/cellular-module-knowledgebase/how-to-determine-good-cellular-signal-strength), « a rough guide » ; même grille sur le [wiki Teltonika](https://wiki.teltonika-networks.com/view/RSRP_and_RSRQ). |
| `RSRQ_FLOORS_DB` | −10 / −15 / −20 | Même grille. |
| `MIN_COVERAGE` | 0,8 | Repris de `DAILY_BATTERY_STATE` : 20 heures mesurées sur 24. |
- **Ce que la grille n'est pas** : ni la norme 3GPP (qui définit la mesure, pas sa qualité), ni la doc du module de la station (NimbeLink NL-SW-LTE-TC4WWG, Telit LE910C4), qui n'en publie pas à notre connaissance. D'autres éditeurs placent les seuils 10 à 20 dB plus bas (ex. « Good » de −90 à −104 dBm).
- **`CELL_EDGE` en RSRQ est inatteignable** : le collecteur plafonne la mesure à −19,5 dB (code AT 0), au-dessus du plancher de −20 dB.
## Graphique
- **En haut, deux panneaux** (un par unité : pas de double axe, skill dataviz) : la médiane du jour du RSRP en dBm, puis celle du RSRQ en dB. Les planchers de la grille sont en pointillés, la classe de la mesure en marqueurs ; l'état du jour (la pire classe) est dans le survol.
- **Dessous** : les séries du modem.
## Résultats sur WEISSHORN (jeu de travail)
- 04/10 au 12/10 : `GOOD` les 9 jours. RSRP `EXCELLENT` (médianes de −71,5 à −66,6 dBm), RSRQ `GOOD` (médianes de −14,75 à −13,25 dB).
- Le RSRQ est la mesure qui décide, et il est à 0,25 dB du plancher de `GOOD` (−14,75 dB les 05, 06 et 07/10) : un jour à peine plus chargé passerait `MID_CELL`.
- Les décrochages de nuit (RSRP minimum de −98,25 dBm le 05 et le 07/10) n'atteignent pas la médiane.
- 03/10 et 13/10 : UNKNOWN (couverture de 0,71 et 0,33, jours coupés par l'export).
## Options écartées
| Option | Pourquoi écartée |
|---|---|
| Comparer la station à son propre passé | Choix de l'utilisateur pour des seuils absolus (D-031) ; aveugle les premiers jours, et l'export ne fait que 10 jours. |
| Le minimum du jour | Déclenché par les décrochages de nuit, 6 nuits sur 10 sur WEISSHORN. |
| RSSI et BER | RSSI au plafond 220 heures sur 241 ; BER redondant avec le RSRQ (r = −0,87). |
| Un seul panneau à deux axes | Deux unités : le skill dataviz l'interdit. |
## Limites connues
1. **Grille d'un autre modem** : publiée pour le Quectel BG96, présentée comme indicative. À confirmer par l'expert ou par le fabricant du module.
2. **Le RSRQ dépend de la charge de la cellule** : son cycle quotidien (−9 dB la nuit, −16 dB le jour sur WEISSHORN) peut faire basculer la classe sans changement à la station.
3. **Moyennes horaires en dB**, puis médiane : un décrochage bref n'est pas vu.
4. **Changement de cellule non observable** : une marche de ~10 dB du RSRP peut être un changement de cellule, pas une dégradation.
5. **Aucun cas annoté par l'expert.**
## Pistes
- Quand l'historique sera long : comparer la médiane du jour au passé de la station, pour voir une dégradation lente qui reste dans la même classe.
- Une marge autour des planchers, si la classe oscille d'un jour à l'autre.
## Historique
- **2026-10-13** : création (D-031).