Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |
System Dependencies
Dependant Packages
Launch files
Messages
Services
Plugins
Recent questions tagged ros2_medkit_fault_detection at Robotics Stack Exchange
Package Summary
| Version | 0.7.2 |
| License | Apache-2.0 |
| Build type | AMENT_CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Description | |
| Checkout URI | https://github.com/selfpatch/ros2_medkit.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-19 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Maintainers
- mfaferek93
Authors
ros2_medkit_fault_detection
Shared, protocol-agnostic fault-detection model for medkit gateway plugins. A single evaluator maps a raw value read from any source (OPC UA, S7, Modbus, ADS, …) to the set of faults it implies, so every protocol plugin detects faults the same way.
Detection modes
Composable per mapped point in a plugin’s node map:
-
threshold (
ThresholdRule) - numeric above/below a setpoint. A boolean point is alarm-on-true. -
status word (
StatusWordRule) - decode named bits of an integer status register; one fault per configured bit. -
fault enum (
EnumMapRule) - map a fault-code register value to a fault code + text; one fault per configured code, with anok_valuemeaning “no fault”.
API
#include "ros2_medkit_fault_detection/fault_detection.hpp"
namespace fd = ros2_medkit::fault_detection;
// Pure evaluator: value + rule -> set of (active/inactive) fault signals.
std::vector<fd::FaultSignal> signals = fd::evaluate(value, rule);
// Stateful raise/clear edge detector over successive evaluations.
fd::FaultTransitionTracker tracker;
std::vector<fd::FaultSignal> transitions = tracker.apply(signals); // raises + clears
evaluate reports the full set of faults a rule governs (each flagged active
or inactive). FaultTransitionTracker keeps the last-known state per
fault_code and emits only the raise/clear edges, which a plugin forwards to
the fault manager as report/clear.
Waiting before a raise
One bad reading is enough for evaluate to call a fault active. A bridge that
reports on that edge sends one EVENT_FAILED, which the fault manager’s debounce
cannot filter, so the filter has to sit where the samples are. A
RaiseQualifier makes a rule wait: the condition must be seen on min_samples
new samples in a row and must hold for min_duration without a break (both,
when both are set). The default raises on the first sample, as before.
fd::RaiseQualifier q;
q.min_samples = 3;
q.min_duration = std::chrono::milliseconds(2000);
fd::RaiseQualifierFilter filter; // between evaluate and the tracker
auto edges = tracker.apply(filter.apply(fd::evaluate(value, rule), q, now, fresh));
- A fault that is still waiting goes out as inactive, so nothing is raised.
- Only the raise waits. The first inactive sample clears at once and the next raise has to qualify again.
-
freshsays whether the call carries a new sample. Only fresh samples count towardmin_samples. A call that is not fresh can still completemin_duration, so a source that reports changes only can be re-checked on a timer. Do not pass a value that could not be read: that is unknown, not unchanged. - An undecidable value (no signal) keeps the wait as it is.
-
reset_pending()drops faults that are still waiting, for example when the connection is lost. Faults already raised stay raised.has_pending()tells a change-driven caller whether it needs to call again on a timer. - A source that reports changes only has no samples to count. Use
q.for_change_notifications(period)there:min_samplessamplesperiodapart become a wait of(min_samples - 1) x period, ormin_durationwhen that is longer. Then passfresh = truefor a change of the point andfresh = falsefor a timer call.
Shared fault types
fault_types.hpp holds the std-only types that the ROS-free fault reporter core and fault manager core
exchange: ReportKind, FaultReport, FaultRecord, FaultEventRecord, and the
constants for severity, fault status and fault event type. They mirror Fault.msg, FaultEvent.msg
and ReportFault.srv in ros2_medkit_msgs. Times are int64_t nanoseconds since the Unix epoch;
0 means never. The ROS adapters of both packages convert to and from the messages at their edge.
cmake/fault_reporter_core.cmake and cmake/fault_manager_core.cmake define an INTERFACE target
ros2_medkit_fault_detection for include/ of this package when the ament target is absent. That lets
the cores build with plain CMake. See the READMEs of ros2_medkit_fault_reporter and
ros2_medkit_fault_manager.
Placement and packaging
This is a header-only INTERFACE package: the detection logic is compiled
directly into each consuming plugin. Protocol plugins are built as MODULE
libraries that resolve gateway symbols from the host process at load time
(-Wl,--unresolved-symbols=ignore-all); a separately linked shared library
would not be present in that host, so the logic is compiled in instead. The
header has no ROS or protocol dependencies, which keeps the evaluator a pure,
trivially unit-testable function.
It lives in the open ros2_medkit repo so both the open OPC UA plugin
(ros2_medkit_opcua) and future protocol plugins can depend on it.
File truncated at 100 lines see the full file
Changelog for package ros2_medkit_fault_detection
0.7.2 (2026-11-19)
- No changes. Version aligned with the rest of the stack
0.7.1 (2026-11-18)
- A rule can wait before it raises a fault: for a number of samples or for a time. For a source that only reports changes, a samples rule becomes a wait (#767)
- Contributors: \@ahmedsleem109, \@bburda
0.7.0 (2026-08-27)
- Initial release of the package: shared, protocol-agnostic
fault-detection model for medkit gateway plugins. A single
header-only evaluator maps a raw value read from any source (OPC UA,
S7, Modbus, ADS, ...) into the set of faults it implies, using one
of three composable detection modes:
ThresholdRule(numeric above/below a setpoint),StatusWordRule(decode named bits of an integer status register, with optional source-width masking to drop sign-extended high bits), andEnumMapRule(map a fault-code register value to a fault code + text, with an optional catch-all for unmapped values) (#481). -
evaluate(value, rule)is a pure function with no ROS / protocol dependencies, so it is trivially unit-testable and safe to compile into a dlopen-loaded plugin MODULE. Undecidable input (a non-finite double, a string, a failed numeric conversion) yields an empty result so a transition tracker holds the prior state instead of clearing a standing fault - a bad read never masks a real alarm. -
FaultTransitionTrackerlayers stateful raise/clear edge detection on top, keyed byfault_codealone; consumers that share one tracker across many points must enforce global fault-code uniqueness at config-load time. - Shipped as a header-only INTERFACE library (
cxx_std_17); theOPC UAplugin is the first consumer and migrates its threshold / status-bit / enum detection onto this module. - Global fault-code uniqueness is enforced across an OPC UA node map, so two rules cannot claim the same code and leave which one raised it undefined (#486)
- A tracker holds its prior state on an undecidable read instead of clearing a standing fault, and an enum value with no mapping is labelled rather than dropped (#486)
- Build and test only: the package is instrumented for coverage (#582), and its test is registered through the shared macros and opted out of DDS domain allocation, the evaluator being pure logic with no ROS node (#597)
- Contributors: \@mfaferek93, \@bburda
Package Dependencies
| Deps | Name |
|---|---|
| ament_cmake | |
| ros2_medkit_cmake | |
| ament_lint_auto | |
| ament_lint_common | |
| ament_cmake_clang_format | |
| ament_cmake_gtest |