# Suivi de la MAIN — natif, à bord (découverte du 2026-08-30)

> **Annexe publiée par explorations360** — extrait de nos notes techniques,
> relevé sur firmware 2.5.5 le 30 août 2026. Projet indépendant, sans lien ni
> affiliation avec Hengbot. Deux sections internes (intégration du kit et
> fichiers de travail) ont été retirées de cette version publique.


## TL;DR
Le robot sait suivre une **main** nativement, sans aucun contrôleur externe.
Le nœud ROS embarqué `face_tracker` gère déjà deux cibles (visage ET main).
Il suffit de lui publier une chaîne sur son canal de contrôle :

```bash
# passer en suivi de MAIN
ros2 topic pub --once /face_tracker/control std_msgs/msg/String '{data: follow_hand}'
# revenir au suivi de VISAGE
ros2 topic pub --once /face_tracker/control std_msgs/msg/String '{data: follow_face}'
```

Résultat : suivi **fluide et robuste**, à bord, sans latence réseau, via la
cinématique/servo native. Testé OK sur firmware 2.5.5.

> Conséquence : tout le pilotage du suivi depuis le PC en WebSocket (filtre de Kalman,
> compensation caméra, modèle de retard servo) est **superflu**. On le garde
> comme référence pédagogique, mais le produit c'est la bascule native.

## Le nœud natif `face_tracker`
Binaire : `/root/sirius_ros2/install/face_tracking/lib/face_tracking/face_tracker`

Abonnements (entrées) :
- `/face_detection/roi`  `ai_msgs/msg/Roi`  — boîte VISAGE
- `/hand_detection/roi`  `ai_msgs/msg/Roi`  — boîte MAIN
- `/face_tracker/control`  `std_msgs/msg/String` — commande de mode

Publications (sorties, consommées par `sirius_motion_control_node`) :
- `/face_tracker/head_pose_channel1`  `geometry_msgs/msg/Point`
- `/face_tracker/body_pose_channel1`  `geometry_msgs/msg/Point`

Les boîtes `/hand_detection/roi` sont publiées en continu par le nœud
`face_detection_bridge` (format `ai_msgs/msg/Roi` : `type: hand`, `rect`
{x_offset, y_offset, width, height, do_rectify}, `confidence`).

## Chaînes de contrôle reconnues (extraites du binaire)
- `follow_hand`  — suivre la main
- `follow_face`  — suivre le visage
- `enable` / `disable` — activer / désactiver le suivi

## Paramètres réglables (ros2 param set /face_tracker <p> <v>)
Valeurs par défaut relevées sur 2.5.5 (déjà bien réglées — le suivi est « nickel » d'origine) :
- `body_head_ratio = 0.4`        — couplage corps/tête (le torse prend 40 % du mouvement ; confirme notre mesure ~0,34-0,4)
- `max_face_jump_distance = 1000`— anti-téléportation (rejet des sauts de cible, en px)
- `face_lost_threshold = 1.0`    — seuil de perte de cible (s)
- `initial_track_factor = 0.3`   — réactivité initiale
Autres paramètres exposés : `yaw_scale`, `pitch_scale` (amplitude par axe),
`interpolation_factor`, `interpolation_update_rate` (lissage servo),
`track_ramp_duration`, `reset_head_duration`, `reset_body_duration`,
`reset_head_start_ratio`.

## Accès ROS depuis une session SSH sur le robot
Le CLI `ros2` doit rejoindre le graphe avec le bon environnement DDS :
```bash
export ROS_DOMAIN_ID=33 ROS_LOCALHOST_ONLY=1 \
       CYCLONEDDS_URI=file:///root/cyclonedds.xml \
       RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
source /opt/ros/humble/setup.bash
source /root/sirius_ros2/install/setup.bash
```
(sans ça, `ros2 topic list` renvoie un graphe vide et `!rclpy.ok()`.)

## Calibration caméra (mesurée, pour référence)
Décalage image par rotation de tête (visage immobile, angles commandés) :
- **K_yaw   = +394 px/rad**
- **K_pitch = −431 px/rad**
(utile si un jour on refait de l'asservissement visuel côté PC ; le natif, lui,
connaît sa pose de tête et compense tout seul.)