ROS2-System¶

Zweck¶

Referenz fuer den ROS2-Stack auf dem Raspberry Pi 5. Beschreibt Knoten, Topics, TF-Baum, Launch-Parameter, Docker-Setup, Symlink-Pattern und Betriebsmodi.

Regel¶

Topic-Tabellen, TF-Details, Launch-Parameter und Docker-Konfiguration gehoeren nur in diese Datei. Firmware-Details stehen in docs/firmware.md, Dashboard-Details in docs/dashboard.md.

1. Knoten-Uebersicht¶

Alle Knoten werden ueber full_stack.launch.py orchestriert. Optionale Knoten sind per Launch-Parameter steuerbar.

2. Topic-Tabelle¶

2.1 MCU-Topics (micro-ROS, ESP32-S3)¶

2.2 Pi-5-Topics (ROS2-Knoten)¶

3. TF-Baum¶

odom
  └── base_link              (dynamisch, odom_to_tf, aus /odom)
        ├── laser             (statisch, x=0.10, z=0.235, Yaw=180 Grad/pi)
        ├── camera_link       (statisch, x=0.10, z=0.08, optional: use_camera)
        └── ultrasonic_link   (statisch, x=0.15, z=0.05, optional: use_sensors)

Der odom_to_tf-Knoten subscribt /odom und broadcastet odom → base_link, da micro-ROS keinen eigenen TF-Broadcaster enthaelt.

4. Launch-Parameter¶

Alle Parameter fuer full_stack.launch.py:

Beispiele:

# Standard (SLAM + Nav2, Cliff-Safety an, RViz2 aus):
ros2 launch my_bot full_stack.launch.py

# Nur SLAM, ohne Navigation:
ros2 launch my_bot full_stack.launch.py use_nav:=False

# Vollausbau mit optionalen Subsystemen:
ros2 launch my_bot full_stack.launch.py use_camera:=True use_vision:=True use_dashboard:=True use_rviz:=False

5. Docker-Setup¶

Basis-Image¶

ros:humble-ros-base (Ubuntu 22.04, arm64 multi-arch). Manuell installiert: RViz2, SLAM Toolbox, Nav2, RPLidar, v4l2_camera, micro-ROS Agent, Python 3.10 + Pakete.

docker-compose.yml (vereinfachte Darstellung)¶

services:
  amr:
    image: amr-ros2-humble:latest
    container_name: amr_ros2
    network_mode: host             # ROS2 DDS Multicast
    privileged: true               # Serial + GPIO
    devices:
      - "/dev/amr_drive:/dev/amr_drive"
      - "/dev/amr_sensor:/dev/amr_sensor"
      - "/dev/ttyUSB0:/dev/ttyUSB0"
      - "/dev/snd:/dev/snd"
    volumes:
      - ../pi5/ros2_ws/src/my_bot:/ros2_ws/src/my_bot:rw
      - ../scripts:/amr_scripts:ro
      - ../scripts:/scripts:ro         # Dual-Mount fuer Symlinks
      - ros2_build:/ros2_ws/build
      - ros2_install:/ros2_ws/install
    environment:
      - DISPLAY=${DISPLAY:-:0}
      - ROS_DOMAIN_ID=0
      - GEMINI_API_KEY=${GEMINI_API_KEY:-}

Kritisch: ../scripts wird doppelt gemountet (/amr_scripts + /scripts), damit Symlinks in beiden Kontexten aufgeloest werden.

Convenience-Befehle (run.sh)¶

cd amr/docker/
docker compose build                                                    # Image bauen (~15–20 Min)
./run.sh colcon build --packages-select my_bot --symlink-install        # Paket bauen
./run.sh ros2 launch my_bot full_stack.launch.py                        # Full-Stack
./run.sh ros2 launch my_bot full_stack.launch.py use_nav:=false         # Nur SLAM
./run.sh exec bash                                                      # Shell im Container
./verify.sh                                                             # Gesamttest

run.sh prueft automatisch: X11-Zugriff, Kamera-Bridge-Status, serielle Symlinks, TTY-Flags.

6. Symlink-Pattern¶

Skripte leben in amr/scripts/, werden als Symlinks in my_bot/my_bot/ referenziert und via setup.py entry_points als ros2 run my_bot <name> ausfuehrbar gemacht.

Neues Skript hinzufuegen (4 Schritte)¶

1. Skript anlegen: amr/scripts/<name>.py
2. Symlink erzeugen: cd amr/pi5/ros2_ws/src/my_bot/my_bot && ln -s ../../../../../scripts/<name>.py
3. Entry-Point in setup.py ergaenzen: '<name> = my_bot.<name>:main'
4. Rebuild: cd amr/docker && ./run.sh colcon build --packages-select my_bot --symlink-install

Entry-Points (29 Executables)¶

Runtime-Knoten: odom_to_tf, dashboard_bridge, cliff_safety_node, can_bridge_node, hailo_udp_receiver_node, hailo_inference_node, gemini_semantic_node, audio_feedback_node, tts_speak_node, respeaker_doa_node, voice_command_node

