Getting Started¶

Lifecycle interface

Core lifecycle for modular robotics systems

Start from the shortest runnable path, then follow the same lifecycle vocabulary used by the library.

Need the shortest runnable path first? Start with Quickstart. This page remains the reference for prerequisites, validation commands, and documentation tooling.

Audience¶

This page is for developers who want to understand or try the repository with ROS 2 Jazzy.

Prerequisites¶

Python 3.12 or newer
ROS 2 Jazzy installed on the system
uv available in the workspace

Environment Notes¶

The project expects rclpy to come from the system ROS installation. It should not be added as a normal PyPI dependency of the package.

Install Paths¶

For an application project that consumes the library from PyPI:

source /opt/ros/jazzy/setup.bash
uv add lifecore-ros2

For a development checkout of this repository, use the local dependency setup below instead.

Lifecycle Landmarks¶

⚙ Configure

Install ROS 2 Jazzy, keep rclpy system-provided, and sync the workspace with uv.

▶ Activate

Enable the developer toolchain with lint, format, type-check, and test commands that match the repository defaults.

▶ Run

Build the docs and exercise examples before diving into API details.

🔁 Transition

Move from quick validation into the conceptual model and architecture pages.

■ Shutdown

Keep cleanup semantics in mind: configured resources are meant to be released explicitly during lifecycle cleanup.

Install Development Dependencies¶

Use uv to sync the default project environment with development tools:

uv sync --extra dev

If you want the documentation toolchain as well:

uv sync --extra dev --group docs

Common Validation Commands¶

The repository currently uses these commands:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

Build the Documentation¶

The Sphinx documentation can be built with:

uv run --group docs python -m sphinx -b html docs docs/_build/html

The generated HTML output is written to docs/_build/html.

Lifecycle reading path. The onboarding flow mirrors the library vocabulary: configure the environment, activate tooling, run validation, then transition into the mental model before you rely on API details.

Repository Concepts¶

For the intended conceptual model before reading API details, start with Mental Model.

The architecture is organized around:

LifecycleComponentNode as the lifecycle-aware orchestrator
LifecycleComponent as the base managed entity for reusable logic
topic-oriented components for publishers and subscribers

Lifecycle rules used by the repository:

create ROS resources during configure
enable or gate runtime behavior during activate and deactivate
release ROS resources during cleanup

These rules keep component behavior explicit and aligned with native ROS 2 lifecycle semantics.

Applied Comparison Example¶

Once the local environment works, continue with Examples for the runnable examples shipped in this repository.

If you want one applied scenario that compares the same watchdog behavior across plain ROS 2, classic lifecycle, and lifecore_ros2, use the sensor watchdog comparison in lifecore_ros2_examples. That companion README keeps the commands, lifecycle transitions, and expected /sensor/status and log signals in one place.