Module additionnel Arduino : du sketch à l'intégration continue

CLAUDE.md

@@ -108,6 +108,18 @@ Les modules additionnels sont des modules complémentaires qui peuvent être sui
 *Prérequis : Modules 1-4 (navigation et manipulation de fichiers)*
 *Durée : 12-15 heures (module plus avancé)*
 
+**Module additionnel Arduino : du sketch à l'intégration continue** (lecture personnelle, hors séances)
+- Chapitre Arduino 1 : De l'Arduino à la XIAO ESP32-S3
+- Chapitre Arduino 2 : De l'IDE Arduino à PlatformIO
+- Chapitre Arduino 3 : MQTT et Home Assistant
+- Chapitre Arduino 4 : Lecture du code
+- Chapitre Arduino 5 : Les tests unitaires
+- Chapitre Arduino 6 : Qualité et intégration continue
+
+*Prérequis : avoir utilisé l'IDE Arduino ; module additionnel Git*
+*Durée : 6-8 heures de lecture*
+*Le code étudié n'est pas copié ici : il est cité depuis le dépôt public pguinet/arduino (sketches/XIAO-ESP32-S3/DS18B20_MQTT), au commit figé 1af068f.*
+
 ## Structure des fichiers du projet
 
 ```
@@ -148,7 +160,7 @@ formation_linux/
       installation_ssh.md           (public A : se connecter à sa VM distante)
       installation_virtualbox.md    (public B : Debian 13 dans VirtualBox, illustré)
   supports/
-    modules_additionnels/           (toujours actif : modules Git et Docker)
+    modules_additionnels/           (toujours actif : modules Git, Git sous Windows, Docker, Arduino)
       module_git/
         01_introduction_git.md
         02_commandes_base.md
@@ -164,6 +176,13 @@ formation_linux/
         02_images_conteneurs.md
         03_volumes_reseaux.md
         04_compose_orchestration.md
+      module_arduino/               (lecture personnelle : PlatformIO, tests, CI)
+        01_arduino_xiao_esp32s3.md
+        02_ide_vers_platformio.md
+        03_mqtt_home_assistant.md
+        04_lecture_code.md
+        05_tests_unitaires.md
+        06_qualite_integration_continue.md
   travaux_pratiques/
     tp_additionnels/                (toujours actif : TP Git et Docker)
       tp_git/
@@ -204,7 +223,7 @@ formation_linux/
       plans/                        (plans d'implémentation)
 ```
 
-**Remarque** : `archives/cours_2025/` contient l'ancien matériau du cours de base issu de la version précédente. Ne plus le modifier et ne plus le générer en PDF. Tout nouveau contenu de cours va dans `cours_2026/`. `supports/` et `travaux_pratiques/` ne contiennent plus que les modules additionnels (Git, Git sous Windows, Docker), toujours actifs.
+**Remarque** : `archives/cours_2025/` contient l'ancien matériau du cours de base issu de la version précédente. Ne plus le modifier et ne plus le générer en PDF. Tout nouveau contenu de cours va dans `cours_2026/`. `supports/` et `travaux_pratiques/` ne contiennent plus que les modules additionnels (Git, Git sous Windows, Docker, Arduino), toujours actifs.
 
 ## Template de chapitre
 

README.md

@@ -107,6 +107,12 @@ Introduction à Docker : images et conteneurs, volumes et réseaux, Docker Compo
 Contenu : `supports/modules_additionnels/module_docker/`
 TP : `travaux_pratiques/tp_additionnels/tp_docker/`
 
