ros2_medkit_fault_reporter

Client library for easy fault reporting to the central FaultManager.

Overview

The FaultReporter library provides a simple API for ROS 2 nodes to report faults. Just call report() when something goes wrong - the fault is immediately confirmed.

Quick Start

#include "ros2_medkit_fault_reporter/fault_reporter.hpp"

class MyNode : public rclcpp::Node {
 public:
  MyNode() : Node("my_node") {
    reporter_ = std::make_unique<ros2_medkit_fault_reporter::FaultReporter>(
        shared_from_this(), get_fully_qualified_name());
  }

  void check_sensor() {
    if (sensor_error_detected()) {
      reporter_->report("SENSOR_FAILURE",
                        ros2_medkit_msgs::msg::Fault::SEVERITY_ERROR,
                        "Sensor communication timeout");
    }
  }

 private:
  std::unique_ptr<ros2_medkit_fault_reporter::FaultReporter> reporter_;
};

That’s it! The fault will be immediately confirmed in FaultManager.

Using with a lifecycle node

FaultReporter also works inside an rclcpp_lifecycle::LifecycleNode — construct it from the node directly (no shared_from_this() needed), typically in on_configure():

#include "rclcpp_lifecycle/lifecycle_node.hpp"
#include "ros2_medkit_fault_reporter/fault_reporter.hpp"

using CallbackReturn = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn;

class MyLifecycleNode : public rclcpp_lifecycle::LifecycleNode {
 public:
  MyLifecycleNode() : LifecycleNode("my_node") {}

  CallbackReturn on_configure(const rclcpp_lifecycle::State &) override {
    reporter_ = std::make_unique<ros2_medkit_fault_reporter::FaultReporter>(
        *this, get_fully_qualified_name());
    return CallbackReturn::SUCCESS;
  }

 private:
  std::unique_ptr<ros2_medkit_fault_reporter::FaultReporter> reporter_;
};

Constructors

FaultReporter can be built from whichever handle you have:

• FaultReporter(rclcpp::Node & node, source_id[, service_name])
• FaultReporter(rclcpp::Node::SharedPtr node, source_id[, service_name])
• FaultReporter(rclcpp_lifecycle::LifecycleNode & node, source_id[, service_name])
• FaultReporter(rclcpp_lifecycle::LifecycleNode::SharedPtr node, source_id[, service_name])
• FaultReporter(node_base, node_graph, node_services, node_params, logger, source_id[, service_name]) — the interface-based constructor the others delegate to, for custom wiring.

Features

• Simple API: Just call report() to report a fault
• Lifecycle node support: Construct from a regular Node or an rclcpp_lifecycle::LifecycleNode
• Local Filtering (optional): Suppress repeated faults until threshold is met
• Per-fault tracking: Each fault_code has independent filtering
• Severity bypass: High-severity faults bypass local filtering

API

report(fault_code, severity, description)

Report a fault occurrence. With default FaultManager settings, the fault is immediately confirmed.

reporter_->report("MOTOR_OVERHEAT",
                  ros2_medkit_msgs::msg::Fault::SEVERITY_ERROR,
                  "Motor temperature exceeded safe limit");

report_passed(fault_code) (Advanced)

Report that a fault condition has cleared. Use this when FaultManager is configured with debounce filtering and healing enabled.

reporter_->report_passed("MOTOR_OVERHEAT");

File truncated at 100 lines see the full file

Changelog for package ros2_medkit_fault_reporter

Forthcoming

• FaultReporter can now be constructed from an rclcpp_lifecycle::LifecycleNode (and from a plain rclcpp::Node reference or explicit node interfaces), enabling use inside lifecycle nodes (#555)
• Contributors: \@zeerekahmad

0.6.0 (2026-06-22)

• No functional changes; version bump for the coordinated 0.6.0 release.
• Contributors: \@bburda

0.5.0 (2026-06-08)

• LocalFilter now debounces PASSED events with the same threshold / window filtering as FAILED, preventing rapid CONFIRMED/CLEARED status cycling from triggering unbounded snapshot recapture (#308)
• Build: adopt the centralized ROS2MedkitWarnings and ROS2MedkitSanitizers cmake modules
• Contributors: \@bburda, \@mfaferek93

0.4.0 (2026-03-20)

• Build: use shared cmake modules from ros2_medkit_cmake package
• Build: auto-detect ccache, centralized clang-tidy configuration
• Contributors: \@bburda

0.3.0 (2026-02-27)

• Multi-distro CI support for ROS 2 Humble, Jazzy, and Rolling (#219, #242)
• Contributors: \@bburda

0.2.0 (2026-02-07)

• Initial rosdistro release
• FaultReporter client library with simple API:
  • report(fault_code, severity, description) - report FAILED events
  • report_passed(fault_code) - report fault condition cleared
  • High-severity faults (ERROR, CRITICAL) bypass local filtering
• LocalFilter for per-fault-code threshold/window filtering:
  • Configurable threshold (default: 3 reports) and time window (default: 10s)
  • Prevents flooding FaultManager with duplicate reports
  • PASSED events always forwarded (bypass filtering)
• Configuration via ROS parameters (filter_threshold, filter_window_sec)
• Thread-safe implementation with mutex-protected config access
• Contributors: Bartosz Burda, Michal Faferek