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 = rcl_get_zero_initialized_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);

Optionally create hooks for lifecycle state changes.

// declare callback
rcl_ret_t my_on_configure() {
  printf("  >>> lifecycle_node: on_configure() callback called.\n");
  return RCL_RET_OK;
}
...

// register callbacks
rclc_lifecycle_register_on_configure(&lifecycle_node, &my_on_configure);

Running

Change states of the lifecycle node, e.g.

bool publish_transition = true;
rc += rclc_lifecycle_change_state(
  &lifecycle_node,
  lifecycle_msgs__msg__Transition__TRANSITION_CONFIGURE,
  publish_transition);
rc += rclc_lifecycle_change_state(
  &lifecycle_node,
  lifecycle_msgs__msg__Transition__TRANSITION_ACTIVATE,
  publish_transition);
...

Except for error processing transitions, transitions are usually triggered from outside, e.g., by ROS 2 services.

Cleaning Up

To clean everything up, simply 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

The state machine publishes state changes, however, lifecycle services are not yet exposed via ROS 2 services (tbd).

Changelog for package rclc_lifecycle

2.0.2 (2021-07-17)

• Bumped version

2.0.1 (2021-05-28)

• added quality declaration

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