Hengbot Sirius : documentation développeur

1En bref

Si votre Sirius reçoit vos commandes sans rien faire d'utile, la réponse est presque toujours dans cette liste. Ces quatre pièges nous ont coûté des journées, et chacun se reconnaît à son symptôme : un robot qui accuse réception et piétine, une commande qui revient en « Unknown request_type », une démarche bridée d'origine, un obstacle qui n'existe pas.

1. L'unité de vitesse : les consignes sont normalisées dans [-1, 1], ce ne sont pas des m/s. Demander 0.15 revient à demander 15 % de la vitesse maximale, pas 0,15 m/s.
2. Les noms de commandes : sur le fil WebSocket ils sont en majuscules. Les noms en minuscules que l'on trouve dans les binaires sont les handlers internes, pas ce qui circule.
3. Le mode robot : sorti d'usine, le robot est en desktop, un mode qui bride volontairement la démarche pour qu'il ne tombe pas de la table.
4. La position du capteur : le ToF n'est pas dans la tête mais sous le cou, et il voit son propre menton. Sans le savoir, on prend le robot lui-même pour un obstacle à 191 mm.

Deux autres causes classiques d'un robot inerte ne sont pas des pièges de protocole mais des règles de conduite : la priorité d'action, qu'il faut monter à 5 pour ne pas se faire écraser par le comportement autonome, et le sommeil, dont on ne sort qu'en jouant l'action de redressement. Les deux sont traitées dans Faire marcher le robot.

Le sujet le plus inédit est le capteur ToF : sa position réelle, sa grille, ses unités et son auto-occultation ne sont publiées nulle part, et c'est de là que vient la détection de vide gratuite décrite plus bas.

2Ce qu'est le robot, vraiment

Sous la carrosserie, le Sirius est un mini-ordinateur Linux (puce D-Robotics RDK X3, environ 5 TOPS) qui fait tourner ROS 2 Humble. Tout son comportement est un ensemble de nœuds ROS 2 qui discutent entre eux. L'application vit dans /root/sirius_ros2 et démarre au boot via le service ros2_launch.service.

Il existe deux niveaux pour le piloter, et le choix engage la sécurité mécanique du robot.

Les nœuds qui tournent vraiment

ros2 node list renvoie 31 entrées, dont deux doublons (core_api_node et camera_publisher_node apparaissent deux fois) : 29 nœuds distincts. Ceux qui comptent :

• core_api_node : le serveur WebSocket :8765, c'est lui qui répond aux 59 commandes.
• sirius_motion_control_node : le mouvement. C'est lui qui consomme /gait_generation_trot/cmd_vel et publie filtered_velocity, ainsi que les topics /kinematics/*.
• behavior_engine_node : le comportement autonome, les émotions, l'arbre de décision. Il a absorbé ce que le paquet 2.3.6 répartissait entre robot_behavior_controller et emotion_manager.
• perception_bridge_node, face_detection_bridge, camera_publisher_node : la perception visuelle.
• state_sensor_tof_node : le capteur de distance, sujet d'une section entière plus bas.
• imu_onbody, internal_sensor_battery_onbody : centrale inertielle et batterie.
• action_player_node : joue les actions nommées de /root/material/actions/.
• lvgl_gui_node : l'écran de la tête, y compris le tactile.
• sirius_gamepad et xbox_bluetooth_gamepad sur le topic /joy : la manette Xbox est gérée nativement, ce que la documentation ne dit nulle part.
• Et le reste de la machinerie : lifecycle_manager_node, ota_update_node, network_config_node, sync_manager_node, motor_torque_controller_node, fan_controller_node, modbus_driver, wmix_audio_player_node, ai_interaction_node, character_state_node, user_data_manager, user_interface_udp_server_node, production_test_node, sirius_bt, ble_control_server, robot_led_controller_node.

Fiche technique officielle

• Dimensions 250 x 130 x 250 mm, 960 g, charge utile 300 g.
• Autonomie annoncée 45 à 50 min en usage actif.
• Vitesse maximale annoncée 0,4 m/s (voir plus bas : trois valeurs contradictoires circulent).
• Aucun capteur n'est mentionné dans la section Spécifications. Ni ToF, ni centrale inertielle, ni caméra.

3Versions et firmware

Savoir sur quelle version vous êtes conditionne tout le reste : entre le paquet source que le constructeur distribue avec ses outils et le firmware réellement installé, l'architecture a changé.

Ce que le journal nous a appris

• 2.5.0, 23 juillet 2026 : « les nœuds de comportement et d'émotion ont été supprimés, fusionnés dans un nœud unique de pilotage par arbre de comportement ». C'est l'explication exacte du décalage avec le paquet 2.3.6.
• 2.4.7, 2 juillet 2026 : passage au WebRTC pour le flux vidéo web, et ajout de la détection de squelette humain. La documentation qui annonce la caméra « non disponible » n'est donc pas fausse : elle est antérieure.
• 2.4.7 et 2.4.9 : balayage vers le haut = déverrouillage de l'écran, balayage vers le bas = mise en veille, décrits comme un « geste de réveil ». Cela tranche une question restée longtemps ouverte, voir le mode sol ou bureau.
• 2.4.6, 10 juin 2026 : ajout d'une protection contre la surcharge de couple dans le firmware bas niveau. Un filet de plus, sous les écrêtages articulaires et sous tout coupe-circuit logiciel.
• 2.4.5, 3 juin 2026 : « protocole d'API mis à jour ». C'est probablement là que naît le protocole en majuscules décrit dans cette page, et l'écart avec l'API que documente le constructeur.

Relire la version depuis le robot, si vous préférez la ligne de commande à l'interface :

