feat: add initial Arduino software documentation

.cspell/steami.txt

@@ -102,6 +102,7 @@ Vittascience
 MakeCode
 CODAL
 Arduino
+arduino
 Altium
 KiCad
 Inkscape
@@ -114,6 +115,7 @@ husky
 Prettier
 ESLint
 lychee
+venv
 
 # STeaMi specific
 STeaMi

docs/software/arduino/conventions.md

@@ -0,0 +1,232 @@
+---
+title: Conventions API des drivers
+sidebar_position: 4
+---
+
+# Conventions de l'API Arduino
+
+Tous les drivers de **arduino-steami-lib** suivent les mêmes conventions afin de proposer une API cohérente sur l'ensemble des composants de la carte STeaMi.
+
+Une fois qu'un driver est maîtrisé, les autres s'utilisent de manière très similaire.
+
+## Initialisation
+
+Tous les drivers utilisent le même principe d'initialisation.
+
+Le constructeur reçoit le bus de communication (`TwoWire` pour l'I²C) ainsi que l'adresse du périphérique, qui est optionnelle lorsque l'adresse par défaut est utilisée.
+
+```cpp
+#include <Wire.h>
+#include <HTS221.h>
+
+TwoWire internalI2C(I2C_INT_SDA, I2C_INT_SCL);
+HTS221 sensor(internalI2C);
+
+void setup() {
+    internalI2C.begin();
+
+    if (!sensor.begin()) {
+        Serial.println("Capteur non détecté");
+        while (true);
+    }
+}
+```
+
+La méthode `begin()` :
+
+- vérifie la présence du composant ;
+- charge les données de calibration lorsque nécessaire ;
+- initialise le périphérique dans son état par défaut.
+
+Elle retourne toujours `false` si le composant n'est pas détecté.
+
+---
+
+## Identification du composant
+
+Chaque driver fournit une méthode permettant de lire l'identifiant matériel (`WHO_AM_I`).
+
+```cpp
+uint8_t id = sensor.deviceId();
+
+Serial.print("Device ID : 0x");
+Serial.println(id, HEX);
+```
+
+Cette méthode est principalement utile pour le diagnostic ou le débogage.
+
+---
+
+## Gestion de l'alimentation
+
+Tous les capteurs peuvent être activés ou mis en veille.
+
+```cpp
+sensor.powerOff();
+
+// ...
+
+sensor.powerOn();
+```
+
+Cela permet de réduire la consommation lorsque les mesures ne sont pas nécessaires.
+
+---
+
+## Lecture des mesures
+
+Les méthodes suivent une convention de nommage commune.
+
+### Lecture d'une grandeur
+
+Les unités SI courantes n'utilisent pas de suffixe.
+
+```cpp
+float temperature = sensor.temperature();
+float humidity = sensor.humidity();
+```
+
+### Mesure avec unité explicite
+
+Lorsque plusieurs unités sont possibles, un suffixe est ajouté au nom de la méthode.
+
+```cpp
+float pressure = sensor.pressureHpa();
+uint16_t distance = sensor.distanceMm();
+
+auto accel = imu.accelerationG();
+auto gyro = imu.gyroscopeDps();
+```
+
+### Lecture complète
+
+La plupart des drivers proposent également une méthode `read()` qui retourne toutes les mesures du capteur.
+
+```cpp
+auto data = sensor.read();
+
+Serial.println(data.temperature);
+Serial.println(data.humidity);
+```
+
+Le contenu de la structure dépend du composant.
+
+---
+
+## Disponibilité des données
+
+Les drivers permettent de vérifier si une nouvelle mesure est disponible avant la lecture.
+
+```cpp
+if (sensor.dataReady()) {
+    auto data = sensor.read();
+}
+```
+
+Certains composants proposent également des méthodes spécifiques :
+
+```cpp
+sensor.temperatureReady();
+sensor.pressureReady();
+sensor.humidityReady();
+```
+
+---
+
+## Mesures en continu et One-Shot
+
+Les capteurs proposant plusieurs modes de fonctionnement utilisent toujours les mêmes méthodes.
+
+### Mode continu
+
+```cpp
+sensor.setContinuous(HTS221_ODR_1_HZ);
+```
+
+La fréquence d'acquisition est définie grâce aux constantes du driver.
+
+### Mesure unique
+
+```cpp
+sensor.triggerOneShot();
+
+while (!sensor.dataReady()) {
+}
+
+auto data = sensor.read();
+```
+
+La plupart des drivers proposent également une version simplifiée :
+
+```cpp
+auto data = sensor.readOneShot();
+```
+
+---
+
+## Calibration
+
+Les drivers mesurant une grandeur physique peuvent appliquer une correction logicielle.
+
+### Offset
+
+```cpp
+sensor.setTemperatureOffset(-0.5f);
+```
+
+### Calibration sur deux points
+
+```cpp
+sensor.calibrateTemperature(
+    20.0f, 20.8f,
+    40.0f, 41.3f
+);
+```
+
+La correction utilisateur est appliquée après la calibration d'usine.
+
+---
+
+## Bus I²C interne de la STeaMi
+
+La majorité des capteurs intégrés à la carte utilisent le bus I²C interne.
+
+Il est donc recommandé de créer une instance dédiée :
+
+```cpp
+TwoWire internalI2C(I2C_INT_SDA, I2C_INT_SCL);
+
+internalI2C.begin();
+```
+
+Puis de la transmettre au constructeur du driver :
+
+```cpp
+HTS221 sensor(internalI2C);
+```
+
+L'utilisation du bus `Wire` par défaut ne permet pas de communiquer avec les capteurs intégrés de la carte.
+
+---
+
+## Conventions générales
+
+| Convention                                         | Description                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| `begin()`                                          | Initialise le périphérique et vérifie sa présence.           |
+| `deviceId()`                                       | Retourne l'identifiant matériel (`WHO_AM_I`).                |
+| `powerOn()` / `powerOff()`                         | Active ou met le périphérique en veille.                     |
+| `read()`                                           | Retourne toutes les mesures disponibles.                     |
+| `temperature()`, `humidity()`                      | Mesures exprimées dans les unités SI usuelles.               |
+| `pressureHpa()`, `distanceMm()`, `accelerationG()` | Le suffixe indique l'unité utilisée.                         |
+| `dataReady()`                                      | Vérifie que les nouvelles mesures sont disponibles.          |
+| `setContinuous()`                                  | Active les acquisitions en continu.                          |
+| `triggerOneShot()`                                 | Lance une mesure unique sans attendre le résultat.           |
+| `readOneShot()`                                    | Lance une mesure unique et retourne directement le résultat. |
+
+## Voir aussi
+
+- Installation
+- Arduino IDE
+- PlatformIO
+- Drivers

docs/software/arduino/index.md

@@ -1,34 +1,71 @@
 ---
 title: Arduino
-sidebar_position: 5
+sidebar_position: 3
 ---
 
-# Arduino / STM32duino
+# Arduino
 
-Le support Arduino pour la carte STeaMi est minimal. La carte est compatible avec [STM32duino](https://github.com/stm32duino/Arduino_Core_STM32) mais les drivers spécifiques ne sont pas encore développés.
+Arduino est l'un des environnements de développement les plus populaires pour les microcontrôleurs. La bibliothèque **arduino-steami-lib** fournit des drivers Arduino/C++ pour tous les capteurs et périphériques intégrés à la carte STeaMi.
 
-## État du support
+## Drivers disponibles
 
-| Composant            | Supporté |
-| -------------------- | :------: |
-| GPIO de base         |    ✅    |
-| I2C / SPI / UART     |    ✅    |
-| Capteurs spécifiques |    ❌    |
-| Écran OLED           |    ❌    |
-| Boutons (MCP23009)   |    ❌    |
-| Flash (DAPLink)      |    ❌    |
+| Driver          | Composant                                        | Avancé du driver | Exemples | Code sources                                                                                   |
+| --------------- | ------------------------------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `apds9960`      | Capteur de lumière, couleur, proximité et gestes | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/apds9960/README.md)      |
+| `bq27441`       | Jauge de batterie                                | ✅               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/bq27441/README.md)       |
+| `daplink_flash` | Configuration et mémoire Flash                   | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/daplink_flash/README.md) |
+| `hts221`        | Humidité et température                          | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/hts221/README.md)        |
+| `ism330dl`      | Accéléromètre et gyroscope                       | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/ism330dl/README.md)      |
+| `lis2mdl`       | Magnétomètre                                     | ✅               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/lis2mdl/README.md)       |
+| `mcp23009e`     | Expandeur GPIO et boutons                        | ✅               | 5        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/mcp23009e/README.md)     |
+| `ssd1327`       | Écran OLED 128×128                               | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/ssd1327/README.md)       |
+| `steami_config` | Configuration persistante                        | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/steami_config/README.md) |
+| `vl53l1x`       | Capteur de distance ToF                          | ✅               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/vl53l1x/README.md)       |
+| `wsen-hids`     | Humidité et température                          | ✅               | 4        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/wsen-hids/README.md)     |
+| `wsen-pads`     | Pression atmosphérique et température            | ❌               | 0        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/wsen-pads/README.md)     |
+| `bme280`        | Pression, humidité et température _(à venir)_    | ❌               | —        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/bme280/README.md)        |
+| `gc9a01`        | Écran LCD rond _(à venir)_                       | ❌               | —        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/gc9a01/README.md)        |
+| `im34dt05`      | Microphone numérique _(à venir)_                 | ❌               | —        | [README](https://github.com/steamicc/arduino-steami-lib/blob/main/lib/im34dt05/README.md)      |
 
-## Installation de STM32duino
+## Conventions de l'API
 
-Voir le guide d'installation sur [stm32python.gitlab.io](https://stm32python.gitlab.io/fr/docs/Stm32duino/installation).
+Tous les drivers suivent les mêmes conventions afin d'offrir une API cohérente d'un composant à l'autre.
 
-## Roadmap
+Les principales méthodes sont :
 
-Le support Arduino nécessite le développement de drivers pour chaque composant de la carte. Les contributions sont les bienvenues.
+- `begin()` : initialise le périphérique et vérifie sa présence.
+- `deviceId()` : lit l'identifiant matériel (`WHO_AM_I`).
+- `powerOn()` / `powerOff()` : active ou désactive le périphérique.
+- `read()` : lit toutes les mesures disponibles.
+- `temperature()`, `humidity()`, `pressureHpa()`, `distanceMm()`, etc. : lecture d'une mesure spécifique.
+- `dataReady()` : indique si de nouvelles données sont disponibles.
+
+Les noms des méthodes et leur comportement sont harmonisés avec la bibliothèque MicroPython afin de faciliter le passage d'un langage à l'autre.
+
+**Voir les conventions détaillées →** `./conventions`
+
+## Installation et outils
+
+- **Installation** — Installer la bibliothèque Arduino STeaMi.
+- **Arduino IDE** — Développer avec l'IDE Arduino.
+- **PlatformIO** — Développer avec Visual Studio Code et PlatformIO.
+- **Exemples** — Compiler et téléverser les exemples fournis.
+
+## Sections à venir
+
+La documentation sera progressivement complétée avec :
+
+- Tutoriels par capteur
+- Utilisation des bus I²C et SPI internes de la STeaMi
+- Bluetooth Low Energy (BLE)
+- Affichage graphique sur écran OLED
+- Gestion de la mémoire Flash
+- Développement de nouveaux drivers
+- Tests et qualification
 
 ## Voir aussi
 
-- [MicroPython](../micropython/) — Alternative avec support complet
-- [CODAL](../codal/) — Alternative C++ avec support partiel
-- [STM32duino](https://github.com/stm32duino/Arduino_Core_STM32) — Core Arduino pour STM32
-- [Tutoriels STM32duino](https://stm32python.gitlab.io/fr/docs/Stm32duino) — Exercices et ressources
+- Premiers pas
+- Documentation de la carte STeaMi
+- Dépôt GitHub `arduino-steami-lib`
+- Documentation Arduino officielle