Tutoriel - STM32_WifiESP

1. Introduction

STM32_WifiESP permet d’ajouter facilement une connectivité WiFi, un serveur web, du MQTT et la synchronisation NTP à n’importe quel projet STM32, en utilisant un module ESP01 (ESP8266 en mode AT) et l’USART DMA. La librairie est conçue pour être simple à intégrer et modulaire.

2. Architecture détaillée du driver STM32_WifiESP

Le driver STM32_WifiESP est organisé en modules indépendants : chaque fonctionnalité (WiFi, HTTP, MQTT, NTP) possède son propre fichier source et header. Le module principal (STM32_WifiESP) gère l’initialisation, la communication bas niveau (USART/DMA) et les utilitaires communs. Vous pouvez n’inclure que les modules nécessaires à votre application.

Exemple d’utilisation typique

1. Initialisation : Appel à esp01_init() pour initialiser le driver avec l’USART, le DMA et les buffers.
2. Connexion WiFi : Utilisation des fonctions du module WIFI pour se connecter à un réseau.
3. Serveur web ou MQTT : Démarrage du serveur HTTP ou du client MQTT selon le besoin.
4. Ajout de routes ou de callbacks : Ajout de routes HTTP personnalisées ou de callbacks MQTT pour gérer les interactions.

3. Prérequis et compatibilité

4. Configuration de la communication avec l'ESP01

Pour utiliser le module ESP01, il faut configurer l'USART et le DMA dans STM32CubeMX (fichier .ioc).

Voici les paramètres recommandés pour l'USART :

Si on souhaite modifier les pins par défaut de l'USART, il faut le faire avant d'activer l'USART dans CubeMX.

On active ensuite l'USART dans CubeMX, on laisse les paramètres par défaut.

• Baudrate : 115200
• Data bits : 8
• Stop bits : 1
• Parity : None
• Flow control : None

Pour le DMA, on configure l'USART1 RX avec les paramètres suivants :

• DMA Request : RX
• Mode : Circular
• Data width : Byte
• Priority : Medium
• Direction : Peripheral to Memory

5. Montage matériel STM32 & ESP01

Le module ESP01 fonctionne en 3,3V et n’est pas tolérant au 5V. Il est donc indispensable d’utiliser un STM32 en 3,3V. Voici deux exemples de montage :

Vérifiez toujours la tension de fonctionnement de votre carte STM32 : un branchement direct en 5V sur l’ESP01 l'endommagerait définitivement.

6. Fichiers de la librairie

• STM32_WifiESP.h/.c : Driver bas niveau (USART, AT, debug, reset, helpers génériques)
• STM32_WifiESP_WIFI.h/.c : Fonctions WiFi haut niveau (scan, connexion, DHCP, IP, etc.)
• STM32_WifiESP_HTTP.h/.c : Serveur web HTTP, parsing, routage, réponses
• STM32_WifiESP_MQTT.h/.c : Client MQTT (connexion, publish, subscribe, callback)
• STM32_WifiESP_NTP.h/.c : Synchronisation NTP, gestion date/heure

7. Installation et Intégration

1. Créez un dossier nommé STM32_WifiESP dans le répertoire Drivers de votre projet STM32 et copiez-y les fichiers STM32_WifiESP.h et STM32_WifiESP.c.
2. Ajoutez les chemins d'inclusion : dans les propriétés de votre projet STM32CubeIDE, dans C/C++ General, > Paths and Symbols > Onglet Includes, dans GNU ajoutez le chemin vers le dossier STM32_WifiESP.

N'oublier pas d'activer le float dans les propriétés du projet pour afficher le nombres flottants dans le printf et scanf si besoin.

8. Fonctionnalités par module

• Bas niveau : Initialisation, reset, logs, gestion du buffer DMA, envoi de commandes AT, helpers de parsing et conversion.
• WiFi : Scan réseaux, connexion/déconnexion, DHCP, IP, MAC, RSSI, hostname, ping, état TCP/IP.
• HTTP : Serveur web multi-route, parsing requêtes, routage, réponses HTML/JSON, statistiques, gestion des connexions.
• MQTT : Connexion broker, publication, abonnement, ping, callback messages, gestion du client MQTT.
• NTP : Configuration serveur NTP, synchronisation automatique, parsing date/heure, gestion DST.

9. Debug et bonnes pratiques

• Activez #define ESP01_DEBUG 1 dans STM32_WifiESP.h pour les logs USART
• Libérez toujours les buffers alloués par esp01_send_raw_command_dma (sauf si la fonction s’en occupe déjà)
• Utilisez les fonctions de parsing fournies pour éviter les erreurs de formatage
• Testez les fonctions de base avant d’intégrer des fonctionnalités avancées