ssh root@<IP_DU_ROBOT>
source /opt/ros/humble/setup.bash
source /root/sirius_ros2/install/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
[ -f /root/cyclonedds.xml ] && export CYCLONEDDS_URI=file:///root/cyclonedds.xml

ros2 topic echo --once /esp32/firmware_version   # version du microcontroleur
ros2 topic echo --once /ota/status               # etat du systeme de mise a jour

La console du constructeur

Sa barre de navigation liste neuf outils, dont plusieurs ne sont documentés nulle part : Material Manager, Inner World, System Update, Node Management (gestion des nœuds ROS, avec journal depuis la 2.4.5), Gait Debug, Group Dance, Net Debug, Behavior Tree et Timeline Editor. Un retour arrière de firmware y est également disponible. Nous n'en avons exploré que deux : les autres sont des pistes ouvertes, pas du connu.

4Les sept canaux de communication

Le robot expose sept voies d'accès distinctes. Le WebSocket est le canal principal : il pousse l'état en continu et répond aux requêtes. Mais celui qui compte le plus pour un développeur est le dernier de la liste.

Le paramètre ?audience=web figure dans l'URL de l'interface officielle. La connexion fonctionne sans, mais autant rester fidèle à ce que fait le robot.

Enveloppes du WebSocket

// handshake reçu à la connexion
{"type":"event","event_type":"connection_info",
 "data":{"client_id":30,"status":"connected",
   "server_info":{"name":"Sirius Core API","version":"4.0.0",
     "architecture":"Service-based",
     "capabilities":["play_motion","status_monitoring","factory_test","ota_update"]}}}

// requête
{"type":"request","request_type":"<NOM>","request_id":"<id>","data":{}}

// réponse
{"type":"response","request_id":"<id>","success":true,"code":"ok","data":{},"error":""}

// battement de cœur, émis par le client
{"type":"ping","data":{"timestamp":0}}

Codes d'erreur observés : invalid_request, not_found (avec le message « Unknown request_type »), invalid_argument, service_unavailable. Sonder un nom de commande inconnu est sans effet sur le robot : on peut explorer l'API sans rien casser.

Le flux d'événements poussés

5Se connecter au robot

Trouver son adresse IP

• Sur l'écran de la tête, menu Réseau.
• Depuis la liste des baux de votre routeur.
• Par le mode point d'accès du robot : SSID sirius_xx, mot de passe hengbot123 (publié par le constructeur dans son manuel), passerelle 192.168.233.1.

Votre machine et le robot doivent être sur le même réseau. L'interface de debug du constructeur est une page hébergée chez Hengbot, pas sur le robot : http://8.163.38.44:8082/connect?robot=<IP_DU_ROBOT>. Elle ouvre ensuite un WebSocket directement vers votre robot sur :8765. On y trouve le joystick virtuel, la lecture d'actions, la vision et le mode autonome. C'est le moyen le plus rapide de vérifier que tout répond avant d'écrire une ligne de code, et c'est ce test qui nous a mis sur la piste de la vitesse normalisée.

Accès SSH

ssh root@<IP_DU_ROBOT>

# charger l'environnement ROS 2, sinon aucun nœud n'est visible
source /opt/ros/humble/setup.bash
source /root/sirius_ros2/install/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
[ -f /root/cyclonedds.xml ] && export CYCLONEDDS_URI=file:///root/cyclonedds.xml

ros2 node list      # 31 nœuds
ros2 topic list     # environ 130 topics

6La vitesse est normalisée, pas en m/s

Les champs linear_x, linear_y et angular_z attendent une valeur dans [-1, 1] : une fraction du débattement maximal, pas des mètres par seconde. La touche « avancer » de l'interface officielle envoie tout simplement linear_x: 1.

{"type":"request","request_type":"gait_control",
 "data":{"linear_x":1,"linear_y":0,"angular_z":0}}

Envoyer 0.15 en croyant demander 0,15 m/s revient donc à demander 15 % de la vitesse maximale : la foulée devient minuscule et le robot marche sur place. Les ordres de grandeur relevés en télémétrie :

Pour convertir une vitesse réelle en consigne, en s'appuyant sur le domaine de validité relevé sur le robot : linear_x = vx / 0.24 en marche avant, vx / 0.16 en marche arrière, linear_y = vy / 0.20, angular_z = wz / 1.20.

La preuve, côté ROS 2

entrée : /gait_generation_trot/cmd_vel           geometry_msgs/msg/Twist
retour : /gait_generation_trot/filtered_velocity geometry_msgs/msg/Twist

consigne vx=+0.50  ->  mesuré vx=+0.500   (rapport 1.00)

La consigne ressort à l'identique sur filtered_velocity, or 0,50 dépasse la vitesse maximale déclarée du robot. Ce ne peut donc pas être des mètres par seconde. filtered_velocity fait foi : il dit ce que le générateur de démarche applique vraiment, et permet de distinguer « le robot refuse » de « on lui demande trop peu ».

Trois vitesses maximales contradictoires

C'est la dernière valeur qui gouverne le comportement réel, puisqu'elle vient des paramètres chargés par le nœud de contrôle. Domaine complet relevé sur la machine : avant 0,24 m/s, arrière 0,16 m/s, latéral ±0,20 m/s, rotation ±1,2 rad/s, tangage et roulis ±0,524 rad. Les garde-fous joint_clamp_enabled et ws_clamp_enabled sont actifs : une consigne hors domaine est écrêtée, pas poussée contre la butée.

7Les noms de commandes sont en majuscules

