Tutoriel : Collecte de Données

Bienvenue dans le guide opérationnel de la Phase 1. Cette documentation a pour vocation de faire le pont entre l'architecture logicielle (théorie) et la réalité du terrain (pratique).

Nous abandonnons ici les équations du MPC et les diagrammes de flux pour nous concentrer sur l'essentiel : Comment utiliser ces outils concrètement ? Ce manuel vous accompagnera de la compilation du workspace jusqu'à la génération de vos premiers Gigaoctets de données, en passant par la maîtrise du launcher unifié datarecord. Préparez votre terminal, nous passons en mode actif.

1. Préparation du Workspace

Avant de lancer quoi que ce soit, assurez-vous que votre environnement est prêt.

I. Installation du Package

Commencez par récupérer le code source du projet.

cd ~/ros2_ws/src
git clone https://gitlab.inria.fr/ia2vr/projets-iliar/2025-2026/boumeh.git
# Etablir le lien symbolique vers le package solution
ln -s boumeh/iliar_solution .

Pré-requis Gazebo

Nous supposons que vous disposez déjà du package iliar_gazebo installé et configuré dans votre ros2_ws/src. Sans lui, la simulation ne pourra pas se lancer.

II. Compilation

Chaque modification dans iliar_solution (code Python ou launch files) nécessite une recompilation pour être prise en compte par ROS 2.

cd ~/ros2_ws
colcon build --symlink-install

Pourquoi --symlink-install ?

Cette option crée des liens symboliques vers vos scripts Python. Cela signifie que si vous modifiez un fichier .py, vous n'aurez pas besoin de recompiler à chaque fois ! (Sauf pour les nouveaux fichiers ou les changements dans setup.py).

III. Sourcing

C'est l'étape que tout le monde oublie. Il faut dire à votre terminal où trouver vos paquets ROS.

source install/setup.bash

2. Le "Launcher" Unique

Pour simplifier le déploiement et éviter d'ouvrir 5 terminaux différents, nous avons condensé l'intégralité de la stack logicielle dans un unique point d'entrée : datarecord.launch.xml.

Ce fichier agit comme un chef d'orchestre qui synchronise et démarre automatiquement les briques suivantes :

L'environnement Virtuel : Lancement de Gazebo avec le circuit sélectionné
La Gestion du Robot : Apparition (Spawn) de la voiture au point de départ et publication des transformations géométriques (TF).
Le Cerveau (Contrôle) : Activation du nœud de pilotage choisi par l'utilisateur (Teleop manuel, PID ou MPC).
L'Interface (Visualisation) : Ouverture du Dashboard d'analyse temps réel et, si besoin, de Rviz.
L'Acquisition de Données : Démarrage du recorder binaire optimisé pour capturer le dataset si l'option est activée.

I. Tableau des Arguments

Vous pouvez modifier le comportement du système en passant des arguments à la commande ros2 launch. Voici la liste exhaustive des paramètres disponibles :

Catégorie	Argument	Valeur Défaut	Description
Général	`mode`	`teleop`	Mode de contrôle : `teleop`, `pid`, ou `mpc`.
	`circuit`	`circuit3.sdf`	Fichier du monde Gazebo (ex: `circuit2.sdf`).
	`record`	`true`	Active/Désactive l'enregistrement binaire (`.bin`).
	`dataset_path`	`~/iliardataset_rec`	Dossier racine pour les fichiers enregistrés.
	`spawn_car`	`true`	Faire apparaître la voiture (mettre `false` si déjà présente).
Limites	`max_steer`	`2.2`	Angle de braquage maximum (rad).
	`max_throttle`	`0.2`	Commande d'accélération maximale [0.0 - 1.0].
	`max_brake`	`5000.0`	Force de freinage maximale (Newton).
MPC	`mpc_speed`	`2.0`	Vitesse cible (m/s).
	`mpc_horizon`	`50`	Horizon de prédiction (nombre de pas).
	`mpc_dt`	`0.10`	Pas de temps du modèle (secondes).
	`mpc_offset`	`3.5`	Décalage latéral par rapport au centre de la piste (m).
	`mpc_wheelbase`	`2.7`	Empattement du véhicule (m).
	`mpc_debug`	`true`	Affiche les prédictions (ligne verte) dans Rviz/Dashboard.
