Guide complet pour le débogage étape par étape d'un code Arduino

Je possède beaucoup de robots ! Et la plupart d'entre eux sont contrôlés par une carte Arduino.

Le développement sur la plateforme Arduino, bien que passionnant, n'est pas exempt de défis. L'IDE Arduino 1.x n'est pas incroyable et le second fait un peu l'effet d'un VSCode au rabais. Dans un cas comme dans l'autre, l'un de leurs nombreux soucis est l'absence de débogueur simple. Au cours de la programmation d'un projet, et plus celui-ci se complexifie, les erreurs peuvent survenir à tout moment et les identifier efficacement est une compétence essentielle pour tout développeur Arduino. La méthode classique et la plus simple ? L'envoi d'information textuelle sur le port série et l'utilisation du moniteur comme écran de débogage. Évidemment, suivre l'exécution d'une boucle ou d'un code complexe devient vite difficile, et il n'est pas possible d'arrêter le programme au moment opportun pour en étudier l'état interne.

Serial.println("jusqu'ici tout va bien !");

C'est une autre approche que je vous propose au cours de cet article : le débogage pas-à-pas.

La méthode que je vais vous montrer est compatible avec de nombreuses cartes programmables. Je l'utilise personnellement avec tout type de carte Arduino (nano, uno, mega, etc..) mais avec un peu d'adaptation, elle fonctionnerait également avec des cartes esp ou autres. Nous allons, autant que possible, utiliser des outils gratuits (ou pour quelques euros en fin d'article) afin que la méthode convienne aux hobbyistes.

Quel que soit votre logiciel de programmation : Arduino IDE, CLion, VSCode, etc.., il possède nécessairement des outils d'aide au débogage. Ceux-ci peuvent être plus ou moins puissants, plus ou moins complexe à mettre en œuvre, ou nécessiter plus ou moins de matériel.

La méthode que je vous propose utilise l'IDE gratuit PlatformIO. L'outil est gratuit et open-source. Il est multi-platforme (windows, linux, mac, etc..), multi-architecture (x32, x64, ARM, etc..), multi-framework (Arduino, ESP, Simba, etc...) et construit sur la base de VSCode. Bref, c'est l'IDE parfait pour la programmation de système embarqué en C/C++… ou presque.

Son installation est simple : rendez-vous sur le lien https://platformio.org/platformio-ide et laissez-vous guider.

Je vous laisse quelques minutes pour installer l'IDE, et je vous retrouve dès que c'est fait ! ☕︎

La méthode "classique" ou à l'ancienne que beaucoup pratiquent pour déboguer le code précédent est l'utilisation du port série et du moniteur série pour transférer et afficher des informations de debug. Ici, ce serait la valeur de la variable counter que nous souhaiterions connaître.
La méthode à l'ancienne consistera donc à initialiser le port série dans la méthode setup(), puis à envoyer la valeur du counter dans la méthode loop() selon le code ci-dessous:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#include <Arduino.h>
 
uint8_t counter = 0;
 
void setup() {
  Serial.begin(9600);
  pinMode(LED_BUILTIN, OUTPUT);
}
 
void blink() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(100);
  digitalWrite(LED_BUILTIN, LOW);
  delay(100);
}
 
void loop() {
  if (counter < 300) {
    blink();
  }
  counter++;
  Serial.println(counter);
}

Je vous invite à tester en déployant le code selon la méthode précédente (Ctrl+F5), puis en ouvrant le moniteur série :

1. Cliquer sur l'icône PlatformIO: Serial monitor en forme de prise électrique, dans la barre d'icone en bas d'écran.
2. Cliquer sur l'onglet Serial Monitor dans la fenêtre ainsi ouverte.
3. Cliquer enfin sur le bouton Start monitoring.

Je sais que je parle (ou écris) beaucoup, mais enfin nous y sommes : voyons une méthode plus adaptée.

La première chose à faire, va être de configurer notre logiciel pour le debug :