C'est le piège principal du protocole WebSocket. Le fil réseau utilise des clés en majuscules, par exemple BEHAVIOR_SET_PAUSE. Les noms en minuscules que l'on trouve en fouillant les binaires, comme set_behavior_pause, sont les handlers internes, pas ce qui circule.

Certaines commandes acceptent les deux formes, par alias hérité : play_motion, gait_control, get_status et get_actions répondent en minuscules. Mais les commandes de mode n'existent qu'en majuscules. Chercher set_behavior_pause sur le fil renvoie « Unknown request_type » et fait croire à tort que la fonction est inaccessible.

Le protocole complet compte 59 commandes, extraites du bundle officiel. Les plus utiles :

Familles complètes également présentes : EMOTION_*, USER_* (thème, MBTI, langue, paramètres de nœud), LIFECYCLE_*, NETWORK_*, OTA_*, SYNC_*, MATERIAL_*.

8Le mode sol ou bureau

Deuxième cause classique du « il piétine sans avancer », après l'unité de vitesse. Le robot possède deux modes de fonctionnement, et il sort d'usine dans celui qui bride la marche.

USER_GET_ROBOT_MODE  {}                        -> {"robot_mode":"desktop"}
USER_SET_ROBOT_MODE  {"robot_mode":"ground"}   -> {"robot_mode":"ground"}

• desktop : selon le firmware, « limite les mouvements amples et la démarche pour empêcher le robot de tomber de la table ». Les pattes bougent sur place.
• ground : « active toutes les actions, y compris la démarche et les déplacements amples ».

L'écran de la tête affiche un état nommé « Ground », et le robot y bascule de lui-même après une période d'inactivité. Un balayage vertical sur l'écran « débraye » cet état, mais ce n'est pas un changement de mode robot. Les notes de version du constructeur sont explicites : le balayage vers le haut déverrouille l'écran et sert de geste de réveil (versions 2.4.7 et 2.4.9), le balayage vers le bas met en veille. Le mode sol ou bureau, lui, ne se change que par USER_SET_ROBOT_MODE, ou depuis une interface.

La documentation officielle décrit par ailleurs un mode Développeur sur l'écran de tête, qui « suspend l'interface pour permettre la programmation Python via les API ». Nous ne l'avons pas testé. La navigation dans cet écran se fait par les boutons d'oreille, la validation par une tape sur le crâne.

9Le capteur n'est pas là où on croit

Pendant dix sessions, notre robot en déambulation autonome s'arrêtait net devant un obstacle situé à 191 mm. Toujours 191 mm, avec 5 mm d'écart-type. Un obstacle qui n'existait pas : il fuyait sa propre mâchoire.

Le capteur ToF n'est pas dans la tête, comme la position de la « bouche » du robot le laisse croire. Il est sous le cou, en haut du poitrail. Placé si haut et si en avant, il voit son propre menton dans le haut de son champ, et ses propres pattes avant dans le bas.

La mesure qui tranche

Quand on bascule la tête de ±0,30 rad (17°) sur son axe de tangage, les distances ToF ne varient que de 1 à 2 mm. Un capteur logé dans la tête verrait ses distances au sol changer de plusieurs dizaines de millimètres pour un tel basculement.

Les conséquences sont presque toutes favorables. La géométrie du ToF ne dépend que de l'assiette du corps, que le générateur de démarche régule déjà : il n'y a donc aucun angle de tête à suivre dans vos calculs. Et la tête peut regarder ailleurs, suivre un visage, sans perturber la navigation. En contrepartie, le champ est fixe par rapport au corps : impossible d'orienter le capteur pour balayer les côtés, c'est le corps entier qu'il faut tourner.

L'auto-occultation par les pattes

Une main passée devant le capteur fait chuter les distances mesurées de 80 % sur les rangées hautes, mais de 18 % seulement sur la rangée basse : les pattes avant y occupent déjà le champ. Et en marchant, elles balancent, donc elles entrent et sortent du champ à chaque foulée. D'où deux règles de conception : ne jamais fonder une détection sur la seule rangée 0-3, et apprendre le fond en marchant, jamais à l'arrêt.

Caractérisation complète du ToF

Le même relevé est aussi publié en image mono16 4 x 4 sur /state_sensor/tof/heatmap. Le champ raw_registers (11 valeurs, souvent 65535) est du débogage constructeur, sans intérêt.

        haut   [12] [13] [14] [15]
               [ 8] [ 9] [10] [11]
               [ 4] [ 5] [ 6] [ 7]
        bas    [ 0] [ 1] [ 2] [ 3]
                gche            drte

Signature au repos

robot debout, tete au neutre, champ degage

   ..   765    ..    ..      <- horizon : hors portee
  780   786    ..    ..      <- sol lointain
  304   295   291   298      <- sol a ~30 cm
  198   219   218   201      <- sol a ~20 cm, juste devant les pattes

Les rangées basses voient le plancher à distance croissante. C'est de là que découlent les deux lectures qui fondent toute navigation autonome, et la section suivante.

10Ce que le ToF permet : la détection de vide

C'est la trouvaille la plus utile de tout ce travail, et elle ne demande aucun matériel supplémentaire. Puisque les rangées basses du ToF voient en permanence le plancher, entre 20 et 30 cm devant elles, il suffit de surveiller sa disparition.

• Obstacle : les rangées hautes cessent de saturer et les basses raccourcissent.
• Vide (bord de table, marche, escalier) : les rangées basses, qui voyaient le sol, passent brutalement à 2047, c'est-à-dire « pas de cible ».

Le principe d'implémentation retenu : le nœud apprend son fond pendant cinq secondes de marche en ligne droite, sous forme d'enveloppe minimum et maximum par zone. Il ne réagit ensuite qu'aux écarts. Ce qui raccourcit est un obstacle, ce qui s'allonge est un vide.