PID	`pid_target_speed`	`2.0`	Vitesse cible pour le régulateur P (m/s).
	`pid_target_dist`	`3.5`	Distance cible au centre de la route (m).
	`pid_kp`	`-0.4`	Gain proportionnel (Volant).
	`pid_kd`	`-1.2`	Gain dérivé (Volant).
	`pid_ki`	`0.0`	Gain intégral (Volant).
Joystick	`joy_axis_steer`	`0`	Index axe volant (défaut: stick gauche H).
	`joy_axis_throttle`	`1`	Index axe gaz (défaut: stick gauche V).
	`joy_btn_deadman`	`0`	Bouton sécurité "Homme mort" (défaut: A).
	`joy_btn_drive`	`3`	Bouton passage Drive (défaut: Y).
	`joy_btn_reverse`	`1`	Bouton passage Marche Arrière (défaut: B).

3. Guide Pratique des Modes

Au lieu de vous donner des recettes toutes faites, nous allons explorer les modes un par un. Le premier, et le plus critique pour valider votre installation, est le mode manuel.

A. Mode Teleop

C'est votre point de départ. Il permet de vérifier que la chaîne d'infrastructure (ROS 2 -> Launch -> Gazebo -> Voiture) est fonctionnelle avant de laisser l'IA prendre le volant.

I. Pré-requis : Driver Joystick

Pour piloter la voiture, vous avez besoin d'une manette (Xbox filaire recommandée) et des paquets ROS 2 adéquats.

Installation des Drivers

Assurez-vous d'avoir installé le paquet joy standard de ROS 2 ainsi que les drivers Linux :

sudo apt install ros-jazzy-joy joystick xboxdrv

Note : Si votre manette n'est pas détectée, le paquet xboxdrv résout souvent le problème.

II. Commande de Lancement

Pour être explicite et ne rien laisser au hasard, voici la commande complète incluant tous les paramètres qui influencent le mode Teleop :

ros2 launch iliar_solution datarecord.launch.xml \
    mode:=teleop \
    record:=true \
    dataset_path:=/home/$USER/iliardataset_rec \
    circuit:=circuit3.sdf \
    spawn_car:=true \
    joy_axis_steer:=0 \
    joy_axis_throttle:=1 \
    joy_btn_deadman:=0 \
    joy_btn_drive:=3 \
    joy_btn_reverse:=1

À propos des arguments par défaut

La commande ci-dessus est verbeuse volontairement pour vous montrer ce qui est configurable. En pratique, la plupart de ces valeurs sont déjà définies par défaut (default=... dans le launch file). Vous pouvez donc souvent raccourcir la commande en : ros2 launch iliar_solution datarecord.launch.xml mode:=teleop

III. Debugging Manette

Si la voiture ne bouge pas alors que le simulateur tourne : 1. Vérifiez que le terminal affiche bien des logs joystick. 2. Dans un nouveau terminal, inspectez les données brutes :

ros2 topic echo /joy

Appuyez sur les touches pour identifier les bons index (axes/buttons) et mettez à jour votre commande si besoin.

Manette

B. Mode PID

Le PID n'est pas intelligent, mais il est rigoureux. Il nous sert de "Baseline" : c'est le niveau minimum de performance que notre IA devra battre. Il utilise une simple erreur de distance latérale (CTE) pour tourner le volant.

I. Pré-requis

Le fonctionnement du PID repose sur les nœuds dist_to_path et path_publisher. Ces derniers calculent l'erreur latérale (CTE) en se basant sur une librairie géométrique fournie par le professeur : geom2d.

Téléchargez la librairie ICI.

Installez-la dans votre environnement (via pip) :

# Supposons que l'archive est dans ~/Downloads
cd ~/Downloads
unzip geom2d.zip
cd geom2d
pip install .

Bug Connu : Module Not Found

Si malgré l'installation, ROS ne trouve pas la librairie, c'est souvent dû à l'option --symlink-install qui masque certains chemins Python. La solution est de recompiler votre workspace "normalement" :

cd ~/ros2_ws
colcon build
source install/setup.bash

II. Commande de Lancement

Pour lancer une session de collecte avec le PID, voici la commande exposant tous les gains réglables :

