The rclc_lifecycle package

Overview

The rclc_lifecycle package is a ROS 2 package and provides convenience functions to bundle a ROS Client Library (RCL) node with the ROS 2 Node Lifecycle state machine in the C programming language, similar to the rclcpp Lifecycle Node for C++.

The quality declaration is available in QUALITY_DECLARATION.md.

API

The API of the RCLC Lifecycle Node can be divided in several phases: Initialization, Running and Clean-Up.

Initialization

Creation of a lifecycle node as a bundle of an rcl node and the rcl Node Lifecycle state machine:

#include "rclc_lifecycle/rclc_lifecycle.h"

rcl_allocator_t allocator = rcl_get_default_allocator();
rclc_support_t support;
rcl_ret_t rc;

// create rcl node
rc = rclc_support_init(&support, argc, argv, &allocator);
rcl_node_t my_node;
rc = rclc_node_init_default(&my_node, "lifecycle_node", "rclc", &support);

// rcl state machine
rcl_lifecycle_state_machine_t state_machine_ =
  rcl_lifecycle_get_zero_initialized_state_machine();
...

// create the lifecycle node
rclc_lifecycle_node_t lifecycle_node;
rcl_ret_t rc = rclc_make_node_a_lifecycle_node(
  &lifecycle_node,
  &my_node,
  &state_machine_,
  &allocator);

Register lifecycle services and optionally create callbacks for state changes. Executor needsto be equipped with 1 handle per node and per service:

// Executor
rclc_executor_t executor = rclc_executor_get_zero_initialized_executor();
rclc_executor_init(
  &executor,
  &support.context,
  4,  // 1 for the node + 1 for each lifecycle service
  &allocator));
...

// Register lifecycle services
rclc_lifecycle_add_get_state_service(&lifecycle_node, &executor);
rclc_lifecycle_add_get_available_states_service(&lifecycle_node, &executor);
rclc_lifecycle_add_change_state_service(&lifecycle_node, &executor);

// Register lifecycle service callbacks
rclc_lifecycle_register_on_configure(&lifecycle_node, &my_on_configure);
rclc_lifecycle_register_on_activate(&lifecycle_node, &my_on_activate);
...

Cleaning Up

To clean everything up, do:

rc += rcl_lifecycle_node_fini(&lifecycle_node, &allocator);
...

Example

An example, how to use the RCLC Lifecycle Node is given in the file lifecycle_node.c in the rclc_examples package.

Limitations

• Lifecycle services cannot yet be called via ros2 lifecycle CLI, e.g., ros2 lifecycle set /node configure. Instead use the ros2 service CLI, e.g., ros2 service call /node/change_state lifecycle_msgs/ChangeState "{transition: {id: 1, label: configure}}".

Changelog for package rclc_lifecycle

4.0.2 (2022-03-22)

• none

4.0.1 (2022-07-20)

• improved doxygen-generated API documentation (#301) (#302)

4.0.0 (2022-04-28)

• updated version for Humble release

3.0.8 (2022-04-14)

• Fix rclc lifecyle header (#279) (#281)

3.0.7 (2022-02-17)

• no changes

3.0.6 (2022-01-25)

• Create service context in main (#224)

3.0.5 (2021-11-23)

• no change

3.0.4 (2021-11-17)

• Provide lifecycle services in the rclc lifecycle nodes (#51)

3.0.3 (2021-07-28)

• Version bump

3.0.2 (2021-07-26)

• Version bump

3.0.1 (2021-07-17)

• Added quality declaration statement

2.0.0 (2021-04-23)

• added codecov support
• new API of rcl_lifecycle in Rolling required major version bump

1.0.1 (2021-03-29)

• Windows port
• Compatibility sleep function (Windows, POSIX-OS)
• Fixed RCL lifecycle API change for Rolling

1.0.0 (2021-03-04)

• Updated version

0.1.7 (2021-01-20)

• Updated version

0.1.6 (2021-01-20)

• Updated version

0.1.5 (2020-12-11)

• Updated version

0.1.4 (2020-11-25)

• Fixed error in bloom release

0.1.3 (2020-11-23)

• Aligned version number to rclc repository

0.1.0 (2020-11-23)

• Initial release