Validierungstests: encoder_test, motor_test, pid_tuning, kinematic_test, imu_test, rotation_test, straight_drive_test, rplidar_test, slam_validation, nav_test, nav_square_test, docking_test, sensor_test, serial_latency_logger, aruco_docking, can_validation_test, cliff_latency_test, dashboard_latency_test

7. Cliff-Safety und Hindernisstopp¶

Datenfluss mit Cliff-Safety (Default)¶

Nav2 controller_server ──→ /nav_cmd_vel ──→ cliff_safety_node ──→ /cmd_vel ──→ Drive-Node
Dashboard Joystick ──→ /dashboard_cmd_vel ──→ cliff_safety_node ──→ /cmd_vel ──→ Drive-Node
Sensor-Node ──→ /cliff ──→ cliff_safety_node (blockiert bei true)
Sensor-Node ──→ /range/front ──→ cliff_safety_node (Stopp < 100 mm, Freigabe > 140 mm)
cliff_safety_node ──→ /audio/play ──→ audio_feedback_node (einmaliger Alarm)

Funktionsweise: - Normalbetrieb: Twist-Nachrichten werden an /cmd_vel weitergeleitet - Cliff (/cliff = true): Blockiert alle Fahrbefehle, sendet Null-Twist (20 Hz) - Ultraschall < 100 mm: Blockiert, Freigabe > 140 mm (Hysterese) - Audio-Alarm (cliff_alarm) einmalig bei Blockierung

Remapping: - dashboard_bridge: /cmd_vel → /dashboard_cmd_vel (bei use_cliff_safety:=True) - Nav2: separat konfiguriert auf /nav_cmd_vel

Datenfluss ohne Cliff-Safety¶

Nav2 / Dashboard ──→ /cmd_vel ──→ Drive-Node

8. Vision-Pipeline¶

Host (Python 3.13): host_hailo_runner.py (Hailo-8 YOLOv8 @ 5 Hz)
  → UDP 127.0.0.1:5005 →
Docker (Python 3.10): hailo_udp_receiver_node → /vision/detections
                      gemini_semantic_node (Gemini Cloud) → /vision/semantics
                      tts_speak_node (gTTS) → Audio

UDP-Bruecke noetig weil hailort nur mit Host-Python 3.13 kompatibel. Dashboard AI-Schalter steuert Broadcast-Gate in Bridge + /vision/enable Topic fuer TTS.

9. Konfigurationsdateien¶

10. QoS-Hinweise¶

/cliff: Subscriber-seitig Best-Effort QoS¶

Der Publisher (Firmware) nutzt Reliable (rclc_publisher_init_default). Der Subscriber (cliff_safety_node) nutzt Best-Effort, damit er auch bei QoS-Mismatch Nachrichten empfaengt:

from rclpy.qos import QoSProfile, ReliabilityPolicy
qos_sensor = QoSProfile(depth=10, reliability=ReliabilityPolicy.BEST_EFFORT)
self.create_subscription(Bool, "/cliff", self.cliff_callback, qos_sensor)

micro-ROS QoS-Regeln¶

• Reliable (rclc_publisher_init_default()): Alle MCU-Publisher (/odom, /imu, /battery, /cliff, /range/front, /battery_shutdown).
• Maximale Nachrichtengroesse: 2048 Bytes (MTU * STREAM_HISTORY).

11. Linting¶

ruff check amr/                    # Python-Lint
ruff format --check amr/           # Python-Format
mypy --config-file mypy.ini        # Type-Check

Python-Stil: Zeilenlaenge 100, Python 3.10, Double Quotes, isort-Import-Sortierung (ruff.toml).

12. Debug- und Diagnosekommandos¶

# Topic-Liste und Raten:
ros2 topic list
ros2 topic hz /odom
ros2 topic hz /cliff

# Topic-Inhalt:
ros2 topic echo /odom --once
ros2 topic echo /cliff --qos-reliability best_effort

# TF-Baum:
ros2 run tf2_tools view_frames
ros2 topic echo /tf --once

# Knoten:
ros2 node list
ros2 node info /cliff_safety_node

# micro-ROS Agent Status:
ros2 topic hz /odom   # 20 Hz = Agent + Drive-Node verbunden

13. ReSpeaker DoA/VAD-Knoten (optional)¶

Pollt Direction-of-Arrival und Voice Activity Detection vom ReSpeaker Mic Array v2.0 (XMOS XVF-3000) via USB Vendor Control Transfers (pyusb) mit 10 Hz.

• /sound_direction (std_msgs/Int32) — Azimut 0–359 Grad
• /is_voice (std_msgs/Bool) — Sprache erkannt
• Parameter: poll_rate_hz (float, default 10.0)
• Voraussetzungen: ReSpeaker per USB, udev-Regel via host_setup.sh, pyusb im Docker-Image

14. Abgrenzung¶

• Firmware-Details (Dual-Core, ISR, CAN-IDs): docs/firmware.md
• Dashboard-Details (Komponenten, Store, Theme): docs/dashboard.md
• Systemarchitektur, CAN-Notstopp: docs/architecture.md
• Vision-Pipeline: docs/vision_pipeline.md
• Serielle Ports (udev): docs/serial_port_management.md
• Build und Deployment: docs/build_and_deploy.md
• Validierungsskripte: docs/validation.md