formation-arduino/modules/04-serie-debug.qmd

---
title: "Module 4 — Communication série & débogage"
---

## Objectifs du module

- Comprendre le fonctionnement du bus UART et son rôle central dans le débogage.
- Distinguer les différents ports série disponibles sur l'ESP32-S3.
- Utiliser efficacement le moniteur série et les fonctions d'affichage formaté.
- Construire une petite console de commandes interactive.

## 1. Rappel : qu'est-ce que l'UART ?

L'UART (Universal Asynchronous Receiver-Transmitter) est un protocole de communication série point à point utilisant deux fils : TX (transmission) et RX (réception), sans horloge partagée — les deux extrémités doivent donc être configurées à la même vitesse (baud rate) pour interpréter correctement les bits reçus.

![Trame UART 8N1 : envoi du caractère « A » (0x41)](../schemas/svg/m04-trame-uart.svg){#fig-m04-trame-uart}

Sur l'ESP32-S3, la liaison série vers l'ordinateur (moniteur série de l'IDE) transite le plus souvent directement par le port USB natif du microcontrôleur (USB CDC), et non par un UART matériel classique relié à une puce USB-série externe — d'où l'importance de l'option « USB CDC On Boot » vue au Module 0.

## 2. Les ports série disponibles

L'ESP32-S3 dispose de plusieurs contrôleurs UART matériels, utilisables simultanément pour des usages différents (ex : un port pour le debug, un autre pour dialoguer avec un module GPS ou un lecteur RFID).

| Objet | Usage typique |
|---------|----------------------------------------|
| Serial | Console USB (moniteur série / debug), via USB CDC sur l'ESP32-S3 |
| Serial1 | UART matériel n°1, broches à réassigner explicitement |
| Serial2 | UART matériel n°2, broches à réassigner explicitement |

::: {.callout-note title="Réassignation des broches UART"}
Sur l'ESP32-S3, les broches des UART matériels ne sont pas fixes : on les définit avec Serial1.begin(baud, config, rxPin, txPin). Vérifiez que les broches choisies ne font pas partie des broches à éviter identifiées au Module 1.
:::

```cpp
// Exemple : Serial2 sur les broches GPIO17 (RX) et GPIO18 (TX)
#define RX2 17
#define TX2 18

void setup() {
  Serial.begin(115200);           // console USB
  Serial2.begin(9600, SERIAL_8N1, RX2, TX2); // module externe
}

void loop() {
  if (Serial2.available()) {
    String recu = Serial2.readStringUntil('\n');
    Serial.print("Recu du module: ");
    Serial.println(recu);
  }
}
```

![Deux liaisons série simultanées : Serial vers l'ordinateur, Serial2 vers un module (TX et RX croisés)](../schemas/svg/m04-cablage-serie.svg){#fig-m04-cablage-serie}

## 3. Bien utiliser le moniteur série

### 3.1 Fonctions d'affichage

| Fonction | Rôle |
|-----------------------|----------------------------------------|
| `Serial.print(x)` | Affiche x sans retour à la ligne |
| `Serial.println(x)` | Affiche x avec un retour à la ligne |
| Serial.printf(fmt, ...) | Affichage formaté façon C (%d, %s, %f, %.2f...) |

```cpp
int temperature = 24;
float tension = 3.298;

Serial.printf("Temperature: %d C, Tension: %.2f V\n", temperature, tension);
```

::: {.callout-tip title="Bonne pratique de debug"}
Préférez `Serial.printf()` à la concaténation de multiples `Serial.print()` : le code est plus lisible et plus facile à maintenir, surtout lorsqu'on affiche plusieurs variables à la fois.
:::

## 4. Lire des données envoyées depuis le moniteur série

Le moniteur série permet aussi d'envoyer du texte vers la carte, ce qui est très utile pour créer des interfaces de test simples (changer un paramètre sans reflasher le programme).

```cpp
void setup() {
  Serial.begin(115200);
  Serial.println("Tapez une commande puis Entree");
}

void loop() {
  if (Serial.available()) {
    String commande = Serial.readStringUntil('\n');
    commande.trim();  // supprime espaces/retours de fin
    Serial.print("Commande recue: ");
    Serial.println(commande);
  }
}
```

## 5. Exercice pratique : mini console de commandes

En vous appuyant sur la LED NeoPixel du Module 2, développez une petite console pilotée par le moniteur série :

- La commande « rouge » allume la LED en rouge.
- La commande « vert » l'allume en vert.
- La commande « bleu » l'allume en bleu.
- La commande « off » l'éteint.
- Toute commande inconnue affiche un message d'erreur explicite.

```cpp
#include <Adafruit_NeoPixel.h>
#define NEOPIXEL_PIN 48
Adafruit_NeoPixel pixel(1, NEOPIXEL_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  Serial.begin(115200);
  pixel.begin();
  Serial.println("Commandes disponibles: rouge, vert, bleu, off");
}

void loop() {
  if (Serial.available()) {
    String cmd = Serial.readStringUntil('\n');
    cmd.trim();
    cmd.toLowerCase();

    if (cmd == "rouge") {
      pixel.setPixelColor(0, pixel.Color(255, 0, 0));
    } else if (cmd == "vert") {
      pixel.setPixelColor(0, pixel.Color(0, 255, 0));
    } else if (cmd == "bleu") {
      pixel.setPixelColor(0, pixel.Color(0, 0, 255));
    } else if (cmd == "off") {
      pixel.setPixelColor(0, pixel.Color(0, 0, 0));
    } else {
      Serial.println("Commande inconnue.");
      return;
    }
    pixel.show();
    Serial.println("OK");
  }
}
```

## 6. Pour aller plus loin (facultatif)

Ajoutez une commande « couleur R G B » qui accepte trois nombres séparés par des espaces (ex : couleur 128 0 255) en utilisant les fonctions `indexOf()` et `substring()` ou la fonction `sscanf()` pour extraire les valeurs de la chaîne reçue.

## Checklist de fin de module

- [ ] Je comprends la différence entre Serial, Serial1 et Serial2.
- [ ] Je sais réassigner les broches RX/TX d'un UART matériel.
- [ ] Je maîtrise `Serial.printf()` pour un affichage de debug formaté.
- [ ] J'ai réalisé la mini console de commandes pilotant la LED NeoPixel.