docs(server): 📝 replace comment by docstring for functions

This commit is contained in:
Julien Oculi 2024-06-26 14:24:41 +02:00
parent 44699dba7c
commit 491d7ea1ab
4 changed files with 104 additions and 33 deletions

View file

@ -7,7 +7,7 @@
#include "config.h" // Configuration des entrées/sorties et delais. #include "config.h" // Configuration des entrées/sorties et delais.
#include "controls.h" // Fonctions pour se déplacer. #include "controls.h" // Fonctions pour se déplacer.
#include "convert.h" // Utilitaires pour convertir des mesures en steps. #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 // État global de la commande en cours
command_t command = {.running = false, .stopped = false}; command_t command = {.running = false, .stopped = false};
@ -18,11 +18,11 @@ AsyncWebServer server(80);
// Code exécuté au démarrage (paramétrage) : // Code exécuté au démarrage (paramétrage) :
void setup() void setup()
{ {
setupPins(); // Configure les pins de l'ESP32 setupPins(); // Configure les pins de l'ESP32
Serial.begin(115200); // Démarrage d'une communication Série avec l'ordinateur s'il est connecté Serial.begin(115200); // Démarrage d'une communication Série avec l'ordinateur s'il est connecté
connectWiFi(WiFi); // Connexion au wifi connectWiFi(WiFi); // Connexion au wifi
serverConfig(server, command); // Configuration du serveur serverConfig(server, command); // Configuration du serveur
server.begin(); // Démarrage du serveur server.begin(); // Démarrage du serveur
} }
// Code exécuté en boucle jusqu'à l'extinction du robot // 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) void updateCommand(command_t &command)
{ {
if (command.name == "forward") if (command.name == "forward")

View file

@ -2,7 +2,10 @@
Initialisation et fonctions de déplacement 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() void setupPins()
{ {
pinMode(IN1a, OUTPUT); pinMode(IN1a, OUTPUT);
@ -16,9 +19,18 @@ void setupPins()
pinMode(IN4b, OUTPUT); pinMode(IN4b, OUTPUT);
} }
// Applique une configuration aux moteurs. /**
// Chaque configuration est sur 1 octet. * @brief Applique une configuration aux moteurs.
// ex: writeMotor(0b0010, 0b1100); * @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) void writeMotor(uint8_t left, uint8_t right)
{ {
digitalWrite(IN4a, left & 0b1000); digitalWrite(IN4a, left & 0b1000);
@ -31,7 +43,10 @@ void writeMotor(uint8_t left, uint8_t right)
digitalWrite(IN1b, right & 0b0001); digitalWrite(IN1b, right & 0b0001);
} }
// Commande pour faire avancer le robot. /**
* @brief Commande pour faire avancer le robot.
*
*/
void forward() void forward()
{ {
writeMotor(0b1000, 0b0001); writeMotor(0b1000, 0b0001);
@ -44,7 +59,10 @@ void forward()
delay(DELAY_TIME); delay(DELAY_TIME);
} }
// Commande pour faire reculer le robot. /**
* @brief Commande pour faire reculer le robot.
*
*/
void backward() void backward()
{ {
writeMotor(0b0001, 0b1000); writeMotor(0b0001, 0b1000);
@ -57,7 +75,10 @@ void backward()
delay(DELAY_TIME); delay(DELAY_TIME);
} }
// Commande pour faire tourner le robot à droite. /**
* @brief Commande pour faire tourner le robot à droite.
*
*/
void right() void right()
{ {
writeMotor(0b1000, 0b1000); writeMotor(0b1000, 0b1000);
@ -70,7 +91,10 @@ void right()
delay(DELAY_TIME); delay(DELAY_TIME);
} }
// Commande pour faire tourner le robot à gauche. /**
* @brief Commande pour faire tourner le robot à gauche.
*
*/
void left() void left()
{ {
writeMotor(0b0001, 0b0001); writeMotor(0b0001, 0b0001);
@ -83,8 +107,11 @@ void left()
delay(DELAY_TIME); 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); writeMotor(0b0000, 0b0000);
} }

View file

@ -2,20 +2,36 @@
Utilitaires de conversions physique -> steps Utilitaires de conversions physique -> steps
*********************************************/ *********************************************/
// Convertit une longueur en cm vers un nombre de pas moteur. /**
// ex: * @brief Convertit une longueur en cm vers un nombre de pas moteur.
// float distance = 22.3; //cm *
// int steps = convertLengthToSteps(distance); * Exemple
* ```
* float distance = 22.3; //cm
* int steps = convertLengthToSteps(distance);
* ```
*
* @param length
* @return int
*/
int convertLengthToSteps(float length) int convertLengthToSteps(float length)
{ {
float result = length * 512 / (4 * 3.1415); float result = length * 512 / (4 * 3.1415);
return int(result); return int(result);
} }
// Convertit une rotation en degrés vers un nombre de pas moteur. /**
// ex: * @brief Convertit une rotation en degrés vers un nombre de pas moteur.
// float angle = 45; //deg *
// int steps = convertRotToSteps(angle); * 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 convertRotToSteps(int rotation)
{ {
int result = convertLengthToSteps(rotation * 3.1415 / 180 * 7.8); int result = convertLengthToSteps(rotation * 3.1415 / 180 * 7.8);

View file

@ -2,7 +2,10 @@
Configuration et handlers du server Configuration et handlers du server
************************************/ ************************************/
// Type de la variable globale command /**
* @brief Type de la variable globale command
*
*/
struct command_t struct command_t
{ {
bool running; // Une commande doit être exécutée bool running; // Une commande doit être exécutée
@ -11,7 +14,14 @@ struct command_t
int value; // Valeur (nombre de pas à effectuer) 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) void setGlobals(String commandName, float commandValue, command_t &globalCommand)
{ {
// Assert command before updating globals // 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) 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); 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) void serverConfig(AsyncWebServer &server, command_t &globalCommand)
{ {
server.on("/get", HTTP_GET, [&globalCommand](AsyncWebServerRequest *request) 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); }); 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) void connectWiFi(WiFiClass &WiFi)
{ {
// For simulator only // For simulator only