Monter un projet FreeRTOS + micro-ROS

Comment le projet firmware a été mis en place, et comment le refaire de zéro sur un STM32H750VBT6. Utile si vous repartez d’un .ioc neuf, ou si vous voulez comprendre d’où viennent les réglages que CubeMX ne sait pas exprimer.

Note

Pour utiliser le firmware existant — le compiler, le flasher, le déboguer — vous n’avez pas besoin de cette page. Voir Bootloader et exécution depuis la flash externe et Architecture de l’application firmware.

Les quatre étapes :

créer le projet CubeMX ;
intégrer le module micro-ROS ;
programmer la carte ;
lancer l’agent micro-ROS.

1. Créer le projet CubeMX

A. File -> New Project, cible STM32H750VBT6.

B. System Core -> RCC -> High Speed Clock (HSE) : sélectionner Crystal/Ceramic Resonator.

C. System Core -> SYS -> Timebase Source : choisir TIM6.

C’est obligatoire : FreeRTOS s’approprie le SysTick, et laisser la HAL dessus crée un conflit silencieux.

D. System Core -> RTC : activer l’horloge temps réel.

Warning

Le quartz LSE 32,768 kHz de cette carte (CL = 7 pF, HC-49S miniature) ne démarre qu’en drive MEDIUMHIGH. CubeMX n’a aucune case pour ce réglage sur H7 : il doit être posé dans le code, et il saute à chaque régénération. Voir Bootloader et exécution depuis la flash externe, section Les réglages effacés par CubeMX.

Ne jamais armer le CSS du LSE sur cette carte : erratum ES0396 §2.2.19.

E. Connectivity -> SPI1 -> Mode : Full-Duplex Master. C’est le bus de la flash de données U7, celle qui porte la configuration et le journal de bord.

F. Connectivity -> USB_OTG_FS -> Mode : Device_Only, puis activer USB On The Go FS global interrupt dans NVIC Settings.

G. Middleware -> FREERTOS : interface CMSIS_V2.

H. Middleware -> FREERTOS -> Configuration -> Tasks and Queues : ajouter une tâche avec une pile d’au moins 3000 mots, soit 12 Ko. La pile FreeRTOS se compte en mots de 4 octets, pas en octets — l’erreur est facile et ne se voit qu’au débordement.

I. Middleware -> USB_DEVICE : Communication Device Class (Virtual Port Com).

J. Activer la configuration DEBUG pour pouvoir utiliser le ST-LINK.

K. Régler l’arbre d’horloge.

L. Déclarer les GPIO, les timers, les UART dont le projet a besoin.

M à O. Project Manager -> Project : choisir l’emplacement, puis IDE/Toolchain. Le projet RatBot utilise un Makefile.

2. Intégrer le module micro-ROS

1. Cloner micro_ros_stm32cubemx_utils dans le répertoire du projet.

2. Se placer sur la branche correspondant à votre distribution :

cd micro_ros_stm32cubemx_utils
git checkout humble      # Ubuntu 22.04  (jazzy sur 24.04)

3. Ajouter ceci à la fin du Makefile :

#######################################
# micro-ROS addons
#######################################
LDFLAGS += micro_ros_stm32cubemx_utils/microros_static_library/libmicroros/libmicroros.a
C_INCLUDES += -Imicro_ros_stm32cubemx_utils/microros_static_library/libmicroros/microros_include

C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/custom_memory_manager.c
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_allocators.c
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_time.c

# Le transport : UN SEUL des trois
C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_transports/dma_transport.c
#C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_transports/it_transport.c
#C_SOURCES += micro_ros_stm32cubemx_utils/extra_sources/microros_transports/usb_cdc_transport.c

print_cflags:
     @echo $(CFLAGS)

Important

Le RatBot utilise ``dma_transport``, sur UART5 à 3 Mbaud (connecteur J1 vers la Raspberry). Les tutoriels génériques proposent usb_cdc_transport, pratique sur un bureau mais inutilisable sur un robot autonome : la liaison passerait par le port de débogage.

Le fichier de transport du projet est d’ailleurs modifié : la HAL traite toute erreur de réception comme bloquante, et sans correctif la carte reste sourde jusqu’au chien de garde. Voir Communication avec la carte STM32, section Robustesse de la liaison.

4. Construire la bibliothèque statique, depuis la racine du projet :

docker pull microros/micro_ros_static_library_builder:humble
docker run -it --rm -v $(pwd):/project \
    --env MICROROS_LIBRARY_FOLDER=micro_ros_stm32cubemx_utils/microros_static_library \
    microros/micro_ros_static_library_builder:humble

L’outil affiche les CFLAGS qu’il reprend du projet ; s’ils apparaissent, c’est bon signe.

Note

Les limites du client (nombre de publishers, de services, de handles d’exécuteur) se règlent dans un colcon.meta avant cette étape, et il faut reconstruire la bibliothèque à chaque changement. Voir Communication avec la carte STM32, section Limites du client micro-ROS.

3. Programmer la carte

Sur ce microcontrôleur, l’application ne tient pas dans la flash interne de 128 Ko : elle vit dans la flash QSPI externe et s’y exécute en place. La procédure complète — bootloader, external loader, et le piège du reset matériel — est dans Bootloader et exécution depuis la flash externe.

Le débordement de DTCMRAM

Erreur fréquente à la première compilation d’un projet micro-ROS :

La section .bss est placée par défaut en DTCMRAM, qui ne fait que 128 Ko. Une pile micro-ROS la remplit aussitôt. Il faut la déplacer vers la RAM principale dans le fichier .ld :

.bss :
{
   _sbss = .;
   __bss_start__ = _sbss;
   *(.bss)
   *(.bss*)
   *(COMMON)
   . = ALIGN(4);
   _ebss = .;
   __bss_end__ = _ebss;
} >RAM                    /* et non >DTCMRAM */

Warning

Sur le RatBot, le placement mémoire va plus loin : les tampons DMA doivent être hors DTCMRAM — le DMA n’y a pas accès — et dans une région non cacheable, sans quoi le cœur lit du cache périmé. Le tas de micro-ROS doit rester hors de cette zone. Voir Architecture de l’application firmware, section MPU et caches.

4. Lancer l’agent micro-ROS

L’agent fait le pont entre la carte et le reste du graphe ROS 2.

Sur le robot

Rien à installer : il est lancé par systemd, et la commande manuelle est

./scripts/ratbot agent

Voir Bringup.

Sur une machine de développement

Si vous n’avez pas ROS 2 installé, un conteneur suffit. Le script setup_agent.sh crée un espace de travail partagé, installe micro_ros_setup dans le conteneur, construit l’agent et le lance.

./setup_agent.sh

Une fois l’agent en route, la carte doit apparaître :

ros2 node list          # /ratbot_1/ratbot_controller
ros2 topic hz /ratbot_1/base/odom

Si rien n’apparaît, vérifier dans l’ordre : le ROS_DOMAIN_ID (77 sur le parc, figé dans le firmware), le périphérique série, et la vitesse de la liaison.

Voir aussi

Bootloader et exécution depuis la flash externe — programmer la carte, et l’exécution depuis la flash QSPI.
Architecture de l’application firmware — l’architecture des tâches, MPU et caches.
Communication avec la carte STM32 — le transport, ses limites et sa robustesse.