État du robot ============= **S'applique à :** :bdg-info-line:`Simulation` :bdg-warning-line:`Robot réel` Le paquet ``ratbot_status`` centralise l'état de santé du robot et le retour utilisateur : voyant RGB, sons, surveillance de la batterie et des températures, diagnostics ROS. .. note:: Sur le robot réel, le voyant correspond aux LED RGB de la carte et les sons aux buzzers. En simulation, le voyant est publié sous forme de marqueur affichable dans RViz. Le comportement et les topics sont identiques. États et couleurs ----------------- La liste complète des états — ce que chacun veut dire, sa couleur, sa mélodie, qui l'annonce — et la façon dont la carte et le Raspberry Pi se partagent le voyant sont expliquées dans :doc:`signaux`. Cette page-ci décrit le paquet lui-même. .. warning:: **Les trois canaux acceptent les nuances, mais pas de la même façon.** Rouge et vert sont modulés par une minuterie du microcontrôleur. Le bleu, lui, est sur une broche qui n'en a aucune : il est modulé par logiciel, cadencé par cette même minuterie. En pratique une palette se comporte comme attendu sur les trois canaux. La seule différence observable est que le bleu peut présenter une variation de luminosité infime lorsque la carte est très chargée — invisible à l'œil sur un voyant d'état. .. note:: Avant septembre 2026, le bleu était en tout-ou-rien : ``b: 0.5`` et ``b: 1.0`` donnaient exactement le même résultat. Si c'est ce que vous observez, la carte porte un firmware antérieur. Arbitrage --------- Plusieurs états peuvent être actifs simultanément ; un seul est affiché, le premier de la liste ``priority`` de ``led_states.yaml`` — voir :doc:`signaux`, section *Quand plusieurs états sont vrais en même temps*. L'arrêt de la manette étant mémorisé (QoS ``transient_local``), un voyant bloqué au rouge clignotant sans alarme indique qu'il n'a pas été levé : voir :doc:`arrets`. Lancement --------- .. tab-set:: :sync-group: env .. tab-item:: Simulation :sync: sim .. code-block:: bash ros2 launch ratbot_status status.launch.py robot_id:=1 .. tab-item:: Robot réel :sync: reel **Rien à lancer** : le service du robot démarre ``status_manager`` à la mise sous tension, et le relance s'il s'arrête. Ne pas le lancer une seconde fois : deux instances se disputeraient le voyant. En simulation, afficher le voyant dans RViz : *Add → By topic →* ``/ratbot_1/status/led_marker`` (type *Marker*). .. Capture d'écran à insérer : le voyant (Marker) coloré dans RViz. Déposez _static/statut/led-rviz.png puis décommentez le bloc ci-dessous (retirez le préfixe « .. » devant chaque ligne) : .. .. image:: _static/statut/led-rviz.png .. :align: center .. :width: 90% Piloter le voyant à la main --------------------------- Utile pour vérifier le câblage, comparer une couleur en simulation et sur le robot, ou simplement voir le voyant réagir. .. code-block:: bash ros2 topic pub --once /ratbot_1/status/led std_msgs/msg/ColorRGBA "{r: 1.0, g: 0.0, b: 0.0, a: 1.0}" # rouge ros2 topic pub --once /ratbot_1/status/led std_msgs/msg/ColorRGBA "{r: 0.0, g: 1.0, b: 0.0, a: 1.0}" # vert ros2 topic pub --once /ratbot_1/status/led std_msgs/msg/ColorRGBA "{r: 0.0, g: 0.0, b: 1.0, a: 1.0}" # bleu ros2 topic pub --once /ratbot_1/status/led std_msgs/msg/ColorRGBA "{r: 1.0, g: 1.0, b: 0.0, a: 1.0}" # jaune ros2 topic pub --once /ratbot_1/status/led std_msgs/msg/ColorRGBA "{r: 1.0, g: 1.0, b: 1.0, a: 1.0}" # blanc ros2 topic pub --once /ratbot_1/status/led std_msgs/msg/ColorRGBA "{r: 0.0, g: 0.0, b: 0.0, a: 1.0}" # eteint Et les quatre LED de façade, commandées par un masque binaire : .. code-block:: bash ros2 topic pub --once /ratbot_1/ui/leds std_msgs/msg/UInt8 "{data: 5}" # LED1 + LED3 ros2 topic pub --once /ratbot_1/ui/leds std_msgs/msg/UInt8 "{data: 15}" # les quatre ros2 topic pub --once /ratbot_1/ui/leds std_msgs/msg/UInt8 "{data: 0}" # eteintes .. important:: **Deux pièges de syntaxe**, qui produisent des erreurs déroutantes. **Le message doit être un seul argument entre guillemets**, en YAML sur une ligne, avec accolades et virgules. Écrire le message sur plusieurs lignes avec des ``\`` en fin de ligne ne marche pas : le shell recolle tout sans les retours à la ligne, et YAML reçoit ``r: 1.0g: 0.0b: 0.0`` — d'où un ``ScannerError: mapping values are not allowed here``, qui ne dit pas du tout que le problème vient du shell. **Ne pas oublier** ``--once``. Sans lui, ``ros2 topic pub`` republie indéfiniment à 1 Hz : le voyant reste figé sur la couleur demandée et ignore les changements d'état du robot, jusqu'à un Ctrl-C. .. tip:: **Vérifier le PWM.** Publier ``{r: 0.3, g: 0.0, b: 0.0, a: 1.0}`` doit donner un rouge visiblement plus faible que ``r: 1.0`` — c'est la preuve que la modulation fonctionne. Le même essai fonctionne sur le bleu : ``b: 0.3`` doit donner un bleu nettement plus faible que ``b: 1.0``. Si les deux se ressemblent, la carte porte un firmware antérieur à septembre 2026. Batterie -------- .. code-block:: bash ros2 topic echo /ratbot_1/sensors/battery Sous 20 % de charge, l'état ``low_battery`` est déclenché (voyant orange clignotant et son d'alerte). En simulation, la décharge est fonction du déplacement : le plugin de batterie de Gazebo consomme proportionnellement à l'effort moteur. Sur le robot réel, la mesure vient d'un pont diviseur lu par la carte, avec une précision d'environ **0,25 %** vérifiée au multimètre. Le champ ``percentage`` est une estimation **linéaire** entre 9,0 V (batterie vide) et 12,6 V (pleine charge) pour une 3S. .. note:: Cette estimation est volontairement grossière au milieu de la plage : la courbe de décharge d'une LiPo y est très plate, et aucune conversion simple n'y est fiable. Elle redevient significative **près du seuil bas**, là où la tension chute franchement — c'est-à-dire là où sert l'alerte. Pour un diagnostic précis, lire ``voltage`` plutôt que ``percentage``. Les champs ``current``, ``charge`` et ``capacity`` valent ``NaN`` : la carte mesure une tension, pas un courant, et annoncer ``0.0`` laisserait croire à une mesure réelle. Températures ------------ .. code-block:: bash ros2 topic echo /ratbot_1/sensors/temperature Deux mesures sont surveillées, avec des seuils distincts : la carte de contrôle (75 °C) et la Raspberry Pi (80 °C). Le dépassement de l'une ou l'autre déclenche ``overheat``. La température de la carte vient d'un TMP102 placé **entre les deux régulateurs** : c'est bien la température de l'électronique, pas celle de l'air ambiant. Elle est donc normalement supérieure de quelques degrés à la pièce. .. note:: En simulation, la température de la Raspberry n'est pas prise en compte pour le déclenchement : la valeur lue est celle de la machine de développement. Elle reste publiée dans les diagnostics à titre indicatif. Sons ---- Les mélodies vivent **dans la carte**, pas sur la Raspberry : ROS n'envoie qu'un numéro. Le robot reste donc capable d'émettre ses alertes même si la couche ROS est en difficulté. Personne n'a à connaître ces numéros : un programme annonce un **état**, et ``led_states.yaml`` choisit le son. Pour en écouter un directement : .. code-block:: bash ros2 topic pub --once /ratbot_1/status/sound std_msgs/msg/UInt8 "{data: 22}" # mission réussie ros2 topic pub --once /ratbot_1/status/sound std_msgs/msg/UInt8 "{data: 0}" # couper La table complète des numéros est dans la `page « Signaux » de la documentation développeur `_. Un numéro inconnu coupe le son en cours et est compté dans ``/diagnostics`` (bloc ``buzzer``, ``unknown_ids``). L'arrêt d'urgence du robot et la batterie critique n'ont **pas** de numéro : ils sonnent sur le buzzer d'alarme, que la carte commande seule. Diagnostics ----------- .. code-block:: bash ros2 topic echo /diagnostics ros2 topic echo /ratbot_1/status/state Comment les lire, bloc par bloc, et ce que veut dire chaque message : voir :doc:`diagnostics`. Configuration ------------- Le fichier ``ratbot_status/config/led_states.yaml`` définit les couleurs, les motifs (fixe, clignotant, alterné), les seuils et l'ordre de priorité. Aucune de ces valeurs n'est codée en dur. Des états supplémentaires peuvent y être déclarés, puis activés depuis n'importe quel nœud en publiant leur nom : .. code-block:: bash ros2 topic pub --once /ratbot_1/status/set_state std_msgs/msg/String "data: obstacle" L'état ``obstacle`` est fourni en exemple (alternance bleu/magenta). Le nœud émetteur n'a ainsi aucune connaissance de la représentation visuelle, définie uniquement dans la configuration. .. tip:: Un état activé par ``set_state`` expire après quelques secondes (``set_state_hold``). Pour le maintenir, le republier tant que la condition persiste.