Robo-Pointer Visuel (SO-ARM100 / LeRobot)

Demo Quickstart (1 page)

Objectif: lancer la chaîne vision → contrôleur bras → interface moteurs, observer les topics, et enregistrer un bag de 20–30 s pour rejouer.

1. Build + source (si nécessaire)

cd ~/ros2_ws
colcon build --packages-select robo_pointer_visual
source ~/ros2_ws/install/setup.bash

2. Lancer la pipeline bras (YOLO → controller → interface)

Option A — Script mock (recommandé pour la démo)

# lance vision + contrôleur + interface mock, puis vérifie les topics
scripts/mock_demo.sh               # auto: yolov8n.pt et /dev/video0
# monitoring 1‑fenêtre (taux + statut):
source scripts/env.sh && python3 scripts/live_status.py

Option B — Commande launch directe

ros2 launch robo_pointer_visual pipeline.launch.py \
  yolo_model:=/home/benja/ros2_ws/yolov8n.pt \
  camera_index:=/dev/video0 \
  target_class_name:=bottle \
  publish_rate_hz:=15.0 \
  leader_arm_port:=/dev/ttyACM0

Mode offline (sans interface matérielle):

ros2 launch robo_pointer_visual pipeline.launch.py \
  yolo_model:=/home/benja/ros2_ws/yolov8n.pt camera_index:=/dev/video0 \
  enable_interface:=false

Mode mock (offline complet, simulation de /joint_states):

ros2 launch robo_pointer_visual pipeline.launch.py \
  yolo_model:=/home/benja/ros2_ws/yolov8n.pt camera_index:=/dev/video0 \
  interface_type:=mock

Vitesse simulée par articulation (deg/s) — exemples:

ros2 param set /mock_robot_interface sim_speed_deg_s.pan 90.0
ros2 param set /mock_robot_interface sim_speed_deg_s.lift 60.0
ros2 param set /mock_robot_interface sim_speed_deg_s.elbow 60.0
ros2 param set /mock_robot_interface sim_speed_deg_s.wrist 120.0

3. Activer le PID (optionnel, à chaud)

ros2 param set /robot_controller_node use_pid_control true
# Ajuster si besoin (exemples) :
ros2 param set /robot_controller_node kp_pan 0.006
ros2 param set /robot_controller_node kd_pan 0.001
ros2 param set /robot_controller_node kp_vert 0.004
ros2 param set /robot_controller_node kd_vert 0.0015

3bis) Sécurité et stabilité (optionnel)

• Réduire le micro‑tremblement près du centre:

ros2 param set /robot_controller_node dead_zone_px 12   # 8..16 recommandé

• Comportement si la cible disparaît (retour sécurité vers la pose initiale après un délai):

ros2 param set /robot_controller_node no_detection_behavior home
ros2 param set /robot_controller_node no_detection_timeout_s 4.0   # 3..5 s

4. Ce que l’on doit voir

• /image_debug (bounding boxes) via rqt_image_view
• /detected_target_point (Point) ≈ 10–20 Hz
• /joint_states et /target_joint_angles stables

Commandes utiles:

# Utiliser le wrapper CLI propre pour éviter les conflits conda/ROS
scripts/ros2_cli.sh topic hz /detected_target_point
scripts/ros2_cli.sh topic hz /target_joint_angles
scripts/ros2_cli.sh topic echo /detected_target_point --once
scripts/ros2_cli.sh topic list | rg 'joint_states|target_joint_angles'
scripts/ros2_cli.sh topic echo /detection_acquired --once
scripts/ros2_cli.sh topic echo /detection_area --once

5. Charger des profils de démo (optionnel)

# Profil mock recommandé (PID ON, dead-zone 12, homing):
ros2 param load /robot_controller_node install/robo_pointer_visual/share/robo_pointer_visual/config/demo_mock.yaml

# Profil réel (PID OFF au démarrage, vitesses conservatrices):
ros2 param load /robot_controller_node install/robo_pointer_visual/share/robo_pointer_visual/config/demo_real.yaml

6. Enregistrer un bag (20–30 s)

