From 491d7ea1ab635499fe569981fd3f8a170bb16168 Mon Sep 17 00:00:00 2001 From: Julien Oculi Date: Wed, 26 Jun 2024 14:24:41 +0200 Subject: [PATCH] docs(server): :memo: replace comment by docstring for functions --- server/src/commande_telephone.ino | 13 +++++---- server/src/controls.h | 47 ++++++++++++++++++++++++------- server/src/convert.h | 32 +++++++++++++++------ server/src/server.hpp | 45 +++++++++++++++++++++++------ 4 files changed, 104 insertions(+), 33 deletions(-) diff --git a/server/src/commande_telephone.ino b/server/src/commande_telephone.ino index 0293bb5..a5e83f1 100644 --- a/server/src/commande_telephone.ino +++ b/server/src/commande_telephone.ino @@ -7,7 +7,7 @@ #include "config.h" // Configuration des entrées/sorties et delais. #include "controls.h" // Fonctions pour se déplacer. #include "convert.h" // Utilitaires pour convertir des mesures en steps. -#include "server.hpp" // Configure et demarre le server HTTP. +#include "server.hpp" // Configure et demarre le server HTTP. // État global de la commande en cours command_t command = {.running = false, .stopped = false}; @@ -18,11 +18,11 @@ AsyncWebServer server(80); // Code exécuté au démarrage (paramétrage) : void setup() { - setupPins(); // Configure les pins de l'ESP32 - Serial.begin(115200); // Démarrage d'une communication Série avec l'ordinateur s'il est connecté - connectWiFi(WiFi); // Connexion au wifi - serverConfig(server, command); // Configuration du serveur - server.begin(); // Démarrage du serveur + setupPins(); // Configure les pins de l'ESP32 + Serial.begin(115200); // Démarrage d'une communication Série avec l'ordinateur s'il est connecté + connectWiFi(WiFi); // Connexion au wifi + serverConfig(server, command); // Configuration du serveur + server.begin(); // Démarrage du serveur } // Code exécuté en boucle jusqu'à l'extinction du robot @@ -54,6 +54,7 @@ void loop() } } +// Met à jour l'état du robot en fonction de la commande en cours. void updateCommand(command_t &command) { if (command.name == "forward") diff --git a/server/src/controls.h b/server/src/controls.h index 695f7ee..cd3abee 100644 --- a/server/src/controls.h +++ b/server/src/controls.h @@ -2,7 +2,10 @@ Initialisation et fonctions de déplacement *******************************************/ -// Configure les ports de contrôle des moteurs sont des sorties (output) +/** + * @brief Configure les ports de contrôle des moteurs sont des sorties (output). + * + */ void setupPins() { pinMode(IN1a, OUTPUT); @@ -16,9 +19,18 @@ void setupPins() pinMode(IN4b, OUTPUT); } -// Applique une configuration aux moteurs. -// Chaque configuration est sur 1 octet. -// ex: writeMotor(0b0010, 0b1100); +/** + * @brief Applique une configuration aux moteurs. + * @brief Chaque configuration est sur 1 octet. + * + * Exemple + * ``` + * writeMotor(0b0010, 0b1100); + * ``` + * + * @param left Configuration du moteur droit (ex: `0b1100`). + * @param right Configuration du moteur droit (ex: `0b0101`). + */ void writeMotor(uint8_t left, uint8_t right) { digitalWrite(IN4a, left & 0b1000); @@ -31,7 +43,10 @@ void writeMotor(uint8_t left, uint8_t right) digitalWrite(IN1b, right & 0b0001); } -// Commande pour faire avancer le robot. +/** + * @brief Commande pour faire avancer le robot. + * + */ void forward() { writeMotor(0b1000, 0b0001); @@ -44,7 +59,10 @@ void forward() delay(DELAY_TIME); } -// Commande pour faire reculer le robot. +/** + * @brief Commande pour faire reculer le robot. + * + */ void backward() { writeMotor(0b0001, 0b1000); @@ -57,7 +75,10 @@ void backward() delay(DELAY_TIME); } -// Commande pour faire tourner le robot à droite. +/** + * @brief Commande pour faire tourner le robot à droite. + * + */ void right() { writeMotor(0b1000, 0b1000); @@ -70,7 +91,10 @@ void right() delay(DELAY_TIME); } -// Commande pour faire tourner le robot à gauche. +/** + * @brief Commande pour faire tourner le robot à gauche. + * + */ void left() { writeMotor(0b0001, 0b0001); @@ -83,8 +107,11 @@ void left() delay(DELAY_TIME); } -// Commande pour arrêter les moteurs du robot. -void stopMotors(void) +/** + * @brief Commande pour arrêter les moteurs du robot. + * + */ +void stopMotors() { writeMotor(0b0000, 0b0000); } \ No newline at end of file diff --git a/server/src/convert.h b/server/src/convert.h index d861e40..a6b2d18 100644 --- a/server/src/convert.h +++ b/server/src/convert.h @@ -2,20 +2,36 @@ Utilitaires de conversions physique -> steps *********************************************/ -// Convertit une longueur en cm vers un nombre de pas moteur. -// ex: -// float distance = 22.3; //cm -// int steps = convertLengthToSteps(distance); +/** + * @brief Convertit une longueur en cm vers un nombre de pas moteur. + * + * Exemple + * ``` + * float distance = 22.3; //cm + * int steps = convertLengthToSteps(distance); + * ``` + * + * @param length + * @return int + */ int convertLengthToSteps(float length) { float result = length * 512 / (4 * 3.1415); return int(result); } -// Convertit une rotation en degrés vers un nombre de pas moteur. -// ex: -// float angle = 45; //deg -// int steps = convertRotToSteps(angle); +/** + * @brief Convertit une rotation en degrés vers un nombre de pas moteur. + * + * Exemple + * ``` + * float angle = 45; //deg + * int steps = convertRotToSteps(angle); + * ``` + * + * @param rotation Angle en degrés. + * @return int Nombres de pas pour les moteurs. + */ int convertRotToSteps(int rotation) { int result = convertLengthToSteps(rotation * 3.1415 / 180 * 7.8); diff --git a/server/src/server.hpp b/server/src/server.hpp index 6a38fb7..e125dd6 100644 --- a/server/src/server.hpp +++ b/server/src/server.hpp @@ -2,7 +2,10 @@ Configuration et handlers du server ************************************/ -// Type de la variable globale command +/** + * @brief Type de la variable globale command + * + */ struct command_t { bool running; // Une commande doit être exécutée @@ -11,7 +14,14 @@ struct command_t int value; // Valeur (nombre de pas à effectuer) }; -// Met à jour la command globale. +/** + * @brief Met à jour la command globale. + * @internal + * + * @param commandName Nom de la nouvelle commande. + * @param commandValue Valeur de la nouvelle commande. + * @param globalCommand Commande globale (courante). + */ void setGlobals(String commandName, float commandValue, command_t &globalCommand) { // Assert command before updating globals @@ -54,12 +64,20 @@ void requestCheck(String commandName, float commandValue, command_t &globalComma } /** - * Parse la requête GET (vers "/get") du serveur et résout le nom de la commande et sa valeur. + * @brief Parse la requête GET (vers "/get") du serveur et résout le nom de la commande et sa valeur. + * + * Exemple : + * ``` + * String commandName; + * float commandValue; + * parseRequestParams(request, commandName, commandValue); + * ``` + * + * @param request Requête contenant la commande. + * @param commandName Nom de la commande à assigner. + * @param commandValue Valeur de la commande à assigner. + * @param globalCommand Commande globale (courante) à mettre à jour. * - * Example - * String commandName; - * float commandValue; - * parseRequestParams(request, commandName, commandValue); */ void parseRequestParams(AsyncWebServerRequest *request, String &commandName, float &commandValue, command_t &globalCommand) { @@ -79,7 +97,12 @@ void parseRequestParams(AsyncWebServerRequest *request, String &commandName, flo requestCheck(commandName, commandValue, globalCommand); } -// Configuration du serveur asynchrone. +/** + * @brief Configuration du serveur asynchrone. + * + * @param server Serveur à configurer. + * @param globalCommand Commande globale (courante) à mettre à jour lors des requêtes. + */ void serverConfig(AsyncWebServer &server, command_t &globalCommand) { server.on("/get", HTTP_GET, [&globalCommand](AsyncWebServerRequest *request) @@ -96,7 +119,11 @@ void serverConfig(AsyncWebServer &server, command_t &globalCommand) request->send(200, "text/plain", commandName); }); } -// Démarre le point d'accès WiFi. +/** + * @brief Démarre le point d'accès WiFi. + * + * @param WiFi WiFi à configurer. + */ void connectWiFi(WiFiClass &WiFi) { // For simulator only