Note

You're reading the documentation for a development version. For the latest released version, please have a look at Lyrical.

Client libraries

Client libraries in ROS provide the APIs that developers use to create nodes, communicate between processes, and access core system functionality. This article explains the supported client libraries, how they relate to lower-level ROS interfaces, and how they enable development in different programming languages.

Area: client-libraries, framework | Content type: about | Level: beginner

Client libraries are the APIs that allow you to implement your ROS code. This article explains rcl, the shared core library, and the main C++ and Python client libraries. With this information, you can choose the right library for your language and understand how nodes written in different languages work together.

Summary

Client libraries are the APIs that allow you to implement your ROS code.

The common core library is the ROS Client Library (RCL).

The main language-specific libraries are:

• C++ client library (rclcpp)

• Python client library (rclpy)

Client libraries in ROS

Client libraries are maintained in a variety of programming languages so that you can write ROS code in the language that is best-suited for your application. For example, you might prefer to write visualization tools in Python because it makes prototyping iterations faster, while for parts of your system that are concerned with efficiency, the nodes might be better implemented in C++.

Client libraries expose the core functionality of ROS. For example, through a client library, you can access the following:

• Names and namespaces

• Time (real or simulated)

• Parameters

• Console logging

• Threading model

• Intra-process communication

All client libraries implement code generators which allow you to interact with ROS interface files. These interface files then allow nodes written with different client libraries to exchange messages. For a walkthrough of the message exchange between a publisher using the Python library and a subscription using the C++ library, we encourage you to watch this ROSCon talk starting at 17:25 (see the slides here).

ROS Client Library (rcl)

Most of the functionality of a client library is not specific to its programming language. For example, parameters and namespaces should behave the same across all programming languages. Client libraries in ROS use a common core ROS Client Library (rcl) interface that implements logic and behaviour of ROS concepts.

Each language-specific library only wraps rcl rather than re-implementing the logic. As a result, a change made to logic or behaviour in rcl, such as namespaces, applies to every library that wraps it.

The C++ client library (rclcpp) and the Python client library (rclpy) are both core client libraries which use common functionality in rcl. By using the rcl API in the implementation of a language-specific client library, it remains with the other client libraries that also use rcl in terms of feature parity and behaviour.

Client library concepts that require language-specific features or properties are not implemented in the rcl but instead are implemented in the language-specific client libraries. For example, threading models used by “spin” functions will have implementations that are specific to the language of the client library.

The rclcpp package

The ROS Client Library for C++ (rclcpp) is the user-facing, idiomatic C++ interface that provides all of the ROS client functionality, such as creating nodes, publishers, and subscriptions. rclcpp builds on rcl and the rosidl API, and is designed to be used with the C++ messages generated by rosidl_generator_cpp. rclcpp uses C++20 features to make the interface as easy to use as possible, but because it reuses the implementation in rcl, it maintains consistent behaviour with the other client libraries that use the rcl API.

The rclpy package

The ROS Client Library for Python (rclpy) provides an idiomatic Python experience that uses native Python types and patterns, such as lists and context objects.

Like the C++ client library, rclpy builds on top of the rcl C API for its implementation, to maintain a consistent behaviour with the other client libraries that use the rcl API. In addition to providing Python idiomatic bindings around the rcl API and Python classes for each message, the rclpy takes care of the execution model, using threading.Thread or similar to run the functions in the rcl API.

Note

rclpy generates custom Python code for each ROS message you interact with. Unlike rclcpp, it converts the native Python message object into the C version of the message. All operations happen on the Python version of the message until it needs to be passed into the rcl layer, at which point it is converted into the C version for the rcl C API. For publishers and subscriptions in the same process, rclpy avoids this conversion where possible, to cut down on converting into and out of Python.

Related content

Related articles

• How ROS works

• Nodes

• Parameters

• Interfaces (topics, services, actions)

Related packages

Core ROS packages

• ROS client library (rcl): Library to support implementation of language-specific ROS Client Libraries. The API documentation for rcl is at https://docs.ros.org/en/rolling/p/rcl/.

• ROS Client Library for C++ (rclcpp): rclcpp provides the canonical C++ API for interacting with ROS. The generated API documentation is at https://docs.ros.org/en/rolling/p/rclcpp/.

• ROS Client Library for Python (rclpy): rclpy provides the canonical Python API for interacting with ROS. The generated API documentation is at https://docs.ros.org/en/rolling/p/rclpy/.

Community packages

• GoLang: rclgo - GoLang bindings for ROS.

• Ada: This is a set of packages (binding to rcl, message generator, binding to tf2, examples and tutorials) that allows the writing of Ada applications for ROS.

• C: rclc does not put a layer on top of rcl but complements rcl to make rcl+rclc a feature-complete client library in C. See micro.ros.org for tutorials.

• JVM and Android: Java and Android bindings for ROS.

• .NET Core, UWP and C#: This is a collection of projects (bindings, code generator, examples and more) for writing ROS applications for .NET Core and .NET Standard.

• Node.js: rclnodejs is a Node.js client for ROS. It provides a simple and easy JavaScript API for ROS programming.

• Rust: This is a set of projects (the rclrs client library, code generator, examples and more) that enables developers to write ROS applications in Rust.

• Flutter and Dart: Flutter and Dart bindings for ROS.

FAQs

What is a client library?

A client library is the API you use to write ROS code in a given programming language. It gives you access to core ROS concepts such as nodes, topics, services, parameters, and logging.

Can nodes written with different client libraries communicate?

Yes. Client libraries generate language bindings for ROS interface files, so nodes can share messages even when they use different languages, for example rclcpp and rclpy.

What is the ROS Client Library (rcl)?

rcl is the common C core that implements language-independent ROS behaviour, such as parameters and namespaces. Language-specific client libraries wrap rcl instead of reimplementing that shared logic.

Why does ROS use a common rcl core?

Shared behaviour stays consistent across languages, and bug fixes or behaviour changes in rcl apply to every client library that uses it. That also keeps the language-specific libraries thinner and easier to maintain.

Is all client library behaviour implemented in rcl?

No. Features that depend on the programming language, such as the threading model used by spin functions, are implemented in each client library rather than in rcl.