mirror
/
r2r
mirror of https://github.com/sequenceplanner/r2r.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Minimal ROS 2 Rust bindings
298 Commits 1 Branch 21 Tags 4.1 MiB
Rust 98.1%
C 1.6%
CMake 0.2%
Shell 0.1%
Go to file
Martin Škoudlil db7aa0b6fd Pin timer_handle to avoid SIGSEGV in _rcl_timer_time_jump() callback 
This commit is preparation for next commit with timer using RosTime clock.

In the previous implementation the function rcl_timer_init is called
with zero initialized timer handle being stored on stack and after
initialization with rcl_timer_init the timer handle is moved by rust
inside Timer_ struct.

The problem occurs if the type of clock being passed to rcl_timer_init()
is RosTime because the function also registers callbacks in the clock
that would notify the timer about sudden time change (jump callback).
In RCL the jump callback is registered with rcl_clock_add_jump_callback()
and the argument callback.user_data is pointer to timer handle that in
our case references timer stored om stack. When returning from function
create_wall_timer() the pointer becomes dangling and therefore when the
callback is actually called (by function _rcl_timer_time_jump) it could
result in SIGSEGV or could access some variable that happens to be in
the same place as the timer_handle was on stack.

This is fixed by storing timer_handle inside pinned box to prevent
moving the handle.
 		2024-03-20 13:27:09 +01:00
.github/workflows Add ros2 iron 2024-02-09 14:53:18 +01:00
r2r Pin timer_handle to avoid SIGSEGV in _rcl_timer_time_jump() callback 2024-03-20 13:27:09 +01:00
r2r_actions Release 0.8.4 2024-03-19 13:30:06 +01:00
r2r_common Release 0.8.4 2024-03-19 13:30:06 +01:00
r2r_macros Release 0.8.4 2024-03-19 13:30:06 +01:00
r2r_msg_gen Release 0.8.4 2024-03-19 13:30:06 +01:00
r2r_rcl Release 0.8.4 2024-03-19 13:30:06 +01:00
tests Add ros2 iron 2024-02-09 14:53:18 +01:00
tools Refresh bindings bash script 2023-06-26 12:03:58 +02:00
.dockerignore add get_publishers_info_by_topic (#80) 2024-01-11 20:55:33 +01:00
.gitignore Ignore editor temp files 2022-11-25 00:14:47 +08:00
Cargo.toml Release 0.8.0 2023-10-05 11:44:22 +02:00
LICENSE Bump version numbers, update readme and licenses. 2022-01-13 11:53:30 +01:00
README.md Release 0.8.4 2024-03-19 13:30:06 +01:00
r2r_cargo.cmake Release 0.8.4 2024-03-19 13:30:06 +01:00
rustfmt.toml rustfmt 2023-06-26 13:33:41 +02:00

README.md

R2R - Easy to use, runtime-agnostic, async rust bindings for ROS2.

Easy to use bindings for ROS2 that do not require hooking in to the ROS2 build infrastructure -- cargo build is all you need. Convenience Rust types are created by calling into the c introspection libraries. This circumvents the ROS2 .msg/.idl pipeline by relying on already generated C code. By default, the behavior is to build bindings to the RCL and all message types that can be found in the currently sourced ros environment, but it is possible to be more specific to save on build time (see note below).

When integration with the colcon build system is desired, a CMakeLists.txt file can be used to limit the generation of bindings to only include specific (idl) dependencies. This is done through additional environment variables. A minimal example of the colcon integration is available here: https://github.com/m-dahl/r2r_minimal_node.

This library differ a bit in style from rclpy and rclcpp as it eliminates all synchronous callbacks in favor of rust futures and streams. Coupled with the rust await syntax, this makes it very pleasant to work with ROS services and actions, even in a single threaded setup (see service.rs example). The library purposefully does not chose an async runtime -- this means that the user needs to take care of any task spawning. This also limits the API to what futures-rs provides.

Documentation can be found on docs.rs: https://docs.rs/r2r/latest/r2r.

These bindings are being written organically when things are needed by me and others so please be aware that the API will change. As of now I have no intention of wrapping all of the RCL just for the sake of completeness. However, if you need some specific functionality, feel free to open an issue or a PR!

How to use

  1. Make sure you have libclang installed. (e.g. libclang-dev on ubuntu)
  2. Depend on this package in Cargo.toml: r2r = "0.8.4"
  3. You need to source your ROS2 installation before building/running.
  4. The bindings will rebuild automatically if/when you source your workspace(s).
  5. If you make changes to existing message types, run cargo clean -p r2r_msg_gen to force recompilation of the rust message types on the next build.

Examples of how to use the crate are included in examples/

. /opt/ros/humble/setup.sh
cargo build
cargo run --example subscriber
# In other shell
ros2 topic pub /topic std_msgs/msg/String "data: 'Hello, world'"

A note on build times

Since the default behavior is to build all sourced message types, build time can quickly become a problem for larger workspaces. To avoid building everything, it is possible to declare only the message packages needed using the environment variable IDL_PACKAGE_FILTER. Setting this can be done in .cargo/config.toml for convenience, e.g. https://github.com/m-dahl/r2r_minimal_node/blob/master/r2r_minimal_node/.cargo/config.toml. Note there is no automatic dependency resolution done for nested message types, so all used message packages need to be explicitly included.

What works?

  • Up to date with ROS2 ~Dashing~ ~Eloquent~ Foxy Galactic Humble Iron
  • Building Rust types
  • Publish/subscribe
  • Services
  • Actions
  • Parameter handling
  • Runs on Linux, OSX, and Windows.

Changelog

[Unreleased]

[0.8.4] - 2024-03-19

[0.8.3] - 2024-01-14

[0.8.2] - 2023-12-11

[0.8.1] - 2023-11-30

[0.8.0] - 2023-10-05

[0.7.5] - 2023-06-27

[0.7.4] - 2023-06-26

[0.7.3] - 2023-06-20

  • Fix mistake in docs generation.

[0.7.2] - 2023-06-20

[0.7.1] - 2023-05-21

[0.7.0] - 2023-03-21

[0.6.7] - 2023-02-20

TODO

  • Documentation is lacking. (For now, look at the examples.)

LICENSING

All code is under the MIT licence unless another license is specified in the source files. Some parts from the rclrust (https://github.com/rclrust/rclrust) package are included in this repo and these are licensed under Apache 2.0.

rosin_logo

Supported by ROSIN - ROS-Industrial Quality-Assured Robot Software Components. More information: rosin-project.eu

eu_flag

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement no. 732287.