Les garde-fous qui se sont révélés nécessaires

• Le vide l'emporte sur toute autre décision.
• Seules les rangées basses ont le droit de déclarer un vide, et seulement les zones qui voyaient le sol de près (moins de 50 cm) et presque toujours (80 % des trames).
• Toute décision doit persister trois cycles avant d'être appliquée : le trot fait tanguer le corps, une seule trame ne prouve rien.
• Le recul est bridé à la moitié de la vitesse d'avance et borné à 1,5 s, parce que le robot ne voit rien derrière lui.
• Une rotation sans issue de plus de 5 s déclenche un recul et un changement de sens, sinon le robot tourne indéfiniment.
• Le nœud publie dix consignes nulles à l'arrêt, y compris sur SIGHUP. Validé en réel lors d'une coupure Wi-Fi : le robot s'arrête proprement au lieu de continuer sur sa dernière consigne.

L'historique des versions dit tout du chemin parcouru : recul perpétuel en v1 (seules 8 zones apprises, les autres signalaient sans cesse un obstacle surgi de nulle part), vides fantômes en v6 (zones lointaines saturées prises pour des précipices), rotation sans fin en v7, et v8 qui a révélé le piège de la vitesse normalisée. La v9 se faufile et esquive. La v10 a tenu 11 s de marche rectiligne et survécu à une perte de SSH.

La v12 masque une bande étroite de 170 à 225 mm dans le haut du champ, la signature de la mâchoire, mais seulement si les rangées basses ne confirment pas la présence d'un obstacle, pour qu'une étagère basse reste visible. Elle remplace aussi la marge fixe de 120 mm par une marge proportionnelle au fond appris (30 %, plancher à 50 mm) : avec un fond à 200 mm, une marge fixe de 120 mm rendait les rangées basses incapables de déclencher quoi que ce soit. Trente-quatre tests hors ligne rejouent de vraies trames capturées sur le robot.

La v13, celle qui est livrée avec l'outil, remplace la réaction unique par une réponse graduée. Au-delà de 300 mm, le robot esquive en continuant d'avancer, en braquant du côté le moins encombré : il compare l'encombrement cumulé à gauche et à droite, et réévalue à chaque cycle. En dessous de 300 mm, il pivote sur place. Il ne recule qu'en dessous de 200 mm, ou s'il est coincé, parce que le recul est aveugle : rien ne regarde derrière lui. C'est toute la raison de cette gradation. Elle expose aussi un service HTTP sur le port 8790 qui publie la grille, la décision et son motif, et accepte démarrer, arrêter et vitesse : c'est ce que l'onglet Déambulation affiche et commande, par un passe-plat du pont.

Deux itérations plus tard, la v15 corrige un défaut qui sautait aux yeux dès qu'on regardait le robot longtemps : à obstacle symétrique, il partait toujours du même côté. Ce biais à gauche est supprimé. Le recul déclenché par une détection de vide est désormais borné lui aussi, au lieu de courir jusqu'à ce qu'autre chose l'interrompe.

11Sécurité

• Le robot ne voit rien derrière lui. Le ToF regarde vers l'avant et il n'existe aucun capteur arrière. Toute marche arrière est aveugle : vitesse réduite et durée bornée.
• Les moteurs chauffent. Évitez les sessions très longues en continu, d'autant que la remontée de température est muette sur ce firmware.
• Ne modifiez pas les fichiers du firmware sans sauvegarde. Travaillez avec vos propres scripts dans /root/ ou un dossier à vous.
• Gardez un arrêt d'urgence sous la main, dans un terminal déjà ouvert. Publier des consignes nulles en boucle est le moyen le plus fiable de tout arrêter.
• La voie UDP Play_Keyframe court-circuite les protections du robot. Ne l'utilisez qu'après avoir relevé les limites articulaires, et jamais pour un premier essai.

Surveiller la charge moteur

L'événement motor-load remonte 14 charges à 1 Hz, en pour mille de PWM, sur une plage de ±1000. C'est le seul instrument fiable dont on dispose pour détecter une butée, puisque les sondes de température sont muettes. Mesures réelles :

Le firmware applique par ailleurs ses propres garde-fous, actifs en permanence : écrêtage des angles articulaires, écrêtage de l'espace de travail, seuil de saut articulaire à 0,5 rad, régime moteur plafonné à 200 tr/min. Une consigne hors domaine est donc écrêtée plutôt que poussée contre la butée. Cela ne dispense d'aucune précaution, mais c'est un filet de plus.

Enfin, la documentation officielle mentionne un mode Emergency_Stop via Mode_Switch, que nous n'avons pas encore testé et que nous avions reconstruit à la main. Si vous le validez, écrivez-nous.

12Faire marcher le robot

Deux voies, selon que vous travaillez depuis votre machine (WebSocket) ou depuis le robot lui-même (ROS 2). Dans les deux cas, relisez d'abord la vitesse normalisée et le mode sol ou bureau : ils expliquent la plupart des cas où le robot refuse d'avancer.

Par le WebSocket

Par ROS 2, depuis le robot

import rclpy
from rclpy.node import Node
from geometry_msgs.msg import Twist

# ATTENTION : linear.x est NORMALISE dans [-1, 1], pas des m/s.
# 0.10 fait pietiner sur place. 0.45 fait marcher.

rclpy.init()
node = Node('hello_move')
pub = node.create_publisher(Twist, '/gait_generation_trot/cmd_vel', 10)