ros2 bag record -O follower_arm_demo \
  /image_debug /detected_target_point /joint_states /target_joint_angles
# Stopper l’enregistrement après 20–30 secondes (Ctrl+C)

7. Rejouer le bag (test offline du contrôleur)

Cas A — Relecture des topics pour inspection:

ros2 bag play follower_arm_demo --loop
ros2 topic hz /detected_target_point

Cas B — Rejouer et lancer seulement le contrôleur bras:

# Terminal 1: rejouer le bag (fournit /detected_target_point et /joint_states)
ros2 bag play follower_arm_demo

# Terminal 2: lancer le contrôleur seul (PID activé)
ros2 run robo_pointer_visual robot_controller_node --ros-args -p use_pid_control:=true

8. Vérifications TF et diag (optionnel)

• Pour visualiser les TF en RViz: ros2 launch so100_description display.launch.py
• Echo TF (si robot_state_publisher lancé):

ros2 run tf2_ros tf2_echo base_link wrist_link

Plan B (si instable): documenter l’état atteint, enregistrer quand même un bag (20–30 s) et une courte vidéo (60–90 s).

Ce projet vise à contrôler un bras robotique SO-ARM100 (version LeRobot/Hugging Face) à l'aide d'une caméra montée sur le poignet ("eye-in-hand") pour détecter et suivre un objet via YOLOv8 (Ultralytics). Il s'agit d'un projet personnel d'apprentissage dans le cadre d'une reconversion vers la robotique logicielle.

Objectif Principal : Implémenter un système de visuo-servage simple mais fonctionnel en utilisant ROS 2 Humble, Python et OpenCV.

État Actuel (Branche main) :

• L'architecture ROS 2 (3 nœuds principaux) est en place et communique.
• Détection d’objet via YOLOv8 (Ultralytics) fonctionnelle (GPU si dispo, sinon CPU; FP16 sur CUDA).
• Interface bas niveau avec les moteurs Feetech (scservo_sdk + lerobot) établie, utilisant GroupSyncRead/GroupSyncWrite.
• Calibration manuelle des moteurs via un fichier JSON.
• Cinématique Directe (FK) et Inverse (IK) (2R) pour l’élévation (épaule/coude).
• Contrôleur bras: P/PID optionnel, dead‑zone, vitesse limitée, homing en absence prolongée de cible.
• Interface robot réelle (Feetech) et mode mock (offline end‑to‑end).

---

Table des Matières

• Matériel Requis

• Logiciels Requis

• Installation

  • 1. Cloner le Dépôt
  • 2. Environnement Conda
  • 3. Installer LeRobot
  • 4. Workspace ROS 2
  • 5. Calibration Manuelle (Crucial !)
  • 6. Règles Udev (Recommandé)
  • 7. Permissions

• Utilisation

• Structure du Projet

• Prochaines Étapes

• Licence

• Contact

• Dépôt Matériel SO-ARM100

---

Matériel Requis

• Bras Robotique SO-ARM100 (version LeRobot/Hugging Face avec moteurs Feetech STS3215)
• Adaptateur U2D2 ou interface similaire pour les moteurs Feetech
• Caméra USB (testé avec Innomaker 1080P)
• Alimentation 5 V, ~5 A pour les moteurs
• Objet rouge vif pour la détection
• PC sous Ubuntu 22.04

Logiciels Requis

• Ubuntu 22.04 LTS
• ROS 2 Humble Hawksbill (ros-humble-desktop)
• Miniconda ou Anaconda
• Git
• Tmux

Installation

1. Cloner le Dépôt

# Adaptez ~/ros2_ws si votre workspace est ailleurs
git clone https://github.com/bkoensgen/robo-pointer-so100.git ~/ros2_ws/src/robo-pointer-so100

2. Environnement Conda

# Si vous n'avez pas déjà l'environnement de LeRobot
# conda create -n lerobot python=3.10
conda activate lerobot

3. Installer LeRobot

