Crate roslibrust 

RosLibRust

Documentation about the crate is on docs.rs, extended guides can be found on roslibrust.github.io

An async rust library for interfacing with ROS1 and ROS2, built on Tokio.

• One Trait Based API - Write your behavior once and use it with any backend! Select the backend you want to use at compile time.
• Pure Rust - No ROS1 or ROS2 dependencies or installation required! Compile time message generation from .msg/.srv files.

This allows writing generic behaviors like:

use roslibrust::{TopicProvider, Publish, Subscribe};

async fn relay<T: TopicProvider>(ros: T) -> roslibrust::Result<()> {
    let mut subscriber = ros.subscribe::<std_msgs::String>("/in").await?;
    let mut publisher = ros.advertise::<std_msgs::String>("/out").await?;
    while let Ok(msg) = subscriber.next().await {
        println!("Got message: {}", msg.data);
        publisher.publish(&msg).await?;
    }
    Ok(())
}

#[tokio::main]
async fn main() -> roslibrust::Result<()> {
    // Experimental support in roslibrust_ros2, not yet released on crates.io
    // Relay messages over a native ROS2 connection using Zenoh
    // #[cfg(feature = "ros2")]
    // {
    // let ros = roslibrust::ros2::NodeHandle::new("http://localhost:11311", "relay").await?;
    // relay(ros).await?;
    // }

    // Relay messages over a native ROS1 connection via TCPROS
    #[cfg(feature = "ros1")]
    {
    let ros = roslibrust::ros1::NodeHandle::new("http://localhost:11311", "relay").await?;
    relay(ros).await?;
    }

    // Relay messages over a zenoh connection compatible with zenoh-ros1-plugin / zenoh-ros1-bridge
    #[cfg(feature = "zenoh")]
    {
    let ros = roslibrust::zenoh::ZenohClient::new(zenoh::open(zenoh::Config::default()).await.unwrap());
    relay(ros).await?;
    }

    // Relay messages over a rosbridge_server connection with either ROS1 or ROS2!
    #[cfg(feature = "rosbridge")]
    {
    let ros = roslibrust::rosbridge::ClientHandle::new("ws://localhost:9090").await?;
    relay(ros).await?;
    }

    // Relay messages over a mock ROS connection for testing
    #[cfg(feature = "mock")]
    {
    let ros = roslibrust::mock::MockRos::new();
    relay(ros).await?;
    }

    Ok(())
}

All of this is backed by common traits for ROS messages, topics, and services. roslibrust_codegen provides generation of Rust types from both ROS1 and ROS2 .msg/.srv files and roslibrust_codegen_macro provides a convenient macro for generating these types:

// Will generate types from all packages in ROS_PACKAGE_PATH, AMENT_PREFIX_PATH, and COLCON_PREFIX_PATH
roslibrust_codegen_macro::generate_ros_types_with_env!();

If you want to see what the generated code looks like checkout our generated messages in our test crate. While the macro is useful for getting started, we recommend using roslibrust_codegen with a build.rs as shown in example_package. This allows cargo to know when message files are edited and automatically re-generate the code.

Getting Started / Examples

• Checkout the Quick Getting Started Guide for a brief guide on how to get started with RosLibRust.
• Checkout the Extended Getting Started Guide for a more in depth guide on how to get started with RosLibRust.
• Examples can be found in examples.

Contributing

Contribution through reporting of issues encountered and implementation in PRs is welcome! Before landing a large PR with lots of code implemented, please open an issue if there isn’t a relevant one already available and chat with a maintainer to make sure the design fits well with all supported platforms and any in-progress implementation efforts.

We uphold the rust lang Code of Conduct.

Minimum Supported Rust Version / MSRV

MSRV is currently 1.90.

Re-exports

pub use roslibrust_ros1 as ros1;

pub use roslibrust_rosbridge as rosbridge;

pub use roslibrust_zenoh as zenoh;

pub use roslibrust_mock as mock;

pub use roslibrust_codegen as codegen;

Modules

md5sum

Contains functions for calculating md5sums of message definitions.

topic_name

Contains the validation logic for topic, service, and action names.

traits

Contains the generic traits represent a pubsub system and service system. These traits will be implemented for specific backends to provides access to “ROS Like” functionality.

Macros

find_and_generate_ros_messages

Deprecated alias for [generate_ros_types_with_env].

find_and_generate_ros_messages_without_ros_package_path

Deprecated alias for [generate_ros_types].

generate_ros_types

Generates struct definitions and trait impls for ROS types found in the paths provided to the macro, skipping ROS environment discovery.

generate_ros_types_with_env

Generates struct definitions and trait impls for ROS types found in the paths provided to the macro plus ROS1 paths from ROS_PACKAGE_PATH and ROS2 packages found through ament resource indexes in AMENT_PREFIX_PATH and COLCON_PREFIX_PATH.

Structs

GlobalTopicName

A unified representation for the names of topics, services, and actions.

ShapeShifter

A generic message type used by some implementations to provide a generic subscriber / publisher without serialization

Enums

Error

The central error type used throughout roslibrust.

Traits

Publish

Indicates that something is a publisher and has our expected publish Implementors of this trait are expected to auto-cleanup the publisher when dropped

Ros

Represents all “standard” ROS functionality generically supported by roslibrust

RosMessageType

Fundamental traits for message types this crate works with This trait will be satisfied for any types generated with this crate’s message_gen functionality

RosServiceType

Represents a ROS service type definition corresponding to a .srv file.

Service

Defines what it means to be something that is callable as a service

ServiceFn

This trait describes a function which can validly act as a ROS service server with roslibrust. We’re really just using this as a trait alias as the full definition is overly verbose and trait aliases are unstable.

ServiceProvider

This trait is analogous to TopicProvider, but instead provides the capability to create service servers and service clients

Subscribe

Represents that an object can act as a subscriber. Types returned by calling TopicProvider::subscribe, implement this trait. Types implementing this trait are expected to auto-cleanup the subscriber when dropped, and de-register themselves with ROS as needed.

ToGlobalTopicName

This trait represents types that can be converted into a GlobalTopicName

TopicProvider

This trait generically describes the capability of something to act as an async interface to a set of topics

Type Aliases

Result

Generic result type used throughout roslibrust.

ServiceError

The error type used by ServiceFn