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_test::ros1::*; // Provides std_msgs::String
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() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Relay messages over a native ROS 2 Kilted-or-newer connection using rmw_zenoh.
    #[cfg(feature = "hiroz")]
    {
        use roslibrust::hiroz::Builder;
        let ctx = roslibrust::hiroz::context::ZContextBuilder::default()
            .with_domain_id(0)
            .with_connect_endpoints(["tcp/127.0.0.1:7447"])
            .build()?;
        let ros = roslibrust::hiroz::ZenohClient::new(&ctx, "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(
        roslibrust::zenoh::open(roslibrust::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_hiroz as hiroz;
pub use roslibrust_codegen as codegen;

Modules§

dynamic: Runtime metadata and type-erased values for generated ROS messages.
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§

DynamicField: One named field in a dynamically represented ROS message.
DynamicMessage: A schema-validated, canonical representation of a runtime-selected ROS message.
GlobalTopicName: A unified representation for the names of topics, services, and actions.
MessageDescriptor: Metadata and conversion operations for one generated ROS message type.
MessageRegistry: An immutable registry generated alongside a set of ROS message types.
ServiceDescriptor: Metadata and request/response codecs for one generated ROS service type.
ServiceInfo: Information about a service currently visible in the ROS graph.
ServiceRegistry: An immutable registry generated alongside a set of ROS service types.
ShapeShifter: A generic message type used by some implementations to provide a generic subscriber / publisher without serialization
TopicInfo: Information about a topic currently visible in the ROS graph.

Enums§

DynamicMessageError: A failure while looking up or converting a runtime-selected ROS message.
DynamicValue: An unvalidated, format-neutral representation of a possible ROS message value.
Error: The central error type used throughout roslibrust.

Traits§

DynamicPublish: A publisher for messages whose concrete Rust type was selected at runtime.
DynamicService: A reusable client for a service whose concrete Rust type was selected at runtime.
DynamicServiceProvider: Describes a backend that can call services using runtime-selected service types.
DynamicSubscribe: A subscriber for messages whose concrete Rust type was selected at runtime.
DynamicTopicProvider: Describes a backend that can advertise and subscribe using runtime-selected message types.
DynamicValueIndex: An index that can access a member of a DynamicValue.
GraphProvider: Describes the ability to inspect the visible ROS graph.
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.
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

Functions§

normalize_ros_type_name: Normalize common ROS message and service type spellings to package/Type.

Type Aliases§

DynamicMessageResult: Result type for runtime message lookup and conversion.
Result: Generic result type used throughout roslibrust.
ServiceError: The error type used by ServiceFn