• Ouvrir le fichier platformio.ini qui se trouve à la racine du projet.
• Modifier le fichier pour que son contenu soit le suivant :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[env:default]
platform = atmelavr
framework = arduino
 
; Compatible boards with the debugger:
;  https://docs.platformio.org/en/stable/plus/debug-tools/avr-stub.html#boards
board = nanoatmega328
; board = uno
; board = megaatmega2560
 
; Configure debugger tool
debug_tool = avr-stub
debug_port = COM3
 
; GDB stub implementation
lib_deps = 
  jdolinay/avr-debugger

Ce fichier configure le comportement de PlatformIO pour notre projet.

1. La première ligne indique un début de section. Nous configurons ici l'environnement par défaut, c'est à dire que notre projet se comportement pareil dans toutes les conditions. Il est toutefois possible de configurer un comportement ou des settings différents selon que l'on veuille faire du debug ou une compilation pour release, mais aussi selon la carte avec laquelle on souhaite travailler. Il est donc possible de complexifier ces configurations pour par exemple tester notre code simultanément sur deux cartes différentes connectés sur des ports différents de l'ordinateur.
   Plus d'infos : https://docs.platformio.org/en/latest/projectconf/sections/env/index.html
2. Les deux lignes suivantes définissent la plateforme et le framework, c'est à dire le toolchain de compilation utilisée. En deux mots, la compilation transforme notre code C++ en code spécifique au microcontrôleur cible, ici des cartes arduino dont le processeur est de la famille des AVR. C'est donc cette plateforme la cible.
3. Nous définissons ensuite la carte qui sera utilisé. Là encore, parce que chaque carte a un processeur différent ainsi que des spécificités matérielles, il nous faut être précis. Notre compilateur supporte un très grand nombre de carte, mais le débogueur un peu moins. (cf point 4)
4. Voici le moment de configurer le débogueur. Nous utiliserons ici avr-stub qui est spécifique aux processeurs de la famille des AVRs. Ce débogueur supporte un nombre limité d'architecture, de framework et de cartes (en fait toutes les cartes de type Arduino)
   Plus d'infos : https://docs.platformio.org/en/stable/plus/debug-tools/avr-stub.html
5. Nous indiquons ensuite le port de debug. Notez que cette ligne est optionnelle si une seule carte Arduino est branchée à l'ordinateur : PlatformIO saura la détecter.
6. Finalement, nous incluons une dépendance à la librarie jdolinay/avr-debugger. Vous constatez ici la magie de PlatformIO qui va se charger tout seul de trouver, télécharger, compiler et lier cette librairie au projet ! Cette librairie contient le code Arduino permettant à notre carte de dialoguer avec le débogueur via le port série.

Une fois fait, il nous reste à changer quelques détails dans notre code : nous allons repartir de notre premier jet, sans le debug Serial. Il conviendra alors d'ajouter :

• Deux #include en début de fichier (mais après celui d'<Arduino.h> permettant d'utiliser la librairie de debug à notre code
• L'appel à la méthode debug_init() en début du setup().

Voici le code ainsi obtenu :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#include <Arduino.h>
#include "avr8-stub.h"
#include "app_api.h"
 
uint8_t counter = 0;
 
void setup() {
  debug_init();
  pinMode(LED_BUILTIN, OUTPUT);
}
 
void blink() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(100);
  digitalWrite(LED_BUILTIN, LOW);
  delay(100);
}
 
void loop() {
  if (counter < 300) {
    blink();
  }
  counter++;
}

Tout est prêt pour le grand moment, celui qui nous retourne généralement le cerveau la première fois que l'on découvre le debug pas-à-pas 🤯.

Revenons un peu en arrière : au paragraphe Tentative de debug à l'ancienne, j'ai énuméré plusieurs inconvénients liés à l'utilisation du port série pour le débogage. J'espère à présent avoir réussi à vous persuader de l'intérêt d'un "vrai" débogueur pas à pas. Cependant, nous n'avons pas encore abordé le dernier point de la liste d'inconvénient, à savoir, comment utiliser la liaison série tout en déboguant notre programme simultanément. Car oui, cela est bel et bien possible ! 🤯

