Zephyr FMS: Fault Monitoring System for Zephyr

[vahanesac]

Hi Zephyr community,

I am sharing the Fault Monitoring System (FMS), the first pre-release subsystem from Zephyr Commons.

Many Zephyr applications start with checks such as:

• temperature > maximum
• voltage < minimum
• connection == lost
• error_count > limit

What grows around those checks is usually more complicated: timers, recovery handling, latching, priorities, callbacks, and diagnostic information.

FMS packages that repeated logic into a reusable Zephyr module.

How it works

Concept	What it means
Fault	A state your application needs to react to, such as MOTOR_THERMAL or COMMUNICATION_LOSS
Monitor	One condition that can activate a fault
Comparator	The function that checks a value, such as temperature > 80
Priority	Determines which active monitor is reported as the most important cause

For example, one MOTOR_THERMAL fault could have:

• A warning monitor when temperature stays above 80°C
• A shutdown monitor when temperature stays above 100°C
• Different trigger times and priorities for each monitor
• Latching on the shutdown monitor so it remains active until reset

If both monitors are active, FMS reports the shutdown monitor as the leading cause while still keeping both monitors in the active set.

What FMS provides

Feature	What it gives the application
Multiple monitors per fault	Up to 32 different conditions can contribute to one fault
Trigger delay	A condition must remain unhealthy for a configured time before activating
Recovery delay	A condition must remain healthy for a configured time before clearing
Latching	Important monitors can remain active until explicitly reset or disabled
Monitor priorities	Priorities range from 0–127; lower numbers have higher priority
Complete active-cause tracking	Query the leading monitor, active count, active mask, and priority
Duration tracking	Query how long faults and monitors have been active
Transition callbacks	Receive a callback when a fault becomes active or clears
Monitor control	Enable, disable, or reset monitors at runtime
Fault-level monitor control	Enable or disable every monitor associated with a fault
Manual fault control	Set or clear a fault from service, test, or application code
Value overrides	Temporarily replace a monitored value for testing or fault injection
Built-in comparators	Common integer comparisons are included
Custom comparators	Applications can evaluate their own values, states, or health conditions
Two processing options	Use the built-in FMS worker or call fms_process() from your own loop
Static configuration	Faults and monitors are created at build time with no heap allocation or runtime registration
Thread-safe APIs	Application supervisor threads can safely query and control FMS after initialization
Optional names and logging	Keep readable fault and monitor names when diagnostics require them

FMS does not read sensors or decide how the product should respond to a fault. The application owns the data and reaction policy. FMS handles the timing, state changes, multiple-cause tracking, priority selection, and notifications.

The repository includes:

• A QEMU sample using the built-in FMS worker
• A QEMU sample using application-owned processing
• Integration and API documentation
• Host tests and Zephyr runtime tests

This is currently pre-release work, verified against Zephyr v4.2.0. We’re looking for feedback on the API, the multiple-monitor model, the processing options, and how FMS fits real Zephyr applications.

Repository, documentation, and runnable samples:

https://github.com/zephyrium-labs/zephyr-commons