diff --git a/.cspell/steami.txt b/.cspell/steami.txt index 73da7fd..06f390f 100644 --- a/.cspell/steami.txt +++ b/.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 diff --git a/docs/software/arduino/conventions.md b/docs/software/arduino/conventions.md new file mode 100644 index 0000000..4ba9cb6 --- /dev/null +++ b/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 +#include + +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 diff --git a/docs/software/arduino/index.md b/docs/software/arduino/index.md index 882e3e2..e096d82 100644 --- a/docs/software/arduino/index.md +++ b/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 diff --git a/docs/software/arduino/install.md b/docs/software/arduino/install.md new file mode 100644 index 0000000..7d917a2 --- /dev/null +++ b/docs/software/arduino/install.md @@ -0,0 +1,244 @@ +--- +title: Installation du firmware +sidebar_position: 1 +--- + +# Installation de l'environnement Arduino + +La bibliothèque **arduino-steami-lib** fournit les drivers Arduino/C++ nécessaires pour utiliser les capteurs et périphériques intégrés à la carte STeaMi. + +Le dépôt utilise principalement **PlatformIO** pour compiler et téléverser les programmes. Les commandes courantes sont regroupées dans un `Makefile`. + +## Prérequis + +Pour utiliser le projet, vous devez disposer de : + +- une carte **STeaMi** ; +- un câble USB permettant le transfert de données ; +- **Python 3** avec le module `venv` ; +- **Node.js** et `npm` ; +- `make` ; +- Git. + +Sous Debian ou Ubuntu, le support des environnements virtuels Python peut être installé avec : + +```bash +sudo apt install python3-venv +``` + +## Télécharger le projet + +Cloner le dépôt GitHub puis ouvrir son dossier : + +```bash +git clone https://github.com/steamicc/arduino-steami-lib.git +cd arduino-steami-lib +``` + +## Installer l'environnement de développement + +Exécuter la commande suivante à la racine du dépôt : + +```bash +make setup +``` + +Cette commande : + +- crée un environnement Python virtuel dans `.venv/` ; +- installe PlatformIO ; +- installe `clang-format` et `clang-tidy` ; +- installe les dépendances Node.js ; +- active les hooks Git du projet. + +Les versions des outils Python sont définies dans `requirements.txt`. + +## Compiler le firmware + +Pour compiler le firmware principal du dépôt : + +```bash +make build +``` + +Cette commande exécute PlatformIO sur l'environnement STeaMi configuré dans le projet. + +Elle compile notamment le programme principal situé dans `src/` ainsi que les drivers utilisés par celui-ci. + +La compilation permet de vérifier que : + +- la configuration de la carte est correcte ; +- les drivers sont compatibles entre eux ; +- le firmware peut être produit sans erreur. + +## Téléverser le firmware + +Connecter la carte STeaMi en USB, puis exécuter : + +```bash +make upload +``` + +Cette commande compile le firmware si nécessaire, puis le téléverse sur la carte avec PlatformIO. + +Le téléversement utilise le programmateur **CMSIS-DAP** intégré à la STeaMi. + +Lorsqu'un port doit être précisé, il peut être fourni avec la variable `PORT` : + +```bash +make upload PORT=/dev/ttyACM0 +``` + +Sous Windows, le port utilise généralement la forme suivante : + +```bash +make upload PORT=COM5 +``` + +## Vérifier le firmware + +Après le téléversement, ouvrir le moniteur série à `115200` bauds : + +```bash +source .venv/bin/activate +pio device monitor -b 115200 +``` + +Le programme principal du dépôt sert de test de compilation et de détection rapide des drivers intégrés. + +Pour quitter le moniteur série, utiliser : + +```text +Ctrl+C +``` + +## Compiler et téléverser un exemple + +Le dépôt contient également des exemples propres à chaque driver. + +### Lister les exemples + +```bash +make list-examples +``` + +La commande retourne des cibles prêtes à être exécutées, par exemple : + +```text +flash-hts221/read_temperature_humidity +flash-wsen-pads/altitude +flash-lis2mdl/compass +``` + +Il est possible de filtrer les résultats par driver : + +```bash +make list-examples DRIVER=hts221 +``` + +### Téléverser un exemple + +Copier l'une des cibles affichées et la passer à `make` : + +```bash +make flash-hts221/read_temperature_humidity +``` + +Cette commande : + +1. compile l'exemple pour la carte STeaMi ; +2. téléverse le programme ; +3. ouvre le moniteur série à `115200` bauds. + +## Capturer les messages de démarrage + +Le moniteur série interactif peut manquer les premières lignes envoyées immédiatement après le redémarrage de la carte. + +Pour capturer ces messages, remplacer `flash-` par `capture-` : + +```bash +make capture-hts221/read_temperature_humidity +``` + +Cette commande téléverse l'exemple, ouvre le port série avant le redémarrage de la carte, puis capture la sortie pendant 10 secondes. + +La durée peut être modifiée avec `DURATION` : + +```bash +make capture-hts221/read_temperature_humidity DURATION=30 +``` + +## Commandes principales + +| Commande | Description | +| --------------------------------- | -------------------------------------------------------- | +| `make setup` | Installe l'environnement de développement complet. | +| `make build` | Compile le firmware principal. | +| `make upload` | Compile et téléverse le firmware principal. | +| `make list-examples` | Liste les exemples disponibles. | +| `make flash-/` | Compile, téléverse et ouvre le moniteur série. | +| `make capture-/` | Compile, téléverse et capture les messages de démarrage. | +| `make test-native` | Exécute les tests sur l'ordinateur, sans carte. | +| `make test-hardware` | Exécute les tests sur une carte STeaMi. | +| `make clean` | Supprime les fichiers de compilation. | +| `make help` | Affiche toutes les commandes disponibles. | + +## Dépannage + +### La commande `make setup` échoue + +Vérifier que Python peut créer un environnement virtuel : + +```bash +python3 -m venv --help +``` + +Sous Debian ou Ubuntu, installer si nécessaire : + +```bash +sudo apt install python3-venv +``` + +Vérifier également les installations de Node.js et npm : + +```bash +node --version +npm --version +``` + +### La carte n'est pas détectée + +Vérifier : + +- que le câble USB permet le transfert de données ; +- que la carte est correctement alimentée ; +- que la STeaMi apparaît comme périphérique USB ; +- qu'aucun autre programme n'utilise déjà le port série. + +Pour lister les périphériques détectés par PlatformIO : + +```bash +source .venv/bin/activate +pio device list +``` + +### Le téléversement échoue sous Linux + +Une erreur telle que : + +```text +Error: unable to find CMSIS-DAP device +``` + +indique généralement que l'utilisateur ne dispose pas des permissions nécessaires pour accéder au programmateur intégré. + +Des règles `udev` doivent alors être installées pour autoriser l'accès aux interfaces CMSIS-DAP de la carte. + +La procédure complète est détaillée dans la page consacrée à PlatformIO. + +## Voir aussi + +- [Conventions de l'API](./conventions) +- [Dépôt arduino-steami-lib](https://github.com/steamicc/arduino-steami-lib) + +Cette version distingue maintenant clairement le **firmware principal** (`make build` / `make upload`) des **exemples individuels** (`make flash-...`).