ros2 launch iliar_solution datarecord.launch.xml \
    mode:=pid \
    record:=true \
    dataset_path:=/home/$USER/iliardataset_rec \
    circuit:=circuit3.sdf \
    pid_target_speed:=2.5 \
    pid_target_dist:=3.5 \
    pid_kp:=-0.4 \
    pid_kd:=-1.2 \
    pid_ki:=0.0

Attention aux Oscillations

Si vous augmentez trop la vitesse (pid_target_speed), le PID risque de devenir instable et d'osciller de gauche à droite. C'est normal : c'est un contrôleur réactif qui ne voit pas les virages arriver (contrairement au MPC). Conseil : Pour un dataset propre, gardez une vitesse modérée (2.0 - 2.5 m/s).

C. Mode MPC

Le Model Predictive Control (MPC) est le joyau de cette stack. Contrairement au PID qui réagit à l'erreur présente, le MPC anticipe le futur. Il résout en temps réel un problème d'optimisation pour trouver la trajectoire parfaite qui respecte les contraintes physiques du véhicule. C'est ce mode que vous devez utiliser pour générer des données d'entraînement de haute qualité ("Expert Demonstrations").

I. Pré-requis : Scipy

Notre solveur utilise scipy. Assurez-vous qu'il est présent :

pip install scipy

II. Commande de Lancement

Voici la commande pour un run "Expert" destiné au dataset :

ros2 launch iliar_solution datarecord.launch.xml \
    mode:=mpc \
    record:=true \
    dataset_path:=/home/$USER/iliardataset_rec \
    circuit:=circuit3.sdf \
    mpc_speed:=3.0 \
    mpc_horizon:=50 \
    mpc_dt:=0.1 \
    mpc_debug:=true

Comprendre l'Horizon

L'argument mpc_horizon (50) avec mpc_dt (0.1s) signifie que l'IA "voit" 5 secondes dans le futur (\(50 \times 0.1s\)). C'est cette capacité d'anticipation qui lui permet de prendre les virages serrés à haute vitesse sans sortir de la route, là où le PID échouerait.

Arrêt d'Urgence (Solver Fail)

Si la voiture freine brutalement ("Safety Brake Triggered"), ce n'est pas un bug mais une sécurité. Cela signifie que le MPC n'a trouvé aucune trajectoire physiquement possible pour négocier le virage à la vitesse actuelle. Au lieu de tenter l'impossible et de sortir de la route, il préfère s'arrêter. Solution : Réduisez mpc_speed ou augmentez l'horizon.

Tuning Expert : Les Poids (Weights)

Vous remarquerez dans le code Python (mpc.py) des variables comme self.w_cte, self.w_epsi, self.w_delta... Ce sont les Poids de la Fonction de Coût. Ils déterminent la "personnalité" de la conduite (agressive vs douce).

Ces valeurs ont été minutieusement réglées ("Fine-Tuned") pour fonctionner de manière robuste sur l'ensemble des 9 circuits du projet. Bien qu'il soit techniquement possible de les modifier dans le code, nous vous le déconseillons fortement : un mauvais réglage peut rendre le contrôleur instable partout. C'est une recette de chef : ne changez pas les ingrédients si vous ne connaissez pas la chimie ! 🧪

4. Astuces & Troubleshooting

1. "La voiture ne bouge pas !"

Si en mode Teleop : Avez-vous maintenu le bouton de sécurité (Deadman) ? le noeud joy est lancé ?
Si en mode MPC : Regardez le terminal. Si vous voyez "Solver Failed" ou des erreurs rouges, le problème vient de l'optimiseur.

2. "Probleme de stockage"

Le format binaire est optimisé, mais :

Un chunk de 500 frames fait environ 20-30 Mo.
Une minute d'enregistrement (20Hz) = 1200 frames = ~70 Mo.
Assurez-vous d'avoir quelques Go de libres avant de lancer une "night run".

3. Visualiser l'enregistrement

Pour vérifier ce que vous avez enregistré, n'essayez pas d'ouvrir le fichier .bin avec un éditeur de texte ! Utilisez les notebooks de la Phase 2 pour charger et visualiser les chunks.

Prêt pour l'Entraînement ?

Si vous avez réussi à générer des fichiers .bin avec le mode MPC, félicitations ! Vous possédez maintenant la matière première (le dataset). Rendez-vous à la Phase 2 pour transformer ces données en intelligence. 🧠