J'en suis désolé d'avance, mais pour bien comprendre, nous allons devoir évoquer des sujets un peu techniques.

Concrètement, pour communiquer avec l'extérieur, les cartes Arduino disposent de divers protocoles de communications - peut-être ces noms vous diront quelques choses : SPI, I2C, UART, etc...

Intéressons-nous plus spécifiquement au protocole UART. C'est un protocole de communication de type série nécessitant 2 câbles, appelés RX et TX. RX réceptionne les informations, tandis que le câble TX les transmet. En branchant le câble RX d'un appareil compatible UART au câble TX d'un autre et vice-versa, ces deux appareils se retrouvent capable d'échanger ensemble dans les deux sens, via ce protocole.

Pour uploader votre programme dans votre carte arduino, vous branchez certainement celle-ci au port USB de votre ordinateur. Concrètement, votre carte arduino possède un convertisseur UART-USB intégré sur ses broches 0 et 1. C'est également ces broches 0 et 1 qui sont utilisées par la bibliothèque Serial lorsque l'on écrit Serial.begin(). C'est également ces broches qui sont aussi utilisées par défaut par avr-debugger. Il n'est pas possible d'utiliser simultanément cette connectique UART0 (broche 0 et 1) pour deux usages différents et simultanés, par exemple la bibliothèque Serial et avr-debugger. Toute l'astuce réside donc dans le fait de trouver un autre couple de broche permettant une liaison UART. Plusieurs possibilités s'offre à nous :

1. Utiliser d'autres broches pour l'upload du code Arduino. C'est théoriquement possible quoi que compliqué. En effet, l'usage des broches 0 et 1 comme support UART pour l'upload du code est ancré au plus profond de la carte Arduino dans le bootloader. Il faudrait donc hacker celui-ci (c'est à dire le modifier) puis flasher la carte selon une procédure spécifique, la rendant inutilisable par la voie classique (branchée en USB). C'est une piste que je déconseille.
2. Utiliser un autre couple de broche pour le transfert de donnée via Serial. Là, c'est tout à fait possible.
   1. Certaines cartes - comme la Arduino Méga - possède plusieurs connexions UART, ainsi les broches 14 à 18 peuvent être utilisées par couple UART1, UART2 et UART3. Ces couples sont standards sur la carte et la bibliothèque Serial comme la bibliothèque avr-debugger sont capables de les utiliser.
   2. Il est aussi possible de simuler logiciellement une connexion série via la bibliothèque SoftwareSerial.
3. Dans tous les cas, un convertisseur UART-USB supplémentaire sera nécessaire pour se connecter également à l'ordinateur via cette seconde liaison série. Cela peut être fait de deux façons :
   1. Via l'achat d'un convertisseur UART-USB externe. N'importe lequel de n'importe quelle marque est utilisable, même les moins chers à 1€10 sur AliExpress !
   2. Via l'usage d'une seconde carte Arduino (peu importe laquelle) pour laquelle on utilisera son convertisseur intégré aux broches 0 et 1.
4. Dans tous les cas, le débogage peut être confiée à une carte spécialisée de type JTAG compatible avec votre carte Arduino. Ces outils sont en revanche chers et spécifiques à chaque type de carte, c'est une solution à laisser aux professionnels et dont les hobbyistes peuvent se passer.

Simuler un port série

Afin de libérer le port USB (UART0) pour l'usage exclusif du débogueur, il est possible de simuler la liaison série logiciellement via l'usage de la librairie SoftwareSerial. Je n'entrerais pas ici dans les détails car en effet cet article commence à être très long et il traite plus du debug que de la programmation arduino.

Utiliser le port UART1 pour la liaison série

