The rclc repository

This repository provides the rclc package, which complements the ROS Client Support Library (rcl) to make up a complete ROS 2 client library for the C programming language. That is, rclc does not add a new layer of types on top of rcl (like rclcpp and rclpy do) but only provides convenience functions that ease the programming with the rcl types. New types are introduced only for concepts that are missing in rcl, most important an Executor, Lifecycle Node and the Parameter server.

In detail, this repository contains four packages:

• rclc provides the mentioned convenience functions for creating instances of publishers, subscriptions, nodes, etc. with the corresponding rcl types. Furthermore, it provides the rclc Executor for C, analogously to rclcpp’s Executor class for C++. A key feature compared to the rclcpp Executor is that it includes features for implementing deterministic timing behavior.
• rclc_lifecycle introduces an rclc Lifecycle Node, bundling an rcl Node and the lifecycle state machine from the rcl_lifecycle package.
• rclc_examples provides small examples for the use of the convenience functions and the rclc Executor, as well as a small example for the use of the rclc Lifecycle Node.
• rclc_parameter provides convenience functions for creating parameter server instances with full ROS2 parameters client compatibility.

Technical information on the interfaces and the usage of these packages is given in the README.md files in the corresponding subfolders.

The quality declarations for the packages are avaiable in QUALITY_DECLARATION.md files in the corresponding subfolders.

Purpose of the project

The software is not ready for production use. It has neither been developed nor tested for a specific use case. However, the license conditions of the applicable Open Source licenses allow you to adapt the software to your needs. Before using it in a safety relevant setting, make sure that the software fulfills your requirements and adjust it according to any applicable safety standards (e.g. ISO 26262).

Requirements, how to build, test and install

Source your ROS2 distribution with source /opt/ros/distribution/setup.bash. This will setup the environment variable $ROS-DISTRO. Clone the repository into a ROS2 workspace (e.g. ~/ros2_ws/) and build the packages using colcon build from the Colcon Command Line Tools. To test the RCLC package run colcon test or if you have multiple repositories in this workspace colcon test --packages-select rclc. For correct installation of the rclc-package do a source ~/ros2_ws/install/local_setup.bash. Then you are ready to run the examples in the rclc_examples package.

The following repositories might not be in the default ROS 2 distribution: osrf_testing_tools_cpp and test_msgs. In this case install them manually:

 sudo apt-get install ros-$ROS_DISTRO-osrf-testing-tools-cpp
 sudo apt-get install ros-$ROS_DISTRO-test-msgs

License

rclc is open-sourced under the Apache-2.0 license. See the LICENSE file for details.

For a list of other open source components included in rclc, see the file 3rd-party-licenses.txt.

Quality assurance

• Coding style:
  • The uncrustify tool is used to check the coding style.
• Linters:
  • The cpplint tool is used to detect common flaws and problems in C/C++ code.
  • The cppcheck tool is used for code analysis.
  • The CMakeLists.txt is checked with lint_cmake and the package.xml with xmllint
• Unit tests:
  • Unit tests based on gtest are located in the rclc/test folder.

Known issues/limitations

Please notice the following issues/limitations:

• The rclc executor is single-threaded. You cannot create nodes in multiple threads and manage the corresponding subscriptions/services/etc. by one executor.

Bloom Release Status of Code Repository ros2/rclc

Bloom release status of the packages in github.com/ros2/rclc/ for amd64 and arm64 architectures and ROS 2 distributions Foxy, Galactic, Humble and Rolling.

Package	Release	amd64	arm64
rclc	Foxy
	Humble
	Iron
	Rolling
rclc_examples
	Foxy
	Humble
	Iron
	Rolling
rclc_lifecycle
	Foxy
	Humble
	Iron
	Rolling
rclc_parameter
	Humble
	Iron
	Rolling

Code coverage

The code coverage is tested with every commit, pull request. Results are available at codecov.

Contribution Guidelines

The present document provides a set of guidelines to which contributors must adhere.

• Contribution Guidelines
  • Contributions Licensing
  • Developer Certificate of Origin

Contributions Licensing

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

Developer Certificate of Origin

Contributors must sign-off each commit by adding a Signed-off-by: ... line to commit messages to certify that they have the right to submit the code they are contributing to the project according to the Developer Certificate of Origin (DCO) Version 1.1.