Interface ROS 2
===============

**S'applique à :** :bdg-info-line:`Simulation` :bdg-warning-line:`Robot réel`

Cette page décrit ce qu'un programme voit du robot : les topics à publier pour
le commander, ceux à lire pour connaître son état, et les services. Tous sont
des types ROS 2 **standards** : un programme n'a besoin d'aucun paquet du
RatBot pour piloter ou observer un robot.

Les noms sont donnés **relativement à l'espace de noms du robot** :
``base/cmd_vel`` désigne ``/ratbot_1/base/cmd_vel`` pour le robot 1. Seuls les
noms commençant par ``/`` sont absolus.

Commander le robot
------------------

Le point d'entrée est ``base/cmd_vel`` (``geometry_msgs/Twist``) :

.. code-block:: bash

   ros2 topic pub /ratbot_1/base/cmd_vel geometry_msgs/msg/Twist \
      "{linear: {x: 0.1}, angular: {z: 0.0}}"

``linear.x`` est la vitesse d'avance, en m/s ; ``angular.z`` la vitesse de
rotation, en rad/s, positive vers la gauche. Les autres champs ne s'appliquent
pas à une base différentielle et sont ignorés.

.. warning::

   ``ros2 topic pub`` publie en continu : le robot roule jusqu'à ``Ctrl+C``.
   Inversement, un programme doit **republier** sa consigne régulièrement : la
   carte du robot arrête les moteurs une demi-seconde après la dernière
   commande reçue.

La chaîne de commande
~~~~~~~~~~~~~~~~~~~~~

Les commandes n'atteignent pas directement les moteurs. Elles traversent trois
étages :

::

   base/cmd_vel_teleop  (priorité 100) ┐
   base/cmd_vel         (priorité 50)  ┼─► twist_mux ─► limiteur ─► garde-barrière ─► moteurs
   base/cmd_vel_nav     (priorité 10)  ┘

**Arbitrage** (``twist_mux``)
   Retient la source active la plus prioritaire : la manette et le clavier
   (``cmd_vel_teleop``) l'emportent sur les programmes (``cmd_vel``), qui
   l'emportent sur la navigation autonome (``cmd_vel_nav``). Une source est
   considérée inactive une demi-seconde après son dernier message.

**Limiteur**
   Plafonne la vitesse à 0,18 m/s et 1,5 rad/s, quelles que soient les valeurs
   demandées. Réglage : ``ratbot_bringup/config/velocity_limits.yaml``.

**Garde-barrière**
   Force la commande à zéro tant que l'arrêt de flotte est actif. Placé en
   dernier, aucun autre étage ne peut l'adoucir.

Un programme publie sur ``base/cmd_vel``, en tête de chaîne : il bénéficie
ainsi des protections. Les topics situés en aval ne doivent pas être publiés
directement.

Lire l'état du robot
--------------------

.. list-table::
   :header-rows: 1
   :widths: 30 32 38

   * - Topic
     - Type
     - Contenu
   * - ``base/odom``
     - ``nav_msgs/Odometry``
     - odométrie des roues seules, **sans fusion**
   * - ``odometry/filtered``
     - ``nav_msgs/Odometry``
     - odométrie **fusionnée** roues + gyroscope
   * - ``base/joint_states``
     - ``sensor_msgs/JointState``
     - position et vitesse de chaque roue
   * - ``scan``
     - ``sensor_msgs/LaserScan``
     - mesures du lidar
   * - ``sensors/tof/depth``
     - ``sensor_msgs/Image``
     - capteur de distance avant : 8 × 8 distances en millimètres, 0 = pas de
       mesure (voir :doc:`tof`)
   * - ``sensors/tof/points``
     - ``sensor_msgs/PointCloud2``
     - les mêmes en points 3D, le sol posé à hauteur nulle
   * - ``sensors/tof/clearing``
     - ``sensor_msgs/PointCloud2``
     - rayons d'effacement du capteur de distance (Nav2 seulement) : tout le
       champ, jusqu'à la mesure ou jusqu'à 1,5 m
   * - ``sensors/imu/data_raw``
     - ``sensor_msgs/Imu``
     - accélérations et vitesses angulaires de la centrale
   * - ``sensors/battery``
     - ``sensor_msgs/BatteryState``
     - état de la batterie
   * - ``sensors/temperature``
     - ``sensor_msgs/Temperature``
     - température de la carte
   * - ``status/emergency_stop``
     - ``std_msgs/Bool``
     - ``true`` tant que le bouton d'arrêt du robot est enfoncé, ou que son
       arrêt n'a pas été réarmé. L'arrêt automatique n'y figure pas : il se lit
       dans les diagnostics, bloc ``motion guard``
   * - ``/diagnostics``
     - ``diagnostic_msgs/DiagnosticArray``
     - santé détaillée du robot (voir :doc:`diagnostics`)

Les deux « odom »
~~~~~~~~~~~~~~~~~

Le mot désigne trois choses, source fréquente de malentendus :

.. list-table::
   :header-rows: 1
   :widths: 30 16 54

   * - Nom
     - Nature
     - Contenu
   * - ``base/odom``
     - topic
     - odométrie des roues **brute**, publiée par la carte du robot
   * - ``odometry/filtered``
     - topic
     - fusion des roues et du gyroscope, par ``robot_localization``
   * - ``ratbot_N/odom``
     - repère
     - repère de position produit par la fusion, donc **fusionné**

La cartographie et la navigation utilisent le repère ``odom``, donc la position
fusionnée, comme le veut l'usage ROS. Le topic ``base/odom`` reste brut à
dessein : comparé à la fusion, il sert de **témoin indépendant**, et c'est sur
lui que se mesure la qualité de l'odométrie (voir :doc:`calibration`).

Toute odométrie **dérive** : les erreurs de mesure et les glissements
s'accumulent sans limite. Seul un capteur extérieur — le lidar, en
cartographie et en navigation — permet de la recaler.

Arrêter et réarmer par programme
--------------------------------

**L'arrêt de flotte** arrête tous les robots à la fois. C'est le même que celui
du bouton PS de la manette (voir :doc:`arrets`) :

.. code-block:: bash

   ros2 topic pub --qos-reliability reliable --qos-durability transient_local \
      /ratbot_fleet/emergency_stop std_msgs/msg/Bool "data: true"

``data: false`` lève l'arrêt. Le topic est **absolu** : il vaut pour tout le
parc. La qualité de service ``transient_local`` est indispensable : le dernier
message est conservé et transmis aux robots qui démarrent ensuite, faute de
quoi un robot allumé après l'ordre d'arrêt l'ignorerait.

.. important::

   Ce n'est **pas** un organe de sécurité : il passe par le réseau et par du
   logiciel. Pour protéger quelqu'un, il y a le bouton d'arrêt de chaque robot.

**Les services** de la carte du robot :

.. list-table::
   :header-rows: 1
   :widths: 30 26 44

   * - Service
     - Type
     - Effet
   * - ``rearm``
     - ``std_srvs/Trigger``
     - réarme après un arrêt par le bouton du robot ou un arrêt automatique ;
       refusé tant que le bouton est enfoncé
   * - ``bench_mode``
     - ``std_srvs/SetBool``
     - mode banc : met l'arrêt automatique en pause (voir :doc:`arrets`)
   * - ``reset_odometry``
     - ``std_srvs/Trigger``
     - remet l'odométrie des roues à zéro
   * - ``log``, ``log_clear``
     - ``std_srvs/Trigger``
     - lit ou efface le journal de bord (voir :doc:`journal`)

.. code-block:: bash

   ros2 service call /ratbot_1/rearm std_srvs/srv/Trigger