ROS Client Library (RCL)

The RCL provides the API to initialize, configure, and shutdown a ROS node. This includes:

• Creating a node context and handle.
• Managing the node's registration with the ROS graph.
• Implementing the ROS 2 Lifecycle Node state machine for managed nodes, enabling controlled transitions between states like Unconfigured, Inactive, and Active.
• Properly releasing resources (e.g., subscriptions, publishers, services) on shutdown to prevent memory leaks.

The RCL implements the publish-subscribe communication model. It provides objects and methods to:

• Create a Publisher for a specific topic and message type.
• Publish messages asynchronously to the topic.
• Create a Subscription to a topic, registering a user-defined callback function.
• Manage Quality of Service (QoS) policies (e.g., reliability, durability, deadline) for the communication channel.
• Handle the serialization and deserialization of ROS messages to/from the underlying DDS wire format.

The RCL abstracts synchronous and asynchronous request-reply patterns:

• Services: Provides Service Server and Service Client objects for synchronous, blocking request-response interactions.
• Actions: Implements the more complex Action Server and Action Client interfaces for long-running, cancellable tasks. This includes managing goal handling, periodic feedback publication, and final result delivery, all built atop the publish-subscribe model.

The RCL enables nodes to interact with a dynamic configuration system:

• Declare parameters with names, types, and optional default values.
• Get and set parameter values at runtime, either locally or on a remote node.
• Register callbacks for parameter events to dynamically reconfigure node behavior when a parameter changes.
• Describe parameter constraints (e.g., ranges) for external tools.

The RCL provides the mechanisms for scheduling and executing node logic:

• Timers: Create periodic callbacks with a specified rate (e.g., 10 Hz control loops).
• Executors: The ROS 2 Executor is the processing engine that spins the node, managing the execution of subscriptions, services, timers, and action servers. The RCL API allows configuration of single-threaded or multi-threaded executors to control concurrency and callback scheduling.

The RCL standardizes node output for debugging and system monitoring:

• Provides a hierarchical logging API with severity levels (DEBUG, INFO, WARN, ERROR, FATAL).
• Log messages are routed through the /rosout topic for centralized collection.
• Supports console output with configurable formatting and filtering.
• Enables integration with system-level diagnostic tools.

A ROS 2 Node is the fundamental executable process created using an RCL. Each node performs a specific computation (e.g., sensor driver, planner, controller) and participates in the ROS graph.

• An RCL provides the API to create, configure, and spin a node.
• A single process can contain multiple nodes for logical organization.
• Nodes are the primary entities that publish/subscribe to topics, call services, and execute actions.

Data Distribution Service (DDS) is the underlying middleware standard that provides the actual network transport for ROS 2. The RCL acts as an abstraction layer between the user's node code and the specific DDS implementation (e.g., Cyclone DDS, Fast DDS).

• The RCL translates high-level ROS API calls (like publish()) into DDS-specific operations.
• This abstraction allows ROS 2 to be vendor-neutral; the same RCL code can work with different DDS vendors by switching a runtime configuration.

Quality of Service (QoS) policies are configurable behaviors for communication reliability, durability, and timeliness. The RCL exposes these policies through its API, allowing developers to tune communication for their system's needs.

• Key Policies: Reliability (RELIABLE vs BEST_EFFORT), Durability (TRANSIENT_LOCAL), Deadline, and Lifespan.
• Example: A sensor node might use BEST_EFFORT for high-frequency lidar data, while a command node uses RELIABLE for critical motion instructions.
• QoS must be compatible between publishers and subscribers for a connection to be established.

The ROS 2 Executor is the processing engine that manages how a node's callbacks (for subscriptions, timers, services) are executed. The RCL provides the API to create and spin an executor.

• SingleThreadedExecutor: Processes all callbacks sequentially in one thread.
• MultiThreadedExecutor: Uses a thread pool to process callbacks concurrently.
• Custom Executors: Can be built for specialized scheduling needs (e.g., real-time priorities).
• The executor's spin() function is the core event loop that keeps the node alive and responsive.

An RCL is implemented for each supported programming language, providing a native-feeling API while adhering to a common core specification (rcl).

• rclcpp (C++): The primary RCL for performance-critical systems. Uses object-oriented patterns (Node classes, smart pointers).
• rclpy (Python): Used for rapid prototyping, scripting, and high-level coordination. Leverages Python's dynamic typing.
• rcljava, rcljs: Enable ROS 2 development in Java and JavaScript/TypeScript environments.
• All implementations ensure semantic parity for core concepts like nodes, topics, and QoS.

rcl is the common C-language library upon which all language-specific RCLs (like rclcpp and rclpy) are built. It provides the foundational, non-idiomatic API that handles the core lifecycle and communication logic.

• Purpose: Ensures consistent behavior across all language bindings and isolates complex DDS interactions.
• Architecture: Language-specific RCLs wrap rcl functions to provide a more convenient, idiomatic API (e.g., classes in C++, dynamic types in Python).
• This layered design promotes stability; the core rcl logic is written once and thoroughly tested.