10. Exemples et tests fournis

• Test_Driver.c : Test des fonctions bas niveau (AT, reset, logs, RAM, etc.).
• Test_Module_WIFI_(AP).c : Test complet du mode Point d’Accès WiFi.
• Test_Module_WIFI_(STA).c : Test complet du mode Station WiFi.
• Test_Serveur_WEB.c : Démonstration serveur web multi-route.
• Test_Send_MQTT.c : Publication MQTT.
• Test_Receive_MQTT.c : Réception MQTT (abonnement/callback).
• Test_NTP.c : Synchronisation NTP.
• Test_Terminal AT.c : Terminal AT interactif.

11. Liste des fonctions utilisateurs du cœur du driver

11.1. Fonctions principales (initialisation, gestion du module, buffer, etc.)

                            
/**
 * @brief  Initialise le driver ESP01 (UART, DMA, buffers, test communication).
 * @param  huart_esp   UART utilisé pour l'ESP01
 * @param  huart_debug UART pour debug (logs)
 * @param  dma_rx_buf  Buffer DMA RX
 * @param  dma_buf_size Taille du buffer DMA
 * @retval ESP01_Status_t Code de statut (OK, erreur, etc.)
 */
esp01_init(UART_HandleTypeDef *huart_esp, UART_HandleTypeDef *huart_debug, uint8_t *dma_rx_buf, uint16_t dma_buf_size);
                            
                        

/**
 * @brief  Vide le buffer RX UART (DMA).
 * @param  timeout_ms Timeout en ms
 * @retval ESP01_Status_t
 */
esp01_flush_rx_buffer(uint32_t timeout_ms);

/**
 * @brief  Envoie une commande AT brute via DMA et attend un motif.
 * @param  cmd         Commande AT à envoyer
 * @param  resp        Buffer de réponse
 * @param  resp_size   Taille du buffer réponse
 * @param  wait_pattern Motif à attendre dans la réponse
 * @param  timeout_ms  Timeout en ms
 * @retval ESP01_Status_t
 */
esp01_send_raw_command_dma(const char *cmd, char *resp, size_t resp_size, const char *wait_pattern, uint32_t timeout_ms);

11.2. Wrappers exposant une commande AT à l’utilisateur (et helpers associés)

Chaque wrapper correspond à une commande AT ou à une fonctionnalité du module ESP01, et dispose d’un programme de test dédié dans Test_Driver.c. Ce fichier permet de valider individuellement chaque commande, de visualiser les réponses et de s’assurer du bon fonctionnement du driver sur votre matériel.

11.3. Terminal / console AT

Le programme de test Test_Terminal AT.c permet d’interagir en direct avec le module ESP01 : il est idéal pour tester manuellement n’importe quelle commande AT, observer le retour brut du module, et ainsi affiner ou développer les fonctions de parsing adaptées. C’est un outil précieux pour le debug, l’exploration des réponses et la validation des nouveaux wrappers ou helpers.

/**
 * @brief  Initialise le terminal AT interactif sur l'UART de debug.
 * @param  huart_debug UART utilisé pour la console PC
 */
void esp01_terminal_begin(UART_HandleTypeDef *huart_debug);

/**
 * @brief  Callback appelée à la réception d’un caractère sur la console.
 * @param  huart UART de la console
 */
void esp01_console_rx_callback(UART_HandleTypeDef *huart);

/**
 * @brief  Tâche principale du terminal AT, à appeler en boucle.
 */
void esp01_console_task(void);

11.4. Helpers (conversion, affichage, formatage humain)

Ces fonctions utilitaires facilitent la conversion, l’affichage ou le formatage des données (par exemple : taille mémoire, valeurs numériques, etc.). Elles évitent de réécrire du code déjà existant et permettent de garder une cohérence dans la présentation des informations, tout en respectant la philosophie DRY (Don’t Repeat Yourself) de la librairie.

• char *esp01_format_size(size_t bytes, char *output, size_t size);

11.5. Outils de parsing

Ces fonctions servent à extraire facilement des valeurs (entiers, chaînes, booléens) depuis les réponses AT ou les buffers. Elles sont conçues pour éviter les erreurs de parsing et accélérer le développement, en réutilisant des routines fiables et testées.