# Adaptez ~/lerobot si vous l'avez cloné ailleurs
git clone https://github.com/huggingface/lerobot.git ~/lerobot
cd ~/lerobot
pip install -e .
cd -  # Retour au dossier précédent

4. Workspace ROS 2

cd ~/ros2_ws
# Construire seulement ce package
colcon build --packages-select robo_pointer_visual
# Ou simplement `colcon build` pour tout reconstruire

Puis, ajoutez dans votre ~/.bashrc si ce n’est pas déjà fait :

source ~/ros2_ws/install/setup.bash

5. Calibration Manuelle (Crucial !)

• Créez le fichier ~/.cache/lerobot/calibrations/so100/main_follower.json
• Contient motor_names, homing_offset, drive_mode, calib_mode, etc.
• homing_offset = inverse des steps bruts mesurés au point zéro physique.
• drive_mode typique : [0,1,0,0,1,0] pour [Pan,Lift,Elbow,WristFlex,WristRoll,Gripper].
• Inspirez-vous de la calibration automatique de lerobot, mais mesurez et corrigez manuellement.
• Créez les dossiers si nécessaire :

mkdir -p ~/.cache/lerobot/calibrations/so100

6. Règles Udev (Recommandé)

Créez /etc/udev/rules.d/99-robot-devices.rules :

# Feetech U2D2 Adapter
SUBSYSTEM=="tty", ATTRS{product}=="*U2D2*", ATTRS{serial}=="YOUR_U2D2_SERIAL", SYMLINK+="robot_arm", MODE="0666"

# USB Camera (Exemple générique)
SUBSYSTEM=="video4linux", KERNEL=="video[0-9]*", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", ATTRS{serial}=="CAMERA_SERIAL", SYMLINK+="robot_camera", MODE="0666"

Rechargez les règles :

sudo udevadm control --reload-rules && sudo udevadm trigger

7. Permissions

Ajoutez votre utilisateur aux groupes :

sudo usermod -aG dialout $USER
sudo usermod -aG video  $USER

Important : déconnectez-vous puis reconnectez-vous pour que les changements prennent effet.

Utilisation

Rendez le script de lancement exécutable et lancez-le :

chmod +x ~/ros2_ws/scripts/start_robot.sh
cd ~/ros2_ws
# Mode réel (par défaut):
./scripts/start_robot.sh [nano|medium|large]

# Mode mock (offline complet):
./scripts/start_robot.sh mock [nano|medium|large]

Le script crée une session tmux nommée robot_dev avec trois panneaux :

1. vision_node
2. robot_controller_node
3. real_robot_interface (logs en ~/real_robot_interface_test1.log)

Commandes tmux utiles :

• Détacher : Ctrl+b puis d
• Ré-attacher : tmux attach -t robot_dev
• Tuer la session : tmux kill-session -t robot_dev

Structure du Projet

Le dossier ~/ros2_ws/src/robo_pointer_visual/robo_pointer_visual/ contient :

• vision_node.py : acquisition d’image, détection couleur, publication.
• robot_controller_node.py : calcul d’erreur visuelle, publication signal P.
• real_robot_interface.py : interface moteurs Feetech, calibration, FK/IK, contrôleurs PI, GroupSyncWrite.
• kinematics.py : fonctions FK/IK 2-DOF.
• start_robot.sh : script de lancement.

Prochaines Étapes

• Ajuster les gains PI locaux (épaule ID 2) pour stabiliser le contrôle vertical.
• Explorer une compensation de gravité explicite (URDF ou manuelle).
• Affiner les gains globaux pour un suivi fluide.
• Améliorer la détection visuelle.
• Nettoyer le code et la documentation.
• Ajouter des tests automatisés.
• Créer des démonstrations visuelles.

Licence

Sous licence Apache 2.0. Voir le fichier LICENSE.

Contact

Benjamin Koensgen – benjamin.koensgen@gmail.com LinkedIn : linkedin.com/in/benjamin-koensgen

Dépôt Matériel SO-ARM100

Pour la documentation et les fichiers CAD/URDF du SO-ARM100 (et SO-101), consultez également : https://github.com/TheRobotStudio/SO-ARM100