+### Module Arduino -- Du sketch à l'intégration continue (6-8h de lecture)
+
+À lire chez soi, hors séances, pour qui connaît Arduino par l'IDE officiel et les fichiers `.ino` : la carte XIAO ESP32-S3 et la sonde DS18B20, PlatformIO, MQTT et Home Assistant, lecture du code d'un projet réel ([pguinet/arduino](https://github.com/pguinet/arduino)), tests unitaires natifs, cppcheck et GitHub Actions. Presque tout se fait sans carte.
+
+Contenu : `supports/modules_additionnels/module_arduino/`
+
 
 ## Structure du dépôt
 
@@ -131,6 +137,7 @@ formation_linux/
 |       +-- module_git/
 |       +-- module_git_windows/
 |       +-- module_docker/
+|       +-- module_arduino/
 |
 +-- travaux_pratiques/
 |   +-- tp_additionnels/         # Modules additionnels (TP)

docs/superpowers/plans/2026-10-15-module-arduino.md.tasks.json

@@ -0,0 +1,14 @@
+{
+  "planPath": "docs/superpowers/plans/2026-10-15-module-arduino.md",
+  "tasks": [
+    {"id": 0, "subject": "Task 0: Catalogue PDF et squelettes", "status": "completed"},
+    {"id": 1, "subject": "Task 1: Chapitre Arduino 1", "status": "completed", "blockedBy": [0]},
+    {"id": 2, "subject": "Task 2: Chapitre Arduino 2", "status": "completed", "blockedBy": [0]},
+    {"id": 3, "subject": "Task 3: Chapitre Arduino 3", "status": "completed", "blockedBy": [0]},
+    {"id": 4, "subject": "Task 4: Chapitre Arduino 4", "status": "completed", "blockedBy": [0]},
+    {"id": 5, "subject": "Task 5: Chapitre Arduino 5", "status": "completed", "blockedBy": [0]},
+    {"id": 6, "subject": "Task 6: Chapitre Arduino 6", "status": "completed", "blockedBy": [0]},
+    {"id": 7, "subject": "Task 7: Documentation du dépôt et vérification finale", "status": "completed", "blockedBy": [1, 2, 3, 4, 5, 6]}
+  ],
+  "lastUpdated": "2026-10-15T20:31:23Z"
+}

docs/superpowers/specs/2026-10-15-module-arduino-design.md

@@ -0,0 +1,99 @@
+# Module additionnel Arduino (PlatformIO, tests, CI) -- Design
+
+Date : 2026-10-15
+Statut : validé
+
+## Contexte
+
+Les lecteurs visés connaissent déjà Arduino, mais seulement à travers
+l'IDE officiel et des fichiers `.ino`. Le module leur montre comment
+travailler sur un microcontrôleur avec les pratiques de l'industrie :
+PlatformIO, découpage du code pour le rendre testable, tests unitaires,
+analyse statique et intégration continue.
+
+Le module s'appuie sur un projet réel et public :
+`sketches/XIAO-ESP32-S3/DS18B20_MQTT` du dépôt
+https://github.com/pguinet/arduino. Une sonde de température DS18B20,
+branchée sur une Seeed Studio XIAO ESP32-S3, publie ses mesures dans Home
+Assistant par MQTT Discovery.
+
+## Décisions
+
+1. **Un module de lecture personnelle, pas un cours en séance.** On n'a
+   donc aucune contrainte liée au CID (freeze, VirtualBox, USB dans la
+   VM). Le lecteur installe PlatformIO sur son propre PC : VS Code avec
+   l'extension, ou la CLI `pio`. Linux est l'exemple principal ; les
+   différences avec Windows (port COM) et macOS sont signalées.
+2. **Pas de matériel obligatoire.** Les tests natifs, la compilation et
+   cppcheck tournent sans carte. Seuls le flashage et la publication MQTT
+   demandent une carte, ainsi qu'un broker. On le dit dès le chapitre 1.
+3. **Le code reste dans le dépôt `pguinet/arduino`.** Le module en cite
+   des extraits commentés. Les liens pointent vers un commit figé
+   (`1af068f`) pour que le texte et le code ne divergent pas. On ne copie
+   pas le projet dans `formation_linux`.
+4. **MQTT et Home Assistant sont présentés juste assez pour comprendre le
+   code.** Un encadré renvoie au futur homelab du club, où un broker et un
+   Home Assistant pourront être installés.
+5. **Pas de dossier de TP séparé.** Les exercices sont dans les chapitres
+   et se font sans carte, sauf mention contraire.
+6. **Prérequis** : avoir déjà utilisé l'IDE Arduino, et avoir lu le module
+   additionnel Git (renvoi pour les commits, le fork et GitHub). Durée
+   de lecture : 6 à 8 heures.
+
+## Fichiers
+
+```
+supports/modules_additionnels/module_arduino/
+  01_arduino_xiao_esp32s3.md
+  02_ide_vers_platformio.md
+  03_mqtt_home_assistant.md
+  04_lecture_code.md
+  05_tests_unitaires.md
+  06_qualite_integration_continue.md
+```
+
+- `pdf/documents.yaml` : nouvelle entrée `module_additionnel_arduino.pdf`
+  (titre « Arduino : du sketch à l'intégration continue », sous-titre
+  « Module additionnel »), placée après Docker.
+- `pdf/tests/test_documents.py` : nom ajouté dans `ATTENDUS`, à la même
+  position.
+- `CLAUDE.md` et `README.md` : le module apparaît dans le plan et dans
+  l'arborescence.
+
+## Contenu des chapitres
+
+| Chapitre | Contenu |
+|---|---|
+| Arduino 1 : de l'Arduino à la XIAO ESP32-S3 | L'écosystème Arduino (framework et cartes), l'ESP32-S3, Seeed Studio et la XIAO (antenne U.FL obligatoire, USB natif, `303a:1001`). Le projet en bref : DS18B20, bus 1-Wire, pull-up interne, schéma de câblage en ASCII. Ce qu'on peut faire sans carte |
+| Arduino 2 : de l'IDE à PlatformIO | Ce que cache un `.ino` (prototypes générés, `#include <Arduino.h>` implicite, bibliothèques globales non versionnées). Installation (VS Code et extension, ou CLI). Arborescence `src/lib/test`, `platformio.ini` (plateforme, carte, environnements `xiao` et `native`, `lib_deps` versionnées). `pio run`, `-t upload`, `pio device monitor` |
+| Arduino 3 : MQTT et Home Assistant | Broker, client, sujets, QoS en bref, messages retenus, testament (LWT). MQTT Discovery : le JSON de configuration, `availability_mode: all`. Le tableau des sujets du projet. Encadré homelab |
+| Arduino 4 : lecture du code | L'architecture : code matériel dans `src/main.cpp`, logique pure dans `lib/temp_logic`. Boucle non bloquante (`millis()` contre `delay()`, débordement géré par la soustraction non signée, conversion DS18B20 asynchrone). Validation des lectures (-127, 85), `PublishPolicy`, `ProbeHealth`. Reconnexion WiFi et MQTT. Secrets (`credentials.h`, `.example`, `#error`) |
+| Arduino 5 : tests unitaires | Pourquoi tester du code embarqué, et pourquoi sur le PC. Unity (`setUp`, `TEST_ASSERT_*`, `RUN_TEST`), une suite par dossier de `test/`, l'environnement `native`. Lecture détaillée d'un test, `pio test -e native`, lire un échec. Écrire un test (cas limite) |
+| Arduino 6 : qualité et intégration continue | cppcheck (`pio check`, `check_flags`, suppressions en ligne justifiées). GitHub Actions : `ci.yml` décortiqué (déclencheurs, `permissions`, job `discover`, matrice, cache, version de PlatformIO figée, `credentials.h` factice, `--fail-on-defect=low`). Lire un échec dans l'onglet Actions. Badge, protection de branche en « Pour aller plus loin » |
+
+Chaque chapitre suit le template du projet : objectifs, durée, sections,
+`L'essentiel`, `Pour aller plus loin`, 3 à 6 exercices avec leurs
+solutions. Le calibrage du template (150 à 250 lignes de théorie) est
+appliqué avec souplesse : les chapitres 4 et 6 citent du code et seront
+plus longs. Chaque concept n'est enseigné qu'une fois, avec des renvois
+« (voir chapitre Arduino N) ».
+
+## Exercices sans carte (exemples)
+
+- Créer un projet PlatformIO vide, ajouter une bibliothèque dans
+  `lib_deps`, compiler pour `seeed_xiao_esp32s3`.
+- Ajouter un test à `test_reading` (85 °C après une lecture à 80 °C),
+  puis casser volontairement `isValidReading` et observer l'échec.
+- Introduire un défaut repéré par cppcheck, puis le corriger.
+- Sur un fork, pousser une branche qui casse un test et lire le résultat
+  dans l'onglet Actions.
+
+## Vérification
+
+- `./pdf/build` passe : PDF générés, tests pytest verts, aucun
+  `Missing character`.
+- Les commandes et extraits cités sont vérifiés sur le dépôt `arduino` au
+  commit `1af068f` : `pio test -e native` (24 tests), `pio run -e xiao`,
+  `pio check`.
+- Aucun caractère interdit : pas de dessin de boîtes, pas de flèches
+  Unicode, pas d'emojis.

pdf/documents.yaml

@@ -85,6 +85,16 @@ documents:
       - travaux_pratiques/tp_additionnels/tp_docker/tp3_volumes_donnees.md
       - travaux_pratiques/tp_additionnels/tp_docker/tp4_reseaux_communication.md
       - travaux_pratiques/tp_additionnels/tp_docker/tp5_compose_orchestration.md
+  - fichier: module_additionnel_arduino.pdf
+    titre: "Arduino : du sketch à l'intégration continue"
+    sous_titre: Module additionnel
+    sources:
+      - supports/modules_additionnels/module_arduino/01_arduino_xiao_esp32s3.md
+      - supports/modules_additionnels/module_arduino/02_ide_vers_platformio.md
+      - supports/modules_additionnels/module_arduino/03_mqtt_home_assistant.md
+      - supports/modules_additionnels/module_arduino/04_lecture_code.md
+      - supports/modules_additionnels/module_arduino/05_tests_unitaires.md
+      - supports/modules_additionnels/module_arduino/06_qualite_integration_continue.md
   - fichier: annexe_installation_ssh.pdf
     titre: Se connecter à sa VM distante (SSH)
     sous_titre: Annexe

pdf/tests/test_documents.py

@@ -83,6 +83,7 @@ def test_selectionne_les_documents_demandes():
     "module_additionnel_git.pdf",
     "module_additionnel_git_windows.pdf",
     "module_additionnel_docker.pdf",
+    "module_additionnel_arduino.pdf",
     "annexe_installation_ssh.pdf",
     "annexe_installation_virtualbox.pdf",
 ]
@@ -92,7 +93,7 @@ def catalogue_du_depot():
     return generer.charger_documents(generer.DOSSIER_PDF / "documents.yaml", generer.RACINE)
 
 
-def test_le_catalogue_du_depot_declare_les_13_pdf():
+def test_le_catalogue_du_depot_declare_les_14_pdf():
     assert [document.fichier for document in catalogue_du_depot().documents] == ATTENDUS