• ESP01_Status_t esp01_parse_int_after(const char *text, const char *pattern, int32_t *result);
• ESP01_Status_t esp01_parse_string_after(const char *text, const char *pattern, char *output, size_t size);
• bool esp01_extract_quoted_value(const char *src, const char *motif, char *out, size_t out_len);
• ESP01_Status_t esp01_parse_bool_after(const char *resp, const char *tag, bool *out);
• uint8_t esp01_split_response_lines(const char *input_str, char *lines[], uint8_t max_lines, char *lines_buffer, size_t buffer_size, bool skip_empty);

11.6. Outils utilitaires (buffer, inline, validation)

Ces utilitaires regroupent des fonctions d’aide pour la gestion des buffers, la validation des pointeurs, la copie sécurisée de chaînes, etc. Leur usage permet d’éviter les bugs classiques (dépassement de buffer, pointeur NULL…) et d’écrire un code plus sûr et maintenable, toujours dans l’esprit de réutilisation et de robustesse de la librairie.

• const char *esp01_get_error_string(ESP01_Status_t status);
• ESP01_Status_t esp01_wait_for_pattern(const char *pattern, uint32_t timeout_ms);
• void _esp_trim_string(char *str);
• static inline ESP01_Status_t esp01_safe_strcpy(char *dst, size_t dst_size, const char *src);
• static inline ESP01_Status_t esp01_check_buffer_size(size_t needed, size_t avail);
• static inline bool esp01_is_valid_ptr(const void *ptr);
• static inline ESP01_Status_t esp01_safe_strcat(char *dst, size_t dst_size, const char *src);

12. Détail des modules fonctionnels

ESP01_Status_t esp01_connect_wifi_config(ESP01_WifiMode_t mode, const char *ssid, const char *password, bool use_dhcp, const char *ip, const char *gateway, const char *netmask);

ESP01_Status_t esp01_get_ip_config(char *ip_buf, size_t ip_len, char *gw_buf, size_t gw_len, char *mask_buf, size_t mask_len);

ESP01_Status_t esp01_set_ap_config(const char *ssid, const char *password, uint8_t channel, uint8_t encryption, uint8_t max_conn, uint8_t ssid_hidden);

ESP01_Status_t esp01_list_ap_stations(esp01_ap_station_t *stations, uint8_t max_stations, uint8_t *found);

ESP01_Status_t esp01_ap_disconnect_all(void);
ESP01_Status_t esp01_ap_disconnect_station(const char *mac);

ESP01_Status_t esp01_get_rssi(int *rssi);

ESP01_Status_t esp01_parse_cwlap_line(const char *line, esp01_network_t *network);
ESP01_Status_t esp01_network_to_string(const esp01_network_t *net, char *buf, size_t buflen);

ESP01_Status_t esp01_parse_cwjap_response(const char *resp, char *ssid, size_t ssid_size, char *bssid, size_t bssid_size, uint8_t *channel, int *rssi, uint8_t *enc_type);

const char *esp01_encryption_to_string(int code);
const char *esp01_rf_power_to_string(int rf_dbm);

ESP01_Status_t esp01_http_init(void);

void esp01_http_loop(void);

ESP01_Status_t esp01_add_route(const char *path, esp01_route_handler_t handler);

ESP01_Status_t esp01_parse_http_request(const char *raw_request, http_parsed_request_t *parsed);

ESP01_Status_t esp01_send_http_response(int conn_id, int status_code, const char *content_type, const char *body, size_t body_len);

ESP01_Status_t esp01_send_json_response(int conn_id, const char *json_data);

ESP01_Status_t esp01_send_404_response(int conn_id);

void esp01_clear_routes(void);

int esp01_get_active_connection_count(void);
bool esp01_is_connection_active(int conn_id);

ESP01_Status_t esp01_mqtt_connect(const char *broker_ip, uint16_t port, const char *client_id, const char *username, const char *password);

ESP01_Status_t esp01_mqtt_publish(const char *topic, const char *message, uint8_t qos, bool retain);

ESP01_Status_t esp01_mqtt_subscribe(const char *topic, uint8_t qos);

void esp01_mqtt_set_message_callback(mqtt_message_callback_t cb);

void esp01_mqtt_poll(void);

ESP01_Status_t esp01_mqtt_ping(void);

ESP01_Status_t esp01_mqtt_disconnect(void);

ESP01_Status_t esp01_set_ntp_server(const char *server, int timezone, int dst);

ESP01_Status_t esp01_get_ntp_config(char *server, size_t server_len, int *timezone, int *dst);

ESP01_Status_t esp01_sync_time(void);

ESP01_Status_t esp01_get_time(esp01_time_t *time, bool local_time);

ESP01_Status_t esp01_parse_time_response(const char *resp, esp01_time_t *time);

const char *esp01_ntp_config_to_string(const char *server, int timezone, int dst, char *buf, size_t buflen);