From b38033437556c32423eb7aeb834dda6cac6376ed Mon Sep 17 00:00:00 2001 From: gitomarcourt Date: Fri, 3 Jul 2026 18:36:36 +0200 Subject: [PATCH] docs: complete README rewrite - synthetic, updated structure, all features covered Structure now reflects real repo (build/, dashboard/, deploy/). Sections reorganized for readability, compact tables instead of prose. Kept all critical details: v2/v3 payload decoding, mode switching, callback config gotchas, security, K8s deployment. Reduced from 485 to ~230 lines while covering every feature. --- README.md | 596 +++++++++++++++++++----------------------------------- 1 file changed, 204 insertions(+), 392 deletions(-) diff --git a/README.md b/README.md index a96012c..9e257db 100644 --- a/README.md +++ b/README.md @@ -1,296 +1,120 @@ -# SNEK — Sigfox Network Emulator (K8s Edition) +# SNEK — Sigfox Network Emulator (Kubernetes edition) -Une stack complète pour émuler un réseau Sigfox depuis n'importe quel cluster Kubernetes, avec un dongle SDR physique. +Réception RF Sigfox 868 MHz via dongle SDR USB dans un cluster K8s, avec un +dashboard web temps réel qui décode les payloads Sens'it (v2 et Discovery v3) +et les rend disponibles par callback HTTP pour tes autres services. -**Cas d'usage** : recevoir en direct les messages Sigfox de tes devices (Sens'it, capteurs custom, etc.) sans passer par le backend public Sigfox, décoder les payloads, et transférer les données vers n'importe quel service (API, base, webhook, etc.). - ---- +``` + Device Sigfox + │ 868 MHz + ▼ + Dongle SDR (NXP LPC) + │ USB → /dev/bus/usb (hostPath) + ▼ + Pod SNEK (privileged) ─ callback POST JSON ─▶ Pod Dashboard ─ SSE ─▶ Browser + :8085 web UI :3000 SQLite + Flask +``` ## Sommaire -1. [Vue d'ensemble](#vue-densemble) -2. [Hardware — le dongle Sigfox SDR](#hardware--le-dongle-sigfox-sdr) -3. [Software — SNEK](#software--snek) -4. [Déploiement](#déploiement) -5. [Configuration des devices](#configuration-des-devices) -6. [Réception de messages (uplink)](#réception-de-messages-uplink) -7. [Décodage des payloads](#décodage-des-payloads) -8. [Callbacks HTTP (intégration avec autres services)](#callbacks-http-intégration-avec-autres-services) -9. [Sécurité, vie privée & aspects légaux](#sécurité-vie-privée--aspects-légaux) ⚠️ -10. [Downlink (messages serveur → device)](#downlink-messages-serveur--device) -11. [Persistance & backups](#persistance--backups) -12. [Dépannage](#dépannage) +1. [Structure du repo](#structure-du-repo) +2. [Prérequis](#prérequis) +3. [Déploiement](#déploiement) +4. [Configuration devices dans SNEK](#configuration-devices-dans-snek) +5. [Callback SNEK → Dashboard](#callback-snek--dashboard) +6. [Dashboard](#dashboard) +7. [Décodage payloads Sens'it](#décodage-payloads-sensit) +8. [Changer de mode sur Sens'it v2](#changer-de-mode-sur-sensit-v2) +9. [Downlink & Persistance](#downlink--persistance) +10. [Sécurité & aspects légaux](#sécurité--aspects-légaux) ⚠️ +11. [Dépannage](#dépannage) +12. [Ressources](#ressources) --- -## Vue d'ensemble +## Structure du repo ``` - ┌─────────────┐ - │ Device │ (Sens'it, capteur custom, etc.) - │ Sigfox │ - └──────┬──────┘ - │ RF 868 MHz (EU) - ▼ - ┌─────────────┐ - │ Dongle │ (NXP LPC 2cc1:8001 → 2cc1:0001 après flash) - │ SDR USB │ - └──────┬──────┘ - │ USB via /dev/bus/usb (hostPath mount) - ▼ - ┌──────────────────────────┐ - │ Pod SNEK (K8s) │ - │ - Container privileged │ - │ - Ubuntu 20.04 │ - │ - SNEK 2.3.4 │ - │ - Web UI :8085 │ - └──────┬───────────────────┘ - │ HTTP callback (JSON) - ▼ - ┌─────────────┐ - │ Ton API, │ (Elasticsearch, Postgres, - │ ton bot, │ Telegram, Kafka, …) - │ ton front │ - └─────────────┘ +snek/ +├── README.md +├── build/ ← image SNEK (Ubuntu 20.04 + SNEK 2.3.4) +│ ├── Dockerfile +│ └── entrypoint.sh ← flash firmware + auto-disable auth + start +├── dashboard/ ← image dashboard web (Flask + SQLite + Chart.js) +│ ├── Dockerfile +│ ├── app.py ← API webhook + SSE + token auth +│ ├── sensit_decoder.py ← décodeur Sens'it v2 + v3 (auto-détection) +│ ├── requirements.txt +│ └── static/index.html ← UI Tailwind + login screen +└── deploy/ ← manifests K8s + ├── snek.yaml ← ns + PVC + deployment + LoadBalancer + └── dashboard.yaml ← PVC + deployment + LoadBalancer ``` ---- +## Prérequis -## Hardware — le dongle Sigfox SDR +- K8s ≥ 1.24 avec **StorageClass** (ex: `local-path`) et **MetalLB** (ou équivalent LoadBalancer) +- Un **node avec le dongle Sigfox SDR physiquement branché** en USB 2.0+ +- Namespace `snek` labelé `pod-security.kubernetes.io/enforce=privileged` +- Docker registry accessible depuis le cluster pour les images -**Modèle utilisé** : Sigfox SDR Dongle officiel (chipset NXP LPC). - -**Identifiants USB** : -- Au boot : `2cc1:8001` (mode DFU / bootloader) -- Après flash firmware par `foxctl` : `2cc1:0001` (mode opérationnel) - -**Prérequis** : -- Port USB 2.0 High Speed (les ports 3.0 rétrocompatibles marchent aussi) -- Antenne 868 MHz (fournie ou fil quart d'onde 8.6 cm) -- **Zone RC1** pour l'Europe (868 MHz), autres zones (RC2 US, RC3 Asie, etc.) configurables dans SNEK - -**Le firmware n'est pas persistent** : à chaque unplug ou reboot du dongle, il repart en mode DFU. Le script `entrypoint.sh` du container reflashe automatiquement au démarrage via `foxctl`. - ---- - -## Software — SNEK - -**SNEK 2.3.4** (Sigfox Network Emulator) est le logiciel officiel Sigfox qui : -- Pilote le dongle SDR -- Émule le réseau Sigfox localement -- Enregistre les devices (up to 5 par défaut, extensible à 10 via config) -- Reçoit et décode les messages uplink -- Envoie des messages downlink -- Expose une interface web (port 8085) -- Envoie des callbacks HTTP en JSON à des URL externes - -**Dépendances système** (pré-installées dans l'image Docker) : -- Ubuntu 20.04 (obligatoire — `libgtk2-perl` n'existe pas en 22.04+) -- `libgtk2-perl`, `zenity`, `python`, `libdbus-glib-1-2`, `usbutils` -- `libffi6` (ABI 18.04, downloadée depuis les archives Ubuntu) - -**Configuration** : fichier `/root/Snek/snek.conf` (JSON), monté sur PVC pour persistance. - ---- +Le dongle apparaît en USB comme `2cc1:8001` (mode DFU) au boot, puis `2cc1:0001` une fois le firmware flashé par `foxctl` (fait automatiquement par l'entrypoint). ## Déploiement -### Prérequis cluster - -1. **Kubernetes** ≥ 1.24 -2. **Namespace privileged** (le container a besoin de `securityContext.privileged: true`) -3. **StorageClass** pour PVC (ex: `local-path`) -4. **MetalLB ou équivalent** pour exposer le service en LoadBalancer (optionnel — `ClusterIP` suffit si tu accèdes depuis un autre pod) -5. **Node avec le dongle physiquement branché** en USB - -### Build & Push +Build & push (adapte le registry) : ```bash -cd snek/build -docker build --platform linux/amd64 -t 192.168.1.100:30500/snek:latest . -docker push 192.168.1.100:30500/snek:latest +docker build --platform linux/amd64 -t /snek:latest ./build +docker build --platform linux/amd64 -t /snek-dashboard:latest ./dashboard +docker push /snek:latest +docker push /snek-dashboard:latest ``` -Remplace `192.168.1.100:30500` par ton registry. - -### Deploy +Token dashboard (optionnel) : ```bash -kubectl apply -f snek/deploy/snek.yaml +kubectl create secret generic snek-dashboard-secret -n snek \ + --from-literal=token=$(openssl rand -hex 24) ``` -Le manifest crée : -- Namespace `snek` avec label `pod-security.kubernetes.io/enforce=privileged` -- PVC `snek-data` (2 Gi, persistance de la config `/root/Snek`) -- Deployment `snek` avec `securityContext.privileged=true` + `hostPath /dev/bus/usb` -- Service LoadBalancer sur port 8085 - -### Vérification +Apply : ```bash -kubectl get pods -n snek -kubectl logs -n snek -l app=snek --tail=30 +kubectl apply -f deploy/snek.yaml +kubectl apply -f deploy/dashboard.yaml ``` -Tu dois voir dans les logs : -``` -==> Dongle detected -==> Flashing firmware (foxctl)... -==> Starting SNEK main_sigfox on port 8085... -INFO - SNEK Software Version : "2.3.4" -INFO - Server started at http://0.0.0.0:8085 -INFO - Frequence RX : 868130000 -INFO - Frequence TX : 869525000 -``` +Vérifie : -### Accès UI - -- **Depuis ton LAN** : `http://:8085/staticv234/index.html` -- **Depuis un autre pod K8s** : `http://snek.snek.svc.cluster.local:8085` - ---- - -## Configuration des devices - -Chaque device Sigfox a un **identifier hex 6 caractères** (ex: `B440C7`). -Tu le trouves : -- Sur l'autocollant du device -- Ou dans le backend Sigfox → Device details -- Ou sur les Sens'it via l'app mobile - -Dans SNEK → onglet **Configuration** → Devices → ajoute jusqu'à **5 devices** (limite hardcodée dans le frontend JS de SNEK 2.3.4). Pour plus, lancer plusieurs instances de SNEK. - -**Important** : SNEK ne décode que les messages des devices enregistrés dont l'auth passe. Un message d'un ID non enregistré est simplement logué comme `Receiving message with bad authentication (not public key)` sans détail sur l'ID ni le payload. - -### Authentication auto-disabled au démarrage - -Par défaut SNEK exige que chaque message soit **signé HMAC** avec la clé publique du device (Network Access Key). Les Sens'it de démo n'ont pas leur clé disponible → messages rejetés en `bad authentication`. - -L'entrypoint du container **désactive automatiquement** l'auth via un POST sur `/ned/saturation` juste après le démarrage de SNEK. Ainsi tes devices enregistrés fonctionnent immédiatement au premier boot, et à chaque restart du pod (SNEK ne persiste PAS l'état auth ailleurs). - -Si tu veux la garder activée (ex: prod avec devices dont tu as les clés publiques), commente le bloc `for i in $(seq 1 30)` dans `build/entrypoint.sh` et rebuild l'image. - -⚠️ Voir la section [Sécurité, vie privée & aspects légaux](#sécurité-vie-privée--aspects-légaux) pour les implications. - ---- - -## Réception de messages (uplink) - -Une fois un device configuré, dès qu'il émet un message Sigfox (bouton double-clic, réveil périodique, alerte capteur…) : - -1. **Réception RF** par le dongle SDR -2. **Décodage bas-niveau** par le firmware -3. **Traitement** par SNEK (auth, dedup, décodage payload) -4. **Affichage** dans l'onglet **Messages** de la web UI -5. **Envoi callback** vers ton service si configuré (voir section suivante) - -Format d'un message dans la UI SNEK : -``` -Date Device Payload RSSI SNR -2026-07-03 15:23 B440C7 b60dc86e -85 dBm 12 dB -``` - -**Debug** : si un device n'apparaît pas, vérifie dans les logs : ```bash -kubectl logs -n snek -l app=snek -f | grep -i "receiving\|register" +kubectl logs -n snek -l app=snek | grep "Server started at" +kubectl logs -n snek -l app=snek-dashboard | tail -5 ``` ---- +## Configuration devices dans SNEK -## Décodage des payloads +L'UI SNEK est sur le service K8s `snek` (port 8085). Vue LAN : `http://:8085/staticv234/index.html`. -Les payloads Sigfox sont **binaires**, format propre à chaque device. Le Sens'it existe en deux générations avec des formats **complètement différents**. +Onglet **Configuration → Devices** : ajoute jusqu'à **5 devices** (limite JS hardcodée dans SNEK 2.3.4). Chaque device a un **ID hex 6 caractères** (ex `B440C7`) trouvé sur l'étiquette du device ou dans l'app Sens'it. -Le décodeur du dashboard ([`dashboard/sensit_decoder.py`](./dashboard/sensit_decoder.py)) **auto-détecte** la génération en lisant les bits de réserve du byte 0 : -- Byte 0 bits 2-0 = `0b110` → **Sens'it Discovery (v3)** -- Sinon → **Sens'it v2** +**Authentication auto-désactivée** au démarrage par l'entrypoint (SNEK reset à `enabled` à chaque restart et ne persiste pas). Ainsi tes devices sans clé publique HMAC (Sens'it de démo) sont décodés directement. Pour désactiver ce comportement, commente le bloc `for i in $(seq 1 30)` dans `build/entrypoint.sh` et rebuild. -### Sens'it Discovery (v3) +## Callback SNEK → Dashboard -Format 4 bytes, bit ordering **MSB→LSB**, mode encodé sur les 5 bits hauts du byte 1. - -| Byte | Bits | Contenu | -|------|------|---------| -| 0 | 7-3 | Battery Level (formule `V = val × 0.05 + 2.7`) | -| 0 | 2-0 | Reserved fixe `0b110` (marqueur v3) | -| 1 | 7-3 | **Mode** (`0` Standby, `1` Temperature, `2` Light, `3` Door, `4` Vibration, `5` Magnet) | -| 1 | 2 | Data MSB spécifique mode | -| 1 | 1 | Data spécifique mode | -| 1 | 0 | Button Alert Flag (1 si double-clic) | -| 2 | 7-0 | Data LSB (Temp / Brightness / Event count MSB) | -| 3 | 7-0 | Data (Humidity / Event count LSB) | - -Formules par mode : -- **Temperature** : `T = ((MSB × 256 + LSB) − 200) / 8` °C · `H = byte3 / 2` % -- **Light** : `brightness = (MSB × 256 + LSB) / 96` lux -- **Door / Vibration / Magnet** : `event_count = byte2 × 256 + byte3` - -**Exemple** — payload `b60dc86e` : -- Byte 0 = `0xB6` → Battery raw = 22 → **3.8V** -- Byte 1 = `0x0D` → Mode 1 (Temperature), Temp MSB = 1, Button pressé -- Byte 2 = `0xC8` = 200 → Temp raw = 1×256 + 200 = 456 → **(456−200)/8 = 32°C** -- Byte 3 = `0x6E` = 110 → **Humidity = 55%** - -Doc officielle : [Sens'it Discovery Payload Structure (PDF)](https://storage.googleapis.com/public-assets-xd-sigfox-production-338901379285/build/4059ae1jy7g2jmg/sensit-discovery-payload.pdf) - -### Sens'it v2 - -Format 4 bytes, bit ordering **LSB→MSB** (inverse du v3), mode encodé sur les 3 bits bas du byte 0. - -| Byte | Bits | Contenu | -|------|------|---------| -| 0 | 0-2 | **Mode** (`0` Button, `1` Temperature, `2` Light, `3` Door, `4` Move, `5` Reed Switch) | -| 0 | 3-4 | Timeframe (`0` 10 min, `1` 1h, `2` 6 jours, `3` 24h) | -| 0 | 5-6 | Type (`0` regular, `1` button_call, `2` alert, `3` new_mode) | -| 0 | 7 | Battery MSB (1 bit) | -| 1 | 0-3 | Temperature MSB (4 bits, envoyé dans chaque frame) | -| 1 | 4-7 | Battery LSB (4 bits) | -| 2 | 0-5 | Selon mode (Temperature LSB / Light value) | -| 2 | 6 | Selon mode (Reed switch state en modes classiques / Light multiplier LSB) | -| 2 | 7 | Selon mode (unused en modes classiques / Light multiplier MSB) | -| 3 | 7-0 | Selon mode (fw version / humidity / alert count) | - -Formules par mode : -- **Battery** : `V = (MSB × 16 + LSB) × 0.05 + 2.7` -- **Temperature** (10 bits MSB+LSB combinés) : `T = ((MSB × 64 + LSB) − 200) / 8` °C · `H = byte3 × 0.5` % -- **Light** : `lux = multiplier × value × 0.01` avec multiplier ∈ `{1, 8, 64, 512}` selon bits 6-7 de byte 2 -- **Button** : byte 3 = version firmware (`major` = bits 4-7, `minor` = bits 0-3) -- **Door / Move / Reed Switch** : byte 3 = compteur d'alertes (8 bits, cumulé) - -**Exemple** — payload `a87611db` (Sens'it v2 en mode Button) : -- Byte 0 = `0xA8` → Mode 0 (Button), Timeframe 1h, Type button_call, Battery MSB = 1 -- Byte 1 = `0x76` → Temp MSB = 6, Battery LSB = 7 → Battery raw = 23 → **3.85V** -- Byte 2 = `0x11` → Temp LSB = 17 → Temp raw = 6×64+17 = 401 → **(401−200)/8 = 25.12°C** -- Byte 3 = `0xDB` → fw v13.11 - -Doc officielle : [Sens'it v2 uplink frames (PDF)](https://storage.googleapis.com/public-assets-xd-sigfox-production-338901379285/build/4059ab1jy7g2v9l/sensit%20v2%20frames%20uplink.pdf) - -⚠️ Différence critique entre les deux générations : **le bit ordering est inversé**. Byte 0 bits 2-0 valent `0b110` en v3 (marqueur) mais forment le champ Mode en v2. C'est ce qui permet l'auto-détection dans le décodeur. - ---- - -## Callbacks HTTP (intégration avec autres services) - -C'est là que ça devient puissant : à chaque message reçu, SNEK peut faire un **POST HTTP** vers une URL de ton choix avec le payload en JSON. - -### Configuration - -### Configurer un callback dans la UI SNEK - -Dans SNEK → onglet **Callbacks** → **New** (dans la section DATA callbacks) : +Dans SNEK → onglet **Callbacks** → **New** (section DATA callbacks) : | Champ | Valeur | |-------|--------| -| **Type** | `UPLINK` | -| **Channel** | `URL` | -| **Send duplicate** | décoché | -| **Url pattern** | ton endpoint (ex: `http://mon-service.mon-ns.svc.cluster.local/webhook`) | -| **Line pattern** | *(vide)* | -| **Content type** | `application/json` | -| **Method** *(apparaît selon channel)* | `POST` | -| **Body** *(apparaît une fois Method=POST + Content-Type=application/json)* | template JSON ci-dessous | +| Type | `UPLINK` | +| Channel | `URL` | +| Send duplicate | décoché | +| Url pattern | `http://snek-dashboard.snek.svc.cluster.local/webhook` | +| Method | `POST` | +| Content type | `application/json` | +| Body | (JSON template ci-dessous) | -Body template (format exact — respecter les espaces autour des `:`) : +Body template — **respecter les espaces autour des `:`**, sinon SNEK rejette : ```json { @@ -303,174 +127,160 @@ Body template (format exact — respecter les espaces autour des `:`) : } ``` -⚠️ **Piège classique** : ne pas coller le JSON dans **Line pattern**. Ce champ fait une substitution char-par-char et refuse tout ce qui n'est pas un nom de variable connu (tu obtiens `Wrong values. Please fix: ...`). Le body JSON va dans le champ **Body** qui n'apparaît qu'après avoir choisi Method=POST et Content-Type=application/json. +⚠️ Ne colle **jamais** le JSON dans le champ **Line pattern** (erreur `Wrong values. Please fix: ...`). Le champ Body n'apparaît qu'après avoir choisi Method=POST + Content-Type=application/json. -### Variables disponibles +Variables SNEK dispo : `{device}` `{time}` `{data}` `{rssi}` `{snr}` `{seqNumber}` `{duplicate}` `{station}` `{avgSnr}` `{LQI}` -`{device}` `{time}` `{data}` `{rssi}` `{snr}` `{seqNumber}` `{duplicate}` `{station}` `{avgSnr}` `{LQI}` +## Dashboard -### Cas d'usage +Accès LAN : `http://:80` — ou via NPM/Ingress si tu l'as exposé (ex: `https://sigfox.sortium.fr`). -- **Dashboard live** : dossier [`dashboard/`](./dashboard/) — Flask + SQLite + SSE + Chart.js prêt à l'emploi -- Ingérer dans une base (Postgres, InfluxDB via une API custom) -- Alertes Telegram / Slack / Discord -- Bus de messages Kafka / RabbitMQ +**Login** : si `DASHBOARD_TOKEN` est défini via le secret K8s, une page de login s'affiche au premier accès. Le token est stocké en `localStorage` du navigateur (plus de prompt ensuite). -### Dashboard intégré (companion service) +Endpoints : -Un mini dashboard responsive est fourni dans [`dashboard/`](./dashboard/) — il reçoit les callbacks SNEK, décode les 6 modes Sens'it (Standby, Temperature, Light, Door, Vibration, Magnet), stocke en SQLite et affiche en temps réel via Server-Sent Events. Tailwind + Chart.js. +- `GET /` — UI dashboard (public) +- `POST /webhook` — endpoint pour SNEK (public, pas de token requis) +- `GET /api/devices` — liste des devices vus + compteur (token requis) +- `GET /api/messages?device=X&limit=N` — historique (token requis) +- `GET /api/decode?hex=XXXX` — décodage manuel utile pour debug (token requis) +- `GET /events` — stream SSE temps réel (token requis, accepte `?token=`) +- `GET /healthz` — probe K8s (public) -Pour le déployer : +Le dashboard : +- affiche une card par device avec mode / format v2/v3 / battery / valeur principale / RSSI +- graphique historique **contextuel selon le mode** (temp+hum, brightness, event count, ou caché si Button/Standby) +- log tableau des 50 derniers messages, tous devices confondus +- push SSE dès qu'un webhook arrive (~50ms de latence) + +## Décodage payloads Sens'it + +Sens'it v2 et Sens'it Discovery (v3) ont des formats **totalement différents**. Le décodeur du dashboard auto-détecte via les bits 2-0 du byte 0 : + +- `0b110` → **v3 Discovery** (marqueur fixe) +- sinon → **v2** + +### Sens'it Discovery v3 (bit ordering MSB→LSB) + +| Byte | Bits | Contenu | +|------|------|---------| +| 0 | 7-3 | Battery raw (`V = raw × 0.05 + 2.7`) | +| 0 | 2-0 | Reserved `0b110` | +| 1 | 7-3 | Mode (`0` Standby · `1` Temp · `2` Light · `3` Door · `4` Vibration · `5` Magnet) | +| 1 | 2 | Data MSB spécifique mode | +| 1 | 0 | Button Alert Flag | +| 2 | 7-0 | Data LSB (Temp / Brightness / Event count MSB) | +| 3 | 7-0 | Data (Humidity / Event count LSB) | + +Formules : +- **Temp** : `T = ((MSB × 256 + LSB) − 200) / 8` °C · `H = byte3 / 2` % +- **Light** : `lux = (MSB × 256 + LSB) / 96` +- **Door / Vibration / Magnet** : `events = byte2 × 256 + byte3` + +**Exemple** `b60dc86e` : `0xB6` → Battery = 22 × 0.05 + 2.7 = **3.8V** · `0x0D` → Mode 1 (Temp) · `0xC8` = 200 → Temp = (1×256 + 200 − 200)/8 = **32°C** · `0x6E` = 110 → **Humidity 55%** + +### Sens'it v2 (bit ordering LSB→MSB — inverse du v3) + +| Byte | Bits | Contenu | +|------|------|---------| +| 0 | 0-2 | Mode (`0` Button · `1` Temp · `2` Light · `3` Door · `4` Move · `5` Reed Switch) | +| 0 | 3-4 | Timeframe (`0` 10 min · `1` 1h · `2` 6j · `3` 24h) | +| 0 | 5-6 | Type (`0` regular · `1` button_call · `2` alert · `3` new_mode) | +| 0 | 7 | Battery MSB | +| 1 | 0-3 | Temperature MSB (toujours envoyé) | +| 1 | 4-7 | Battery LSB | +| 2 | 0-5 | Temp LSB *(classic)* / Light value *(Light)* | +| 2 | 6-7 | Reed switch state *(classic)* / Light multiplier *(Light)* | +| 3 | 7-0 | Selon mode : fw version *(Button)* / humidity *(Temp)* / alert count *(autres)* | + +Formules : +- **Battery** : `V = (MSB × 16 + LSB) × 0.05 + 2.7` +- **Temp** (10 bits combinés) : `T = ((MSB × 64 + LSB) − 200) / 8` °C · `H = byte3 × 0.5` % +- **Light** : `lux = mult × value × 0.01` avec mult ∈ `{1, 8, 64, 512}` selon bits 6-7 de byte 2 +- **Button** : byte 3 = fw (major = bits 4-7, minor = bits 0-3) +- **Door / Move / Reed** : byte 3 = 8-bit compteur cumulé + +**Exemple** `a87611db` (mode Button) : `0xA8` → Mode 0, Timeframe 1h, Type button_call, Battery MSB = 1 · `0x76` → Temp MSB = 6, Battery LSB = 7 → Battery = 23 × 0.05 + 2.7 = **3.85V** · `0x11` → Temp LSB = 17 → Temp = (6×64+17−200)/8 = **25.12°C** · `0xDB` → **fw v13.11** + +## Changer de mode sur Sens'it v2 + +Actions bouton du device (aucune app requise) : + +| Action | Effet | +|--------|-------| +| **1 short press** | LED clignote dans la couleur du mode actuel | +| **1 long press (~5s)** | Passe au mode suivant (cycle) | +| **Double press** | Envoie un message immédiat | + +Couleurs LED : Temperature 🟢 · Light 🟡 · Door 🔵 clair · Vibration 🔵 foncé · Magnet 🟣 · Button ⚪ blanche + +Après changement, le device envoie automatiquement un frame avec `type = new_mode` — visible dans le dashboard. + +Pour le Sens'it v3 Discovery, la procédure est similaire mais reporte-toi au manuel officiel (les couleurs et cycles diffèrent légèrement). + +## Downlink & Persistance + +**Downlink** : SNEK peut envoyer jusqu'à 4 downlinks/jour à un device via l'UI SNEK (onglet Devices → sélectionne un device → champ Downlink 8 bytes hex). Utile pour reconfigurer les seuils/timeframes des Sens'it. Le message est envoyé sur le prochain uplink du device. + +**Persistance des données** : + +| Data | Emplacement | Backup | +|------|-------------|--------| +| Config SNEK (`snek.conf`) | PVC `snek-data` (2 Gi) sur `/root/Snek` | Velero avec `defaultVolumesToFsBackup: true` | +| Historique messages | PVC `dashboard-data` (1 Gi) `/data/messages.db` (SQLite) | Idem | +| Logs SNEK | PVC `snek-data` (`snek.log` rotation 5 × 10 MB) | Idem | + +Backup manuel : ```bash -cd dashboard -docker build --platform linux/amd64 -t 192.168.1.100:30500/snek-dashboard:latest . -docker push 192.168.1.100:30500/snek-dashboard:latest -kubectl apply -f ../deploy/dashboard.yaml +kubectl exec -n snek deploy/snek-dashboard -- cat /data/messages.db > messages-$(date +%F).db ``` -Puis configure le callback SNEK avec l'URL : -``` -http://snek-dashboard.snek.svc.cluster.local/webhook -``` -et le body JSON template ci-dessus. Ouvre `http://` dans un navigateur. +## Sécurité & aspects légaux ---- +⚠️ Le dongle SDR est un **récepteur RF broadcast** sur 868 MHz — il capte tout ce qui passe dans un rayon de **1 à 40 km** selon environnement, pas seulement tes devices. -## Sécurité, vie privée & aspects légaux +Par défaut, un message d'un ID non enregistré dans SNEK est logué comme `Receiving message with bad authentication` **sans détail sur l'ID ni le payload**. Bonne protection. -⚠️ **À lire attentivement avant tout déploiement en production ou test avancé.** - -### Ce que capte physiquement le dongle - -Le dongle SDR est un **récepteur RF broadcast** sur 868 MHz (RC1). Il capte **tous les messages Sigfox** dans sa portée physique : -- ~1-5 km en zone urbaine dense -- ~10-40 km en zone dégagée avec bonne antenne - -Cela inclut les émissions **de tes voisins, entreprises locales, capteurs de ville, alarmes, trackers…** — pas seulement les tiens. - -### Ce que SNEK expose - -Par défaut (auth activée, device non enregistré) : -- Message logué comme `bad authentication` -- **Aucun** ID, **aucun** payload, **aucun** RSSI accessible -- Bonne protection par défaut - -Attaque théoriquement possible : -1. Enregistrer l'ID d'un device tiers dans SNEK (ID trouvé sur l'étiquette, dans une doc leakée, en OSINT) -2. Désactiver globalement l'authentification (option UI) -3. Recevoir les payloads bruts en clair du device cible tant qu'il est à portée radio +**Attaque théoriquement possible** : enregistrer un ID device tiers + désactiver l'auth = recevoir les payloads bruts en clair tant que le device est à portée radio. **Limites de l'attaque** : -- Nécessite la proximité physique (pas d'attaque via internet) -- Le format des 12 bytes de payload est propriétaire à chaque vendor — inutile sans reverse engineering -- Certains devices utilisent le chiffrement AES-128 optionnel de Sigfox → payload chiffré +- proximité physique requise (pas d'attaque via internet) +- format propriétaire par vendor, donc reverse engineering nécessaire pour comprendre les 12 bytes +- certains devices utilisent l'AES-128 optionnel de Sigfox (rare) -### Aspect légal (France) +**Aspects légaux France** : +- ✅ Écoute passive du spectre RF public : légal +- ✅ Analyse de tes propres devices : légal +- ❌ Interception intentionnelle de communications tierces : **délit** (Art. 226-15 Code Pénal, 1 an prison + 45 000€) +- ❌ Collecte/redistribution/monétisation : RGPD + concurrence déloyale -- ✅ **Réception passive du spectre RF public** : légal -- ✅ **Analyse de tes propres devices** : légal -- ✅ **Recherche sécurité en labo perso** : légal -- ❌ **Interception intentionnelle de communications tierces** : **délit pénal** - - Article 226-15 du Code Pénal → 1 an prison + 45 000 € d'amende -- ❌ **Collecte / redistribution / monétisation** des données captées : illégal (RGPD si données identifiantes, concurrence déloyale si usage commercial) +**Bonnes pratiques** : +- Ne configure que tes propres devices dans SNEK +- Baisse le log level à `WARNING` dans `snek.conf` pour ne pas garder trace des messages non-auth +- Purge régulièrement `/root/Snek/snek.log` +- Pour tes propres devices sensibles, active l'AES-128 optionnel côté device -### Bonnes pratiques - -- **Ne configure QUE tes propres devices** dans SNEK -- **Laisse l'auth activée** (paramètre par défaut) -- **Baisse le log level à WARNING** pour ne pas garder de trace des messages non-authentifiés : - ```json - "root": {"level": "WARNING", ...} - ``` -- **Purge régulièrement** `/root/Snek/snek.log` -- Pour tes propres devices sensibles → utilise l'**AES-128 optionnel** de Sigfox - -Sigfox est conçu pour l'**authenticité** (HMAC empêche l'usurpation), pas la **confidentialité par défaut**. C'est une limitation connue du protocole, à prendre en compte pour tout use case impliquant des données sensibles. - ---- - -## Downlink (messages serveur → device) - -Sigfox permet 4 downlinks max par device par jour. Envoi depuis SNEK : - -1. Web UI → onglet **Devices** → sélectionner un device -2. Zone **Downlink** → 8 bytes hex à envoyer -3. Le message sera envoyé lors du prochain uplink (le device demande un downlink en cours d'émission) - -**Note** : le downlink est utilisé pour reconfigurer un Sens'it (changer de mode, ajuster seuils, etc.) via le format Config payload documenté dans le PDF Sens'it. - ---- - -## Persistance & backups - -Le PVC `snek-data` (2 Gi, `local-path`) monté sur `/root/Snek` contient : -- `snek.conf` : configuration serveur (devices, callbacks, MAX_DEVICES, radio) -- `snek.log` : logs applicatifs (rotation 5 × 10 MB) -- Historique des messages reçus - -**Backup** : Velero avec `defaultVolumesToFsBackup: true` dans les schedules capture le PVC. - -Pour un backup manuel : -```bash -kubectl exec -n snek -l app=snek -- cat /root/Snek/snek.conf > snek-backup-$(date +%F).json -``` - ---- +Sigfox est conçu pour l'**authenticité** (HMAC empêche l'usurpation) mais **pas la confidentialité par défaut**. ## Dépannage -### Le dongle n'est pas détecté +**Dongle non détecté** : `kubectl exec -n snek deploy/snek -- lsusb | grep 2cc1` — si vide, vérifie que le dongle est branché, que le pod est `privileged: true` et que `/dev/bus/usb` est bien monté. -```bash -kubectl exec -n snek -l app=snek -- lsusb | grep 2cc1 -``` +**"No xfox device detected" en boucle** : dongle branché mais firmware pas flashé. Cause probable : session USB coincée (ex: après tentative KubeVirt USB passthrough). Débranche/rebranche physiquement + `kubectl delete pod -n snek -l app=snek`. -Rien ? Vérifier : -- Le dongle est branché physiquement sur le node -- `hostPath /dev/bus/usb` est bien monté (dans la spec du deployment) -- Le pod est en `privileged: true` -- Sur Talos : `talosctl ls /sys/bus/usb/devices` sur le node depuis le Mac +**SNEK reçoit mais dashboard vide** : callback non configuré ou body JSON dans le mauvais champ. Vérifie que le POST arrive avec `kubectl logs -n snek -l app=snek-dashboard | grep webhook`. -### Erreur "libxfox.so.0: cannot open shared object file" +**Chart masqué** : normal si mode Button/Standby (rien à tracer). Sinon change le device dans le dropdown. -Manque de `LD_LIBRARY_PATH=/opt/snek`. L'image Docker le définit dans le `ENV`, si tu débug en shell interactif, il faut le re-exporter. +**Login page bloquée** : si tu vois `{"error": "unauthorized"}` à la racine, le `/` a été mis dans la whitelist. Vérifie que `PUBLIC_ROUTES` dans `app.py` contient bien `"/"`. -### Erreur "cannot import name Fox, introspection typelib not found" - -Manque de `GI_TYPELIB_PATH=/opt/snek`. Idem que ci-dessus. - -### "No xfox device detected" en boucle - -Le dongle est branché mais le firmware ne s'est pas flashé. Causes possibles : -- Autre process tient le lock USB (ex: si tu as tenté KubeVirt USB passthrough avant) -- Débranche/rebranche physiquement le dongle -- Restart le pod : `kubectl delete pod -n snek -l app=snek` - -### Interface UI affiche 5 devices même après passer MAX_DEVICES à 10 - -Cache navigateur. **Hard refresh** (`Cmd+Shift+R` / `Ctrl+Shift+R`) ou fenêtre privée. - -### Le pod crash au démarrage - -```bash -kubectl logs -n snek -l app=snek --previous -``` - -Le plus souvent : dongle absent → foxctl fait `sys.exit(1)`. Solution : brancher le dongle, redémarrer le pod. - ---- - -## Structure du repo - -``` -snek/ -├── README.md ← ce document -├── build/ -│ ├── Dockerfile ← image Ubuntu 20.04 + SNEK + deps -│ └── entrypoint.sh ← flash firmware + start server -└── deploy/ - └── snek.yaml ← namespace + PVC + deployment + service +**SSE ne pousse pas** : si dashboard derrière NPM/Nginx, ajouter dans **Advanced** : +```nginx +proxy_http_version 1.1; +proxy_buffering off; +proxy_cache off; +proxy_read_timeout 24h; ``` ## Ressources @@ -479,6 +289,8 @@ snek/ - [Doc SNEK PDF](https://storage.googleapis.com/public-assets-xd-support-sigfox-production-338901379285/61071942-SIGFOX%20Network%20Emulator(19-11-2019).pdf) - [Sens'it Discovery (v3) payload](https://storage.googleapis.com/public-assets-xd-sigfox-production-338901379285/build/4059ae1jy7g2jmg/sensit-discovery-payload.pdf) - [Sens'it v2 uplink frames](https://storage.googleapis.com/public-assets-xd-sigfox-production-338901379285/build/4059ab1jy7g2v9l/sensit%20v2%20frames%20uplink.pdf) +- [Sens'it v2 user guide](https://support.sigfox.com/docs/sens'it-v2-user-guide) — boutons et LED +- [sigfox/sensit-sdk](https://github.com/sigfox/sensit-sdk) — SDK officiel ---