cmd = Twist()
cmd.linear.x = 0.45
for _ in range(30):
    pub.publish(cmd)
    rclpy.spin_once(node, timeout_sec=0.1)

# toujours republier des zeros a l arret
cmd.linear.x = 0.0
for _ in range(10):
    pub.publish(cmd)
    rclpy.spin_once(node, timeout_sec=0.05)

Le service /gait_generation_trot/step_move (type gait_generation_trot/srv/GaitStepMove, champs velocity et duration) fait un pas net et rend la main. C'est le plus simple pour un premier essai : une vitesse négative fait reculer.

Se relever, se coucher

ACTION_PLAY {
  "file_path":"/root/material/actions/stand_default_returnPosition_brief.avi",
  "loop":false,
  "priority":5,
  "torque":2047
}

Trois détails comptent, et chacun a coûté du temps : l'action est returnPosition et non stand_default_idle ; la priorité 5 est indispensable, car en priorité 1 (la valeur par défaut) le comportement autonome en cours écrase l'action et le robot reste couché ; et le couple doit être au maximum.

Le sommeil

Après inactivité, le robot passe en état émotionnel sleeping, avec un éveil proche de zéro, et s'accroupit. Dans cet état, la marche ne produit rien d'utile. Pour le réveiller à distance, jouez l'action de redressement, celle de la sous-section précédente, en priorité 5. Vérifié sur le robot : il se relève et obéit de nouveau.

Ce qui ne se pilote pas à distance, c'est l'état émotionnel lui-même : EMOTION_SET_STATE répond service_unavailable sur ce firmware, et EMOTION_INTERACTION refuse tous les types tentés (touch_tap, touch, pet, dog_bone). La distinction compte : on ne peut pas changer son humeur, on peut parfaitement le remettre au travail.

13Gestes, vision et caméra

Les gestes de la main : à vérifier sur votre firmware

Un modèle de reconnaissance de gestes existe côté D-Robotics, et le paquet sirius_full_v2.3.6 référence le topic /hobot_hand_gesture_detection (ai_msgs/PerceptionTargets), avec un attribut gesture porteur d'une valeur entière.

L'événement vision-detection

Une fois VISION_SET_DETECTION actif, le robot pousse sur le canal principal un événement à environ 30 Hz. C'est la sortie du modèle de perception, disponible sans toucher au flux vidéo : on peut donc faire du suivi sans jamais afficher d'image.

{"type":"event","event":"vision-detection","data":{
  "detections":[
    {"class_id":0,"class_name":"body","type":"body","confidence":1,
     "rect":{"x":239,"y":1,"width":126,"height":192}},
    {"class_name":"head","rect":{}},
    {"class_name":"face","rect":{}}
  ],
  "skeletons":[
    {"track_id":1,"type":"body",
     "points":[{"x":191,"y":3,"score":0.859}]}
  ],
  "image_width":640,"image_height":360}}

• Les coordonnées sont dans le repère 640 x 360 du modèle, pas dans celui de la vidéo affichée. Il faut les remettre à l'échelle, et tenir compte du letterboxing si la vidéo est en object-fit: contain.
• track_id persiste entre les trames : c'est du suivi, pas de la détection image par image.
• Classes observées à ce jour : body, head, face. Les objets « os, balle, peluche » du firmware sont des items virtuels du système d'émotions, pas des classes de vision.
• À 30 Hz, ne jamais faire passer ces trames par l'état d'un composant React : les stocker dans une référence et dessiner dans un requestAnimationFrame.

La caméra, en WebRTC

Ce n'est pas une image à récupérer : c'est un flux WebRTC négocié sur une seconde WebSocket. La vidéo circule ensuite directement entre le navigateur et le robot, en pair-à-pair. Un backend ne peut donc que relayer la signalisation, jamais servir le flux.

1. Sur :8765, envoyer VISION_SET_DETECTION {enabled: true}. Le robot répond « Web streaming enabled ».
2. Le navigateur ouvre ws://<IP>:8766, sans paramètre d'URL. C'est le point qui nous a coûté le plus de temps : la signalisation vidéo ne vit pas sur le canal principal.
3. Le robot y envoie {"type":"welcome","client_id":"ws_N"}. Cet identifiant est une chaîne, distincte du client_id numérique du handshake. Reconstruire ws_<numéro> ne fonctionne pas.
4. Le navigateur envoie webrtc_offer avec ce client_id, le robot répond webrtc_answer.
5. Échange de webrtc_ice. Les candidats du robot arrivent préfixés a=, à retirer avant addIceCandidate.

Si le pair-à-pair est bloqué par le réseau, il reste une voie plus simple : le service ROS /camera/capture_jpeg, en affichage par images successives. Services caméra côté ROS : /camera/capture_jpeg, /camera_publisher_node/enable_web_streaming, /camera_publisher_node/enable_yolo_shm.

14Commander la tête

Le canal confirmé sur le robot est un topic ROS d'entrée du nœud de cinématique inverse. Il reçoit une consigne et ne publie rien en retour.

topic : /kinematics/ik_subscriber/head_euler_follow
type  : geometry_msgs/msg/Point
unite : RADIANS

x = tangage (haut / bas)
y = lacet (gauche / droite)
z = sans effet observable

• x commande le tangage, confirmé de visu.
• y commande le lacet.
• z n'a aucun effet observable : la tête n'a que deux degrés de liberté.
• De 0,10 à 0,35 rad, les mouvements sont progressifs. Rester sous 0,35 rad : au-delà d'environ 1 rad, c'est la butée articulaire.

Rappel utile : puisque le ToF est dans le poitrail et non dans la tête, bouger la tête ne perturbe pas la navigation. La tête peut donc suivre un visage pendant que le corps se dirige avec ce même champ ToF, sans que l'un gêne l'autre.