Alternativement à la solution précédente et en supposant que vous utilisiez une carte Arduino Méga, il est possible de remplacer simplement le code classique de votre communication série (c'est à dire le mot clef Serial) par Serial1 pour le port UART1 (broches 18 et 19), par Serial2 (broches 16 et 17) ou encore Serial3 (broches 14 et 15). Là encore, c'est hors du scope de cet article et je vous invite à consulter la documentation.

Utiliser avr-debugger sur UART1

Passons à présent sur une carte Arduino Méga, présentant l'avantage d'avoir nativement plusieurs broches compatibles UART. Nous allons devoir modifier notre fichier platformio.ini comme suit :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[env:default]
platform = atmelavr
board = megaatmega2560
framework = arduino
 
; Configure upload tool
upload_port = COM3
 
; Configure debugger tool
; TX(uart)<->RX(arduino) and RX(uart)<->TX(arduino)
; PIN depends on the UART number used
debug_tool = avr-stub
debug_port = COM4
build_flags = -DAVR8_UART_NUMBER=1
 
; GDB stub implementation
lib_deps =
  jdolinay/avr-debugger

Les différences avec le fichier précédent sont :

• Le changement de la carte board qui passe à un Arduino Méga
• L'introduction de la configuration upload_port : il permet de définir le port série utilisé pour l'upload du code, c'est à dire le port USB sur lequel est branché notre arduino.
• Une nouvelle configuration build_flags qui permet d'ajouter des flags à la compilation. Ici, nous utilisons -DAVR8_UART_NUMBER à la valeur 1, qui permet à avr-debugger d'utiliser le port UART1 (broches 18 et 19) de notre carte.
• Notez que le port debug_port est différent de upload_port et nous devrons utiliser un convertisseur UART-USB depuis les broches 18 et 19 de notre carte, vers ce port USB COM4 de notre ordinateur.

Utiliser un convertisseur UART-USB

Maintenant que notre configuration est prête, nous pouvons à présent réutiliser le code du paragraphe Tentative de debug à l'ancienne pour utiliser à la fois le débogueur pas à pas et notre port série avec le moniteur. Il nous reste simplement à trouver comme relier les broches 18 et 19 de l'UART1 de notre Arduino Méga à l'ordinateur. Pour cela, il nous faut un convertisseur UART-USB. Ceux-ci se présentent généralement sous la forme d'un câble (TTL-USB) ou d'une carte (UART-USB) avec d'un côté un port USB mâle à brancher à l'ordinateur et de l'autre côté des broches ou des câbles Dupont. Il conviendra alors de relier :

• RX de la carte, avec TX (pin 18) de l'arduino
• TX de la carte avec RX (pin 19) de l'arduino
• le GND de la carte au GND de l'arduino
• laissez le +5V de la carte non connecté, en effet dans notre exemple, l'alimentation de votre arduino se fait déjà par le port série classique

Utiliser un arduino comme convertisseur UART-USB

Supposons que l'on souhaite utiliser un arduino nano comme convertisseur UART-USB. Il convient alors de brancher les broches UART de notre arduino méga à déboguer sur les broches UART0 (broches 0 et 1) de l'arduino nano, puis de brancher celui-ci à l'ordinateur. Afin d'éviter d'utiliser réellement cet arduino et pour n'utiliser que le convertisseur UART-USB intégré, nous devons shunter - ou court-circuiter en quelque sorte - le microcontrôleur de la carte en branche le RESET au GND. Récapitulons :

• RX de la carte arduino à déboguer sur la broche 1 de l'arduino de conversion
• TX de la carte arduino à déboguer sur la broche 0 de l'arduino de conversion
• RESET de la carte arduino de conversion sur le GND de cette même carte
• (optionnel) j'aurais tendance à vous conseiller de connecter également les GND des deux cartes ensemble

Une fois ces ajustements fait, le reste du debug se déroule comme précédemment : utilisez le raccourci F5, et c'est parti !