DOCSEARCHbyAlgolia
Submit Docs

rclpy Documentation

repository·rolling·Indexed 19 days ago

https://github.com/ros2/rclpy

The ROS 2 Client Library for Python, providing interfaces to build ROS 2 nodes and communicate via topics, services, and actions. It includes modules for publishing and subscribing (including experimental async versions), service clients and servers, and action clients and servers. The library manages callback execution through Executors and Callback Groups to control concurrency and thread safety.

Tokens
4.4K
Snippets
14
Records
27
Agent score
62%

What's inside rclpy

  2. How executors and callback groups control callback execution

    rolling

    In rclpy, the execution of callbacks (such as timer callbacks, subscription callbacks, or service callbacks) is managed by two primary components:

    1. Executors: These are responsible for the actual execution of the callbacks. To implement custom execution logic, you should extend the rclpy.executors.Executor class.
    2. Callback Groups: These are used to define and enforce concurrency rules for callbacks. They determine whether callbacks can run in parallel or must be executed sequentially. To define custom concurrency behavior, you should extend the rclpy.callback_groups.CallbackGroup class.

    Together, executors pick up tasks and callback groups dictate how those tasks interact with each other regarding thread safety and concurrency.

  3. Use callback groups to enforce concurrency rules

    rolling
    Callback groups allow you to group related callbacks and specify how they should be handled by an executor. This is essential for controlling whether multiple callbacks can run at the same time (concurrency) or if they must wait for one another (sequentially). You can define custom groups by extending rclpy.callback_groups.CallbackGroup.

  4. Use rclpy Service Clients

    rolling

    In rclpy, a Service Client is used to request a service from a Service Server. You can use the standard synchronous/asynchronous client or the experimental async client.

    • Standard Client: Found in rclpy.client. Use this for typical service request/response patterns.
    • Experimental Async Client: Found in rclpy.experimental.async_client. Use this for specialized asynchronous workflows requiring the experimental API.

  5. Use rclpy Service Servers

    rolling

    In rclpy, a Service Server is used to provide a service implementation that responds to incoming requests. You can use the standard service or the experimental async service.

    • Standard Service: Found in rclpy.service. Use this for standard service provider implementations.
    • Experimental Async Service: Found in rclpy.experimental.async_service. Use this for specialized asynchronous service provider implementations.

  6. Build RCLPy documentation locally

    rolling

    You can build the rclpy documentation locally using Sphinx. This requires an existing ROS 2 installation and specific Python Sphinx dependencies.

    1. Install Dependencies

    Install the required Sphinx extensions via apt:

    sudo apt install \
  python3-sphinx \
  python3-sphinx-autodoc-typehints \
  python3-sphinx-rtd-theme

    2. Build the Workspace

    Source your ROS 2 installation and build the rclpy package using colcon:

    # Source ROS 2 (example for rolling)
. /opt/ros/rolling/setup.bash

# Create workspace and clone source
mkdir -p rclpy_ws/src
cd rclpy_ws/src
git clone https://github.com/ros2/rclpy.git
cd ..

# Build the package
colcon build --symlink-install

    3. Generate HTML Documentation

    Source the newly built workspace and use make within the documentation directory:

    source install/setup.bash
cd src/rclpy/rclpy/docs
make html

  8. Create a service client using Node.create_client

    rolling

    In rclpy, you should not instantiate Client or BaseClient directly. Instead, use the create_client method provided by a Node or AsyncNode instance. This ensures the client is correctly managed within the node's lifecycle and context.

    Example usage pattern:

    # Assuming 'node' is an instance of rclpy.node.Node
client = node.create_client(MySrvType, 'service_name')

  9. Use asynchronous subscription with rclpy.experimental.async_subscription

    rolling
    For advanced subscription patterns, use the rclpy.experimental.async_subscription module. This experimental feature allows for asynchronous handling of incoming messages, which can be useful for integrating with async/await patterns in Python.

  10. Subscribe to topics using rclpy.subscription

    rolling
    Use the rclpy.subscription module to create subscriptions that receive messages from ROS 2 topics. This module provides the standard mechanism for registering callback functions that are triggered whenever a new message arrives on the subscribed topic.

  11. Use asynchronous publishing with rclpy.experimental.async_publisher

    rolling
    For use cases requiring non-blocking or asynchronous message publishing, use the rclpy.experimental.async_publisher module. This is an experimental feature designed to handle publishing operations without blocking the execution flow of the node.