15Le volume, les LED, l'écran, et les yeux qui ne répondent pas

Trois réglages que la documentation constructeur ne mentionne pas, et une question qu'on nous pose souvent, tranchée par la négative avec sa preuve. Tout ce qui suit a été relevé sur la machine fin juillet 2026, firmware 2.5.0.

Le volume : un paramètre ROS, pas une commande dédiée

Le volume sonore est le paramètre ROS audio_volume, un entier de 0 à 100, porté par le nœud wmix_audio_player_node. On le règle par la commande WebSocket USER_SET_NODE_PARAMETER, avec pour charge utile node_name, parameter_name et parameter_value. La trame a été capturée sur l'interface officielle du constructeur, en écoutant le WebSocket 8765 pendant qu'on bougeait le curseur de volume.

{ "command": "USER_SET_NODE_PARAMETER",
  "node_name": "wmix_audio_player_node",
  "parameter_name": "audio_volume",
  "parameter_value": 54 }

Deux réserves. La lecture du volume n'est pas supportée : le GET symétrique est vraisemblablement USER_GET_NODE_PARAMETER, mais nous ne l'avons jamais capturé, et notre outil affiche donc un point d'interrogation à la place du niveau courant. Et sur l'interface officielle, changer le volume déclenche un aperçu sonore : le robot joue stand_default_littleBark_brief, se lève et aboie brièvement. Ce n'est pas un dysfonctionnement.

Les LED : uniquement par l'UDP

Le robot porte huit points lumineux colorables, deux à la tête et six sur le dos. Ils ne sont accessibles que par le canal UDP du port 8768, qui republie vers le topic /robot_led_controller/led_colors. Aucune autre voie connue : ni WebSocket, ni REST.

Ce décompte demande une précision, obtenue en poussant le pilotage plus loin : chacun des deux points de la tête est en réalité une oreille de six mini-LED disposées en cercle, adressables une par une, exactement comme les six LED du dos. Cela fait douze canaux à la tête et six au dos, soit dix-huit en tout, et non huit. La numérotation part du haut, 1 à midi, puis dans le sens horaire.

Ce canal UDP mérite qu'on s'y arrête, parce qu'il donne aussi un accès direct à la marche, à l'assiette du corps, à la tête et aux quatre pattes sans passer par le WebSocket. C'est la voie qu'emploie le script Blender du constructeur pour prévisualiser une animation en direct.

L'écran de la tête : par des services ROS

L'écran se pilote par des services ROS actifs sur la machine : /lvgl_gui_node/play_lottie et /play_gif pour les animations, /lvgl_gui/show_toast et /show_dialog pour les messages, /show_ip_address, et /camera_display/toggle. C'est ce que notre outil utilise pour afficher un texte ou rejouer une animation de la bibliothèque du robot.

Les yeux ne sont pas pilotables, et voici la preuve

C'est la question qui revient le plus souvent, et la réponse est non sur le firmware 2.5.0. Le serveur UDP comprend pourtant très bien les clés eye_iris, eye_upper et eye_lower : elles sont présentes dans son binaire, et il les republie consciencieusement sur le topic /lvgl_layer. Sauf que plus personne ne les écoute.

ros2 topic info /lvgl_layer
# Publisher count: 2
# Subscription count: 0

Zéro abonné : lvgl_gui_node, qui dessine l'écran, ne figure pas parmi eux. Les paramètres hide_eye_layer des services d'écran confirment que la couche des yeux est gérée à l'intérieur de ce nœud. Et l'add-on Blender du constructeur montre où vivent réellement les yeux : leurs données sont embarquées dans les fichiers d'action eux-mêmes. L'écran est animé par le lecteur d'actions et le moteur d'émotion, pas par une commande venue de l'extérieur.

Une piste reste ouverte, du côté de l'humeur cette fois : les services ROS /emotion_manager/set_emotion_state, /adjust_emotion et /adjust_satiety existent bel et bien sur la machine. La voie ROS pourrait rendre l'état émotionnel commandable, là où le WebSocket répond service_unavailable. Nous ne l'avons pas encore testée.

16Ce qui n'existe pas, et ce que la doc omet

Cette section est là pour vous éviter de chercher pendant des heures quelque chose qui n'est pas dans la machine.

Ce qui n'existe pas

• Pas de retour d'angle de tête : les topics existent mais restent muets.
• Pas de température moteur : l'événement motor-temperature renvoie 0 sur ce firmware, les sondes sont muettes.
• Pas de réglage de l'état émotionnel à distance : EMOTION_SET_STATE répond service_unavailable. Le réveil, lui, passe très bien par l'action de redressement.
• Pas de détection de clap native, ni de doigt pointé dans le modèle de gestes.
• Pas de classes de vision au-delà de body, head et face à ce jour. Le service enable_yolo_shm laisse penser qu'un modèle YOLO existe par ailleurs, non confirmé.

Ce qui existe, et que la documentation ignore aussi

La liste précédente a son pendant positif : la centrale inertielle est lisible, alors que la fiche technique ne la mentionne pas plus que le reste des capteurs.

/state_sensor/imu_onbody/imu_publisher/imu_data    sensor_msgs/msg/Imu
/state_sensor/imu_onbody/imu_publisher/imu_angle   geometry_msgs/msg/Vector3
/state_sensor/imu_onbody/imu_publisher/diagnostic  "IMU sensor is operating normally"

