Skip to content

getting_started.rst

Latest commit

 

History

History
137 lines (92 loc) · 5.06 KB

getting_started.rst

File metadata and controls

137 lines (92 loc) · 5.06 KB
Raw

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 :doc:`Quickstart <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 :doc:`Mental Model <concepts/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 :doc:`Examples <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.