Sentor: A ROS messages monitoring node

Continuously monitor topic messages. Send warnings and execute other processes when certain conditions on the messages are satisfied. See the wiki.

Integration Documentation

For integrating Sentor with RobotStateMachine and Nav2 for safe autonomous navigation:

• Integration Summary - Quick reference guide (7KB, 5 min read)

  • Core safety requirements and system overview
  • Multi-layer safety approach with sentor_guard
  • Implementation checklist

• Full Architecture Document - Complete concept architecture (45KB, 30 min read)

  • Detailed system architecture and component responsibilities
  • Four integration strategies with pros/cons
  • State transition handling and emergency stop behavior
  • Phased implementation plan with code examples
  • Testing strategy and failure mode analysis
  • sentor_guard package integration

• sentor_guard Package Design - Reusable safety libraries (52KB, 40 min read)

  • Python and C++ guard libraries (context managers, RAII)
  • Topic guard node for transparent filtering
  • Lifecycle guard node for automatic state management
  • Complete code examples and usage patterns
  • Configuration and launch file templates

• Integration Diagrams - Visual reference (22KB)

  • ASCII diagrams for all major flows
  • Timing diagrams and state machines
  • Topic and service interactions

Sentor Monitoring Configuration

This document explains how to structure your YAML config file for Sentor’s topic- and node-monitoring, and how the two “heartbeats” (safety/heartbeat and warning/heartbeat) are driven by your safety-critical and autonomy-critical flags.

---

Table of Contents

1. Overview
2. Top-Level Structure
3. monitors: (TopicMonitors)
   • Common fields
   • signal_when
   • signal_lambdas
   • Example
4. node_monitors: (NodeMonitors)
   • Fields
   • Example
5. Heartbeats
   • Safety heartbeat (safety/heartbeat)
   • Warning heartbeat (warning/heartbeat)

---

Overview

Component	What it watches	Critical flags in YAML	Feeds into
TopicMonitor	Rate + message content of one topic	safety_critical, autonomy_critical	both beats
NodeMonitor	Presence of a node on the ROS graph	safety_critical, autonomy_critical	both beats
SafetyMonitor	Aggregates monitors and publishes a Boolean topic	—	one beat

If all linked monitors are healthy for at least safe_operation_timeout seconds, the heartbeat publishes true; otherwise it immediately publishes false.

---

Top-Level Structure

monitors:       # list of topic monitors
  - …           # one map per topic
node_monitors:  # list of node monitors
  - …           # one map per node

(Spaces only, no tabs.)

---

monitors: (TopicMonitors)

Common fields

Field	Type	Req	Description
name	string	✔	Full topic name (/camera/image_raw)
message_type	string	✔	Package/type (sensor_msgs/msg/Image)
rate	number	✔	Minimum acceptable publish rate (Hz)
N	int	•	Window size for rate (default 5)
qos	map	•	Override QoS (reliability, durability, depth)
timeout	sec	•	Default lambda / signal timeout (default 10)
default_notifications	bool	•	Log flips automatically? (default true)
enable_internal_logs	bool	•	Extra per-topic debug (default false)

signal_when

signal_when:
  condition: "published"        # or "not published"
  timeout: 2.0                  # seconds before failure
  safety_critical:   false
  autonomy_critical: true
  tags: ["camera", "liveliness"]  # optional free-text labels

signal_lambdas

signal_lambdas:
  - expression: "lambda x: x.height == 480"
    timeout: 2.0
    safety_critical: true      # affects safety beat
    autonomy_critical: false   # doesn’t affect warning beat
    process_indices: [2]       # indexes into `execute` list (optional)
    repeat_exec: false         # run every time satisfied?
    tags: ["resolution"]

Example Topic Monitor

- name: "/front_camera/camera_info"
  message_type: "sensor_msgs/msg/CameraInfo"
  rate: 8
  N: 5
  qos:
    reliability: "reliable"
    durability: "volatile"
    depth: 5
  signal_when:
    condition: "published"
    timeout: 2
    safety_critical: false
    autonomy_critical: true
  signal_lambdas:
    - expression: "lambda x: x.height < 480"
      timeout: 2
      safety_critical: true
      autonomy_critical: false
  execute: []                  # optional shell / ROS actions
  timeout: 10
  default_notifications: false

---

node_monitors: (NodeMonitors)

Fields

Field	Type	Req	Description
name	string	✔	Exact node name (/camera_driver)
timeout	sec	✔	Max age since last seen
safety_critical	bool	•	Flip safety beat when missing
autonomy_critical	bool	•	Flip warning beat when missing
poll_rate	Hz	•	Graph query rate (default 1.0)
tags	list	•	Labels

Example Node Monitor

node_monitors:
  - name: "/front_camera_camera_controller"
    timeout: 2.0
    safety_critical: true
    autonomy_critical: false

  - name: "/back_camera_camera_controller"
    timeout: 1.0
    safety_critical: false
    autonomy_critical: true

---

Heartbeats

Safety heartbeat (safety/heartbeat)

• Publishes std_msgs/Bool
• TRUE when all safety-critical monitors are satisfied for safe_operation_timeout
• FALSE immediately on first safety-critical failure

Warning heartbeat (warning/heartbeat)

• Publishes std_msgs/Bool
• TRUE when all autonomy-critical monitors are satisfied
• FALSE on first autonomy-critical failure
  (use for degradations that allow limp-home operation)

---

Quick checklist

• ✔ Every topic lists message_type and rate.
• ✔ Mark each rule/node as safety_critical or autonomy_critical (or both).
• ✔ No critical flag ⇒ the rule is informational only.
• ✔ Adjust parameters at launch:

ros2 run sentor test_sentor.py \
  --ros-args \
    -p config_file:=/path/to/monitor.yaml \
    -p safety_pub_rate:=1.0 \
    -p safe_operation_timeout:=5.0

Note

• /safety/heartbeat toggles TRUE only when all safety-critical items pass.

• /warning/heartbeat toggles TRUE when autonomy-critical items pass.

• Killing a safety-critical publisher flips both beats to FALSE immediately.

• Killing only an autonomy-critical node flips warning beat but leaves safety unchanged.

• If desired, run ros2 topic echo /safety/heartbeat and /warning/heartbeat in separate terminals to verify.

---

Runing with robot state machine

• Start joystick package - ros2 launch teleop_twist_joy teleop-launch.py joy_config:='xbox'
• Launch sentor - ros2 launch sentor sentor_launch.py
• Launch state machine - ros2 run robot_state_machine robot_state_machine_sentor
• Launch joy state machine node - ros2 run robot_state_machine joy_robot_state_machine
• Launch ardunio bridge (on real robot) - ros2 run robot_state_machine bridge_to_arduino
• Launch sentor guard - ros2 launch sentor_guard guard_example.launch.py

Logitech buttons:

• X button - switch to manual mode
• Y button - switch to autonomous mode
• LB (Left bumper) - hold for manual movement (deadman button)
• RB (Right bumper) - enable/activate button

Topics:

• Sentor:
  • ros2 topic echo /safety/heartbeat
  • ros2 topic echo /warning/heartbeat
• State Machine:
  • ros2 topic echo /robot_state
  • ros2 topic echo /autonomous_mode