imu_angle sert de garde-fou dans notre déambulation : si l'assiette dérive de plus de 0,10 rad par rapport à celle apprise, la géométrie du ToF n'est plus valable et toute décision de vide est suspendue. C'est un exemple concret d'un capteur non documenté employé pour sécuriser un autre capteur non documenté.

Ce que la documentation officielle omet

La documentation officielle existe et mérite d'être lue : elle décrit une API WebSocket différente de celle que nous avons cartographiée, la voie « keyframes » du port UDP 8768, avec les commandes Mode_Switch, Control_Move, Start_Record, Play_Keyframe, Get_Status, Set_Parameter. Elle documente aussi un mode Liberté et un mode Développeur sur l'écran de tête, et un auto-test matériel (IMU, boutons, batterie, Wi-Fi, servomoteurs).

L'écosystème indépendant, en juillet 2026

Le terrain est quasi vierge. Huit mois après les premières livraisons, le nombre de tutoriels développeur publiés sur YouTube, toutes langues confondues, est de zéro. Tout ce qui existe tient en deux dépôts, d'une seule personne :

• dspeers/sirius-control-panel : découvre le REST sur :8088 et un flux MJPEG sur :8080. Son test_api.py est la seule documentation d'API reconstituée publiquement disponible, et la seule source publique mentionnant la grille 4 x 4.
• dspeers/sirius-voice-bridge : substitue une reconnaissance vocale locale à celle d'origine. Révèle au passage que la voix du Sirius transite par le cloud ByteDance / Volcano Engine, ce qu'aucune couverture presse ne mentionne.
• mitchrk/sirius-osrd annonce un firmware open source et est entièrement vide.
• Le paquet PyPI hengbot-api est un faux ami : il date de novembre 2024 et pilote le Sparky, le robot précédent.

17Piloter le robot depuis un navigateur

Studio 360 pour Sirius, en abrégé Studio 360, est l'outil que nous utilisons pour tout ce travail, et il est téléchargeable. Il n'a rien d'un produit : c'est un outil de rétro-ingénierie devenu utilisable, publié parce qu'il fait gagner des heures à qui veut commencer.

Ce qu'il fait : deux joysticks pour marcher et s'orienter, un troisième pour la tête, la vue caméra en direct avec les détections dessinées par-dessus, la bibliothèque d'actions du robot avec ses noms traduits du chinois, la télémétrie des 14 moteurs, le journal de tous les appels d'API, le sélecteur Sol / Bureau, et un coupe-circuit qui arrête le robot au-delà de 850 ‰ de charge moteur maintenus 0,8 s.

Comment il est fait : un pont Python tourne sur votre machine (FastAPI), il parle WebSocket au robot et sert une interface React à votre navigateur. La vidéo, elle, va directement du robot au navigateur en WebRTC : un backend ne peut relayer que la signalisation, jamais le flux.

L'interface est bilingue français et anglais : un bouton FR / EN dans la barre du haut, à côté du thème, et le choix est mémorisé. Le bouton de posture s'appelle Couché et non « Au sol », pour ne pas le confondre avec le mode Sol / Bureau, qui décrit l'environnement du robot et non sa posture. Ce sélecteur reflète l'état réel du robot, y compris quand le comportement autonome agit seul : la posture est déduite de l'action jouée, signalée comme telle, et rien ne s'allume tant qu'elle n'est pas connue.

Les sept onglets

L'interface tient en sept onglets : Dashboard, Système, Vie du robot, Actions, Enchaînements, Pilotage et Déambulation.

L'onglet Système est une vue de diagnostic : les compteurs de la vision en temps réel, la charge des 14 moteurs et l'état du coupe-circuit, les métriques de la machine (processeur, disque, nœuds ROS actifs, réseau, fraîcheur du lien), et un volet thermique qui dit la vérité plutôt que d'inventer. La température de la batterie est affichée, parce que c'est la seule que le robot publie réellement. Les quatre sondes de patte sont déclarées muettes, puisqu'elles renvoient 0 sur ce firmware. Et la température du processeur est déclarée non disponible, avec sa raison : elle n'existe ni sur le WebSocket 8765 ni sur le REST 8088, sa seule source connue est le topic ROS /fan_breathing/cpu_temp, qui n'est ponté nulle part vers le monde WebSocket. Un trou honnête vaut mieux qu'un chiffre inventé.

L'interrupteur « autonome » de la barre du haut passe par la route POST /api/modes/autonomous, qui envoie BEHAVIOR_SET_PAUSE au robot.

L'interface s'installe sur un téléphone comme une application, avec son manifeste, ses icônes et le plein écran iOS : piloter le robot en le suivant dans la pièce est possible. Le pont, lui, reste sur votre machine ; le téléphone n'est qu'un écran de plus ouvert dessus. C'est le rôle du mode réseau, lanceur demarrer_telephone.bat : le pont écoute sur le réseau local et la fenêtre affiche l'adresse à taper sur le téléphone.

Le thème est posé avant le premier rendu, donc sans flash clair au chargement, et le bouton de la barre parcourt sombre, clair, puis système, ce dernier suivant à chaud le basculement jour / nuit de la machine. Une différence assumée avec le client officiel du constructeur : il coupe le zoom, pas nous. Gagner en confort d'apparence en désactivant le pincement se paie en accessibilité.

L'onglet Déambulation laisse le robot se promener seul en évitant les obstacles, pendant que l'écran montre ce qu'il perçoit. Il est organisé en trois colonnes, ce qu'il voit, ce qu'il mesure, ce qu'il fait : le champ du capteur de distance en direct, une grille de 4 × 4 zones, seize distances en millimètres colorées de la plus proche à la plus lointaine, les zones qui crient « obstacle » ou « vide » cernées d'un anneau, puis la décision du robot et son motif en clair. On y trouve aussi une marche pas-à-pas, des déplacements bornés en nombre de foulées que le robot compte avant de s'arrêter seul, et un bouton Réveil / Debout.

