A ROS 2 Lifecycle Node makes functional readiness visible instead of equating a running process with an available robot function. The managed state machine separates resource setup, inactive readiness, active processing and terminal failure. It also provides standard transition services that a supervisor can coordinate.
Lifecycle state is software evidence, not a physical safety state. A camera can be Active while blinded, and an Inactive actuator node can leave a drive energized unless its implementation explicitly inhibits output. Every transition needs prerequisites, timeout behavior and a connection to the robot operating state.
Use this guide with the Physical AI safety-layer guide and ros2_control hardware-interface guide. Test failure transitions as deliberately as the normal startup sequence.
Separate process health from functional readiness
A process can exist, answer graph discovery and still lack calibrated sensors, device communication or valid configuration. Managed states let the system report that distinction. Operators and supervisors should display process, lifecycle, hardware and application states separately rather than compressing them into one green indicator.
Define what each node promises while Unconfigured, Inactive and Active. Include publications, subscriptions, services, device outputs and retained data. A consumer should know whether an inactive publisher becomes silent, publishes an invalid marker or holds a last value.
Use the four primary states consistently
The ROS 2 managed-node design defines Unconfigured, Inactive, Active and Finalized primary states, with intermediate transition states for configuring, activating, deactivating, cleaning up, shutting down and error processing. External management normally requests transitions and observes the result.
The ROS 2 managed-node design describes the intended semantics. An implementation should not call itself lifecycle compliant while continuing normal processing in Inactive or hiding a failed transition. Document any behavior added around the standard state machine.
| State | Resources | Functional processing | Robot requirement |
|---|---|---|---|
| Unconfigured | Minimal | No | Outputs inhibited |
| Inactive | Prepared | Managed work stopped | No hazardous command |
| Active | Operational | Enabled | All activation gates valid |
| Finalized | Held for inspection | No | Physical safe state preserved |
| Error processing | Recovery dependent | Restricted | Bounded fault response |
Configure resources without commanding motion
Configuration can allocate memory, create managed publishers and subscriptions, load parameters, open devices and validate static setup. Long-lived resources belong here when they are needed in both Inactive and Active states. The callback should return failure when readiness cannot be established.
Opening a drive or sensor may itself change physical behavior. Specify enable lines, brakes, watchdogs and initial commands before configuration. If configuration partially succeeds, release or quarantine each acquired resource so a retry does not inherit an unknown device state.
Make Inactive a verifiable operating condition
Inactive means prepared but not performing normal managed processing. It is useful for inspection, parameter change and dependency coordination. For a motion-producing node, verify that timers, publishers or hardware paths cannot continue sending hazardous output from the previous Active period.
Test entry from configuration and deactivation. Observe queues and durability because messages can accumulate while callbacks are not processed. When activation later begins, reject data older than the application’s validity limit instead of consuming a backlog as if it were current.
Gate activation with current prerequisites
Activation should be short and deterministic because heavy initialization belongs in configuration. Before requesting it, the supervisor should verify required nodes, valid calibration, synchronized time, current sensor data, hardware mode and applicable safety conditions. Each gate needs an owner and expiry.
Activation success should mean the node can meet its declared service, not merely that on_activate returned success. Publish evidence such as first valid sample, established device mode or controller claim. Block downstream activation until that evidence is current.
| Transition | Precondition | Timeout action | Evidence |
|---|---|---|---|
| Configure | Parameters and device reachable | Return failure | Resource inventory |
| Activate | Dependencies and valid data | Remain Inactive | First valid output |
| Deactivate | Stop request accepted | Escalate safe response | Output inhibited |
| Cleanup | Resources releasable | Enter error handling | No retained ownership |
| Recover | Fault cause removed | Bound retries | Fresh readiness checks |
Distinguish deactivation from cleanup
Deactivation reverses Active-only behavior and returns the prepared node to Inactive. Cleanup releases configured resources and returns to Unconfigured. Treating both as generic stop operations makes restart slow and can leave ownership ambiguous.
Measure how long output takes to cease after deactivation is requested. If a node does not respond, a supervisor service call cannot be the only protective mechanism. Independent hardware or system-level timeout handling must enforce the required physical response.
Use on_error as a bounded decision point
Error processing should clean up enough state to reach a known destination or admit that recovery failed. An unconditional success followed by configure and activate can create an infinite restart loop that repeatedly energizes faulty hardware or floods the network.
Classify transient, persistent and integrity-threatening faults. Set retry count, delay, backoff and escalation for each class. Preserve the first fault and recovery attempts in logs. Require a human or higher-level reset when evidence cannot prove the cause has cleared.
Let supervisors coordinate without replacing node responsibility
A lifecycle manager knows desired ordering and can call transitions, but each node remains responsible for accurate readiness, safe callbacks and local resource cleanup. If the manager disappears, nodes do not automatically become physically safe unless the system explicitly monitors that loss.
Define supervisor heartbeat, ownership election and restart behavior. Avoid two managers issuing conflicting transitions. If management communication is lost, choose whether nodes hold, deactivate or enter another application state based on the risk assessment.
Build startup from a dependency graph
Start order should follow readiness dependencies rather than a fixed sleep. Time synchronization may precede sensors; calibrated sensors may precede state estimation; valid state may precede planning; claimed hardware and safe mode may precede control activation.
Represent each edge as an observable condition with a timeout. Parallelize independent branches, but roll back dependents in reverse order when an upstream promise disappears. A node that remains Active while its source becomes invalid should publish degraded state or deactivate according to contract.
Test transient, persistent and cascading faults
Inject a delayed sensor, unavailable device, invalid parameter, exception, failed transition, dead supervisor and loss of an already-active dependency. Verify lifecycle state, physical output, diagnostic identity, retry limits and time to recovery or escalation.
Cascading tests matter because one node’s deactivation can block another node’s callback or leave queued commands. Run recovery under CPU and network load. A sequence that works on an idle bench can time out differently on the production computer.
Record normal and failed transitions equally
Log transition request, requester, previous state, start time, completion time, result, reason and resulting physical mode. Correlate these events with hardware and application logs on one clock. A state label without timing cannot explain a delayed stop or partial restart.
Track transition latency and failure frequency, but do not optimize success rate by weakening prerequisites. The most important acceptance criterion is that the system never becomes Active when required evidence is absent or stale.
Version a lifecycle recovery contract
Store node version, parameters, dependency graph, transition policy, timeout and recovery limits together. Re-run lifecycle tests after changes to devices, QoS, executor layout or startup orchestration because these can change transition timing.
Use an acceptance checklist that includes physical output, not just ROS service responses.
- Define behavior in every primary state.
- Gate activation with current observable evidence.
- Bound retries and preserve the first fault.
- Test manager loss and cascading dependencies.
- Measure physical output through every transition.
Frequently asked questions
Do Lifecycle Nodes make a robot automatically safe?
No. They expose software state and transitions. Physical safety requires separate hardware, control and application measures.
Is Inactive the same as a stopped process?
No. The process and configured resources can remain present while managed functional processing is disabled.
Should every fault trigger cleanup and configure?
No. Recovery depends on fault class, resource integrity and whether the cause can be proven cleared.
How should several nodes be activated?
Use observable dependency gates and activate upstream readiness before downstream functions, not fixed delays alone.
What happens if the lifecycle manager fails?
Nothing automatically unless the architecture monitors manager loss and defines a hold, deactivate or safe response.
Lifecycle and Physical Safety Boundary
Lifecycle state is not a safety certification or hardware guarantee. Connect transitions to measured device behavior and independent safeguards appropriate to the robot application.