DOCSEARCHbyAlgolia
Submit Docs

rosbridge_suite

repository·ros2·Indexed 22 days ago

https://github.com/robotwebtools/rosbridge_suite

A JSON-based bridge between ROS and external clients using the rosbridge v2 protocol. It enables communication over WebSockets and TCP, allowing non-ROS clients to interact with ROS topics, services, and parameters. The suite includes rosbridge_library for core API processing, rosbridge_server for WebSocket implementation, and rosapi for retrieving ROS meta-information and managing the ROS Parameter Server.

Tokens
8.3K
Snippets
6
Records
54
Agent score
79%

What's inside rosbridge_suite

  1. Overview of rosbridge_suite and the rosbridge v2 Protocol

    ros2

    rosbridge_suite provides a JSON interface to ROS, enabling clients to interact with ROS topics (publish/subscribe), call services, and more using JSON-formatted messages.

    Key features:

    • Protocol: Uses the rosbridge v2 protocol.
    • Transport Layers: Supports various transport layers, including WebSockets and TCP.
    • Functionality: Allows non-ROS clients to communicate with a ROS system via a JSON API.

  2. Overview of the rosapi node

    ros2
    The rosapi node (executable: rosapi_node) provides a suite of ROS services designed to retrieve ROS meta-information. It allows clients to inspect the ROS system, including topics, services, interfaces, action servers, and node details, as well as manage ROS parameters.

  3. Handle byte arrays using Base64 encoding

    ros2

    By default, rosbridge encodes uint8[] or char[] fields as base64 strings instead of JSON lists of numbers. This reduces message size by up to 60%.

    When receiving messages, byte arrays will arrive as base64 strings. When sending byte arrays to the server, you can use either a base64 string or a list of numbers; however, the server will re-encode them as base64 strings before broadcasting them to other clients.

    {
  "data1": "AAAAAA==",
  "data2": "/////w=="
}

  4. Use CBOR encoding for high-performance data transfer

    ros2
    CBOR encoding is the fastest compression method for messages containing large blobs, such as byte arrays and numeric typed arrays. When a subscriber requests CBOR, the server produces a binary message instead of a JSON string. Once decoded, the message follows the standard protocol format. The implementation uses draft typed array tags for efficient packing of homogeneous arrays (little-endian only).

  5. Use CBOR-RAW encoding to receive raw ROS 2 serialized messages

    ros2

    CBOR-RAW encoding allows clients to receive the raw binary message in the ROS 2 serialized format. This is useful for high-performance applications that want to parse messages in WebWorkers, use existing ROS 2 bag parsing logic, or avoid the overhead of converting between ROS 2 binary and CBOR.

    In this mode, the msg field contains an object with a bytes field (the raw serialized ROS 2 message) and secs/nsecs fields representing the ROS time of receipt.

    To parse these raw messages, you can use the /rosapi/get_topics_and_raw_types service to obtain topic names and their raw message definitions.

  6. Specify ROS interface types in operations

    ros2

    When an operation requires a type field, use the full notation: package_name/category/TypeName. The category must be one of msg, srv, or action.

    Examples:

    • Message: std_msgs/msg/String
    • Service: std_srvs/srv/SetBool
    • Action: nav2_msgs/action/NavigateToPose

    You may omit the category (e.g., std_msgs/String), and rosbridge will infer it from context.

  7. Understand the rosbridge_suite package structure

    ros2

    The rosbridge_suite is a meta-package that includes several specialized packages:

    • rosbridge_suite: The ROS meta-package containing all related packages.
    • rosbridge_library: The core Python API that processes JSON strings to control ROS publishers, subscribers, and service calls.
    • rosbridge_server: A WebSocket server implementation that exposes the rosbridge_library functionality.
    • rosapi: Provides ROS meta-information services, such as retrieving topic lists and interacting with the ROS Parameter Server.

  8. Understand the rosbridge message envelope

    ros2

    All rosbridge protocol messages must be structured objects (e.g., JSON or CBOR) containing a mandatory string field named op. This field identifies the specific operation being performed.

    To correlate requests and responses, you can optionally include an id field. The id identifies an entire interaction (which may involve multiple messages) rather than a single message. When a client sends a message with an id, the server will typically include that same id in its response messages.

    {
  "op": "Example",
  "id": "fred"
}

  9. Default QoS settings for rosbridge

    ros2

    If you omit the qos field, rosbridge applies these defaults:

    Publishers

    • Reliability: reliable
    • Durability: transient_local
    • History: keep_last
    • Depth: 100

    Subscribers

    Subscribers attempt to match the QoS of existing publishers. If no publishers exist, they default to:

    • Reliability: best_effort
    • Durability: volatile
    • History: keep_last
    • Depth: 10

    If all existing publishers use transient_local durability, the subscriber switches to transient_local and reliable. If any publisher uses best_effort reliability, the subscriber uses best_effort.

  11. Use PNG compression for large images and maps

    ros2

    The png operation (experimental) allows the server to send large messages (like images or maps) as PNG-encoded bytes. The server takes the serialized payload, interprets it as an RGB image, saves it as a PNG, and then base64-encodes that PNG.

    Note: Currently, only Server-to-Client png messages are supported. The server does not support receiving PNG-compressed messages from clients.