Crate roslibrust

Expand description

§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<()> {
    // 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 
roslibrust_codegen_macro::find_and_generate_ros_messages!();

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.85 to support edition 2024.

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 These functions are needed both in roslibrust_ros1 and roslibrust_codegen so they’re in this crate
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: Given a list of paths, generates struct definitions and trait impls for any ros messages found within those paths. Paths are relative to where rustc is being invoked from your mileage may vary.
find_and_generate_ros_messages_without_ros_package_path: Similar to find_and_generate_ros_messages, but does not search the ROS_PACKAGE_PATH environment variable paths (useful in some situations).

Structs§

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.
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