Comprendre l'organisation du code source du micrologiciel OSSM
Structure des dossiers
Le micrologiciel OSSM suit une architecture modulaire basée sur les fonctionnalités. Chaque fonctionnalité réside dans son propre dossier d'espace de noms, ce qui facilite la navigation et la maintenance de la base de code.
Parcourez le code source sur GitHub : Software/src/
Aperçu
| Dossier | But |
|---|---|
include/boost/ | Bibliothèques d'en-tête uniquement (machine à états Boost.SML) |
lib/StrokeEngine/ | Bibliothèque de modèles de mouvement (modifiée) |
src/ | Code source principal |
test/ | Tests unitaires |
Philosophie de conception
Le micrologiciel utilise une organisation basée sur les fonctionnalités où le code associé cohabite :
- Espaces de noms plutôt que classes - Les fonctionnalités sont organisées en fonctions d'espace de noms plutôt qu'en méthodes de classe
- Fichiers colocalisés : l'en-tête, l'implémentation et le code associé de chaque fonctionnalité se trouvent dans le même dossier.
- Structures d'état globales - L'état partagé est géré via des structures d'état dédiées plutôt que par des membres de classe
- Modules sans état - Les fonctions de chaque fonctionnalité travaillent sur l'état global, ce qui les rend plus faciles à tester et à comprendre.
La classe OSSM dans ossm/OSSM.h est conservée pour des raisons de rétrocompatibilité avec la gestion des commandes BLE. Les nouvelles fonctionnalités doivent utiliser des fonctions d'espace de noms sans état.
Application principale (src/ossm/)
Le dossier ossm/ contient la logique d'application principale, organisée par fonctionnalité.
| Dossier | But |
|---|---|
state/ | Architecture des machines à états |
pages/ | Écrans d'interface utilisateur |
homing/ | Séquence de référence |
menu/ | Navigation dans les menus |
simple_penetration/ | Mode de pénétration simple |
stroke_engine/ | Mode StrokeEngine |
pattern_controls/ | Interface utilisateur de sélection de motif |
play_controls/ | Commandes lecture/pause/vitesse |
Machine à états (ossm/state/)
Les composants de la machine à états sont séparés pour plus de clarté et de testabilité.
| Fichier | But |
|---|---|
machine.h | Définition de la table de transition à l'aide de Boost.SML |
actions.h / actions.cpp | Actions de transition d'état (mises à jour de l'affichage, contrôle du moteur) |
guards.h / guards.cpp | Vérifications conditionnelles pour les transitions |
state.h / state.cpp | Initialisation de la machine à états et instance globale |
Les structures d'état gèrent différents aspects de l'application :
| Fichier | But |
|---|---|
session.h | Session en cours (heure de début, nombre de courses, distance) |
settings.h | Paramètres utilisateur (vitesse, course, sensation, profondeur, motif) |
calibration.h | État de référence (décalage du capteur, pas par course, statut de référence) |
motion.h | Cibles de mouvement (position, vitesse, temps) |
menu.h | Sélection de menu actuelle |
ble.h | État de la connexion Bluetooth |
error.h | Messages d'erreur |
Pour plus de détails sur le fonctionnement de la machine à états, voir Architecture de la machine à états.
Pages d'interface utilisateur (ossm/pages/)
Chaque écran de l'interface utilisateur possède son propre module.
| Module | Description |
|---|---|
hello.h | Écran de démarrage avec logos animés |
preflight.h | Écran de contrôle de sécurité « Réduire la vitesse pour démarrer » |
error.h | Affichage d'erreur avec option d'aide |
update.h | Écrans de mise à jour OTA (vérification, mise à jour, pas de mise à jour) |
wifi.h | Portail de configuration WiFi |
help.h | Informations d'aide et d'assistance |
Modes de fonctionnement
Chaque mode de fonctionnement est un module autonome avec sa logique de contrôle de mouvement.
| Module | Description |
|---|---|
simple_penetration/ | Mouvement de base de va-et-vient à vitesse contrôlée |
stroke_engine/ | Modèles complexes utilisant la bibliothèque StrokeEngine |
Interfaces de contrôle
| Module | Description |
|---|---|
menu/ | Navigation et rendu dans le menu principal |
pattern_controls/ | Interface de sélection de motif pour le mode StrokeEngine |
play_controls/ | Contrôles de vitesse, de course, de profondeur et de sensation |
Modules de fonctionnalités
| Module | Description |
|---|---|
homing/ | Séquence de référencement (balayage avant, balayage arrière, étalonnage) |
Services matériels (src/services/)
Le dossier services/ fournit des couches d'abstraction matérielle.
| Fichier | But |
|---|---|
stepper.h/.cpp | Contrôle du moteur (FastAccelStepper) |
display.h/.cpp | Écran OLED (U8g2) |
encoder.h/.cpp | Entrée du codeur rotatif |
led.h/.cpp | Indication d'état de la LED RGB |
board.h/.cpp | Initialisation de la carte |
tasks.h/.cpp | Gestion des tâches FreeRTOS |
wm.h/.cpp | Gestionnaire Wi-Fi |
communication/ | Communication BLE et WiFi |
Pour plus de détails sur le protocole BLE, voir Communication BLE.
Constantes (src/constants/)
Les valeurs de configuration et les énumérations sont centralisées dans le dossier constants/.
| Fichier | But |
|---|---|
Config.h | Configuration du système (vitesses, limites, délais d'attente) |
Pins.h | Définitions des broches GPIO |
Menu.h | Énumération des options de menu |
Version.h | Informations sur la version du micrologiciel |
UserConfig.h | Paramètres configurables par l'utilisateur |
Images.h | Ressources bitmap pour l'affichage |
LogTags.h | Balises de journalisation ESP-IDF |
copy/ | Chaînes localisées |
Pour les options de configuration, voir Configuration.
Utilitaires (src/utils/)
Fonctions et classes d'assistance utilisées dans toute la base de code.
| Fichier | But |
|---|---|
StateLogger.h | Enregistre les transitions de la machine à états pour le débogage |
RecursiveMutex.h | Wrapper de mutex thread-safe pour ESP32 |
StrokeEngineHelper.h | Utilitaires d'intégration StrokeEngine |
format.h | Aides au formatage de chaînes |
analog.h | Moyennage et traitement des entrées analogiques |
update.h | Utilitaires de mise à jour OTA |
ble.h | Fonctions d'assistance BLE |
Structures de données (src/structs/)
Types de données partagés utilisés entre les modules.
| Fichier | But |
|---|---|
SettingPercents.h | Paramètres utilisateur sous forme de pourcentages (0-100) |
LanguageStruct.h | Configuration de la langue |
Points.h | Structures de coordonnées et de points |
Bibliothèques
Boost.SML (include/boost/sml.hpp)
Boost.SML est une bibliothèque de machine à états composée uniquement d'en-têtes. Elle est incluse directement dans le projet pour la stabilité des versions.
StrokeEngine (lib/StrokeEngine/)
Une version modifiée de theelims/StrokeEngine qui génère des motifs de mouvement. La bibliothèque est fournie et personnalisée pour les exigences spécifiques à OSSM.
Configuration de construction
Le fichier platformio.ini définit les environnements de compilation :
| Environnement | But |
|---|---|
development | Développement local avec journalisation de débogage |
staging | Tests avant publication |
production | Versions de publication avec optimisations |
test | Configuration des tests unitaires |