Le capteur de distance n'existe que sur le ROS embarqué, jamais sur le canal WebSocket : la boucle d'évitement tourne donc à bord du robot et non sur le PC. Ce nœud est fourni avec le kit et se dépose sur la machine en une commande. Tant qu'il n'est pas déposé, l'onglet s'affiche et explique la marche à suivre au lieu de rester muet.

Vie du robot rassemble ce que la machine dit d'elle-même et les réglages qui la concernent : son humeur telle que son propre moteur émotionnel la calcule (plaisir, éveil, satiété, fatigue), lue sur l'échelle 0 à 100 du robot, et ce sont ces valeurs qui expliquent qu'il finisse par se coucher tout seul ; le volume audio ; les LED, pilotables diode par diode, deux oreilles de six mini-LED en cercle et six LED de dos, avec un mode Identifier qui n'en allume qu'une à la fois ; l'écran de la tête, message texte et animations de sa propre bibliothèque ; la batterie, le réseau, la charge des 14 moteurs, les interactions tactiles reçues, les journaux et la mémoire du dialogue.

Enchaînements est un éditeur de comportement : on met bout à bout des animations, des groupes à tirage aléatoire (un groupe « repos » jouera l'une de ses animations au hasard), des pauses et des blocs d'errance autonome, puis on lance le cycle, une fois ou en boucle. Les enchaînements sont enregistrés sur le PC, exportables et importables en JSON. L'idée neuve tient dans le groupe : on décrit un comportement, pas une suite figée.

Deux boutons de la barre du haut ne doivent pas être confondus : Reset commande la remise debout depuis une posture couchée, tandis que Recovery, affiché « Relever », déclenche la mécanique de relevage après chute propre au robot. Ce sont deux appels différents.

Ce qu'il vous faut

• Python 3 installé sur votre PC, avec la case « Add Python to PATH » cochée à l'installation. C'est la cause numéro un des échecs de démarrage.
• Un robot Sirius sur le même réseau Wi-Fi que votre PC.
• Un navigateur récent, la vidéo passe par WebRTC.

Aucune dépendance à installer à la main : le lanceur récupère fastapi, uvicorn, websockets et httpx à la première utilisation, une fois pour toutes, en une trentaine de secondes.

Se connecter, en trois étapes

1. Allumez le robot et vérifiez qu'il est sur le même réseau Wi-Fi que votre PC. Son adresse IP s'affiche sur l'écran de sa tête, menu Réseau.
2. Décompressez l'archive et double-cliquez demarrer.bat. Une fenêtre noire s'ouvre, affiche le numéro de version, puis votre navigateur s'ouvre seul sur l'interface. Si ce n'est pas le cas, allez sur http://127.0.0.1:8787.
3. Saisissez l'adresse IP du robot dans l'interface, puis cliquez « Connecter ». Elle est mémorisée : les fois suivantes, un clic sur l'adresse récente suffit.

Pour piloter depuis un téléphone, lancez demarrer_telephone.bat au lieu de demarrer.bat, puis ouvrez sur le téléphone l'adresse que la fenêtre affiche, le téléphone étant sur le même Wi-Fi que le PC. « Ajouter à l'écran d'accueil » installe l'interface comme une application, qui s'ouvre alors en plein écran. Le pont reste sur le PC : c'est lui qui parle au robot.

Faire déambuler le robot

L'onglet Déambulation a besoin du nœud d'évitement, qui tourne à bord du robot. Il est dans l'archive, et un lanceur s'en charge : double-cliquez deambulation_robot.bat, saisissez l'adresse du robot, il dépose le fichier et démarre le service. Il vous faut le client OpenSSH de Windows, et rien d'autre.

À la main, si vous préférez voir ce qui se passe, c'est la même chose en trois commandes :

scp deambulation.py root@<IP_DU_ROBOT>:/root/
ssh root@<IP_DU_ROBOT>
python3 /root/deambulation.py --service

Lancé ainsi, le nœud expose sur le port 8790 la grille du capteur, sa décision et son motif, et accepte démarrer, arrêter et vitesse : le pont ne fait que relayer. L'onglet devient alors vivant. Tant que ce programme ne tourne pas, il affiche « service injoignable » : il ne manque que lui. Relisez l'encart « sol plat uniquement » plus haut avant de cliquer Démarrer, il n'est pas décoratif.

S'il ne bouge pas

Par ordre de fréquence, et les deux premières causes sont la vitesse normalisée et le mode sol ou bureau :

• Il bouge les pattes sans avancer : il est en mode Bureau, basculez sur Sol dans Modes et comportement. Ou la vitesse demandée est trop faible : montez le curseur.
• Il ne réagit à rien : soit il dort, jouez une action pour le réveiller, soit le mode autonome est actif et annule vos commandes, coupez-le.
• « Impossible de joindre le robot » : vérifiez l'adresse IP, et que le PC et le robot sont bien sur le même réseau.
• « Python introuvable » : réinstallez Python en cochant « Add Python to PATH ».
• Voir ce qui se passe : l'API du pont est documentée et testable sur http://127.0.0.1:8787/docs.

Le kit est fourni sans garantie : il pilote du matériel qui peut tomber ou se coincer. Les lanceurs sont des fichiers .bat, donc Windows ; le pont Python est multiplateforme mais n'a été testé nulle part ailleurs. Un bug, une remarque, un résultat d'essai : écrivez-nous, c'est ainsi que cette page progresse.