Lifecycle interface

Core lifecycle for modular robotics systems

Configure · Activate · Run · Transition · Shutdown

lifecore_ros2

Explicit lifecycle composition for ROS 2 Jazzy

lifecore_ros2 is a minimal lifecycle composition library for ROS 2 Jazzy — no hidden state machine.

ROS 2 lifecycle works well for nodes. lifecore_ros2 makes it practical for reusable components.

It provides a small composition layer for building lifecycle-managed ROS 2 nodes from explicit, reusable components. Instead of concentrating lifecycle behavior in one large rclpy node class, it lets a lifecycle node own named components and drive their hooks through the native ROS 2 transition flow.

Quickstart Mental Model API Reference

⚙ Configure

Start with environment setup, resource creation rules, and the ownership model that keeps ROS handles explicit.

▶ Activate

Read how runtime behavior becomes live only through lifecycle transitions and explicit activation gates.

▶ Run

Move into examples and API lookup once the lifecycle contract is clear.

🔁 Transition

Use architecture and patterns to understand propagation, registration, and failure handling.

■ Shutdown

Keep cleanup and release semantics in view so resources never outlive the lifecycle that created them.

Raw rclpy lifecycle:
LifecycleNode
 ├── publishers
 ├── subscriptions
 ├── timers
 └── lifecycle logic mixed into one class

lifecore_ros2:
LifecycleComponentNode
 ├── LifecyclePublisherComponent
 ├── LifecycleSubscriberComponent
 └── LifecycleTimerComponent

The library exists to make raw rclpy lifecycle code easier to structure and verify. Resource creation, activation, deactivation, and cleanup stay explicit; component boundaries stay testable; and the library does not add a second state machine behind ROS 2 lifecycle semantics.

What this is not

  • A second lifecycle state machine.

  • A plugin system or ROS 2 component container replacement.

  • A behavior tree system, orchestration middleware, or launch replacement.

  • A replacement for native ROS 2 lifecycle semantics.

Why lifecore_ros2?

  • Explicit lifecycle flow from configure to activate, deactivate, and cleanup.

  • Component ownership is centered in LifecycleComponentNode.

  • Activation and deactivation behavior stays predictable and visible in code.

  • No hidden state machine beyond native ROS 2 lifecycle semantics.

  • Testable component boundaries with small lifecycle hooks.

When to use it

  • Composed robotics nodes built from multiple lifecycle-aware parts.

  • Lifecycle-managed publishers and subscribers.

  • Reusable ROS 2 components with explicit ownership and cleanup.

  • Projects that need strict startup, pause, resume, and shutdown behavior.

Start here

Begin with the guides below. They explain the library’s lifecycle model, ownership rules, and recommended usage before you jump into symbol-level API details.

Read the docs like a lifecycle. Quickstart gets a node running, Getting Started fixes the environment contract, Mental Model explains ownership, Architecture defines transition rules, and Examples shows the contract under load.

Quickstart

Install from PyPI for an application project, or clone the repository to run the smallest composed lifecycle example.

Getting Started

Review prerequisites, validation commands, and reference setup details after the quickstart.

Mental Model

Build the right lifecycle composition intuition before diving into lifecycle internals and extension points.

Architecture

Read the lifecycle ownership model, transition rules, and component contracts.

Recommended Patterns and Anti-Patterns

Learn the concrete practices that keep components explicit, testable, and lifecycle-aligned.

Testing Utilities

Reuse fakes, fixtures, assertions, and helpers for lifecycle-focused tests.

Examples

Walk through runnable publisher, subscriber, and composed node examples.

Migration from Raw rclpy

Compare the library approach with direct lifecycle code in rclpy.
Need a side-by-side comparison? Use the sensor watchdog comparison in the companion examples repository to compare the same node behavior across plain ROS 2, classic lifecycle, and lifecore_ros2.

Documentation map

The guides section is the recommended reading path for new users. Use the API reference afterward as a lookup surface for classes, methods, and module details.

Lifecycle-oriented reading order:

  1. Configure the environment and first node with Quickstart and Getting Started.

  2. Activate the mental model with Mental Model.

  3. Understand transition ownership with Architecture and Recommended Patterns and Anti-Patterns.

  4. Test lifecycle boundaries with Testing Utilities.

  5. Run concrete flows with Examples, then use the companion sensor watchdog comparison for a side-by-side view against plain ROS 2 and classic lifecycle before comparing tradeoffs in Migration from Raw rclpy.

Guides

API Reference

Planning

Project

Design notes