Skip to content

Commit a67de85

Browse files
christophfroehlichmergify[bot]
christophfroehlich
authored and
mergify[bot]
committed
Add docs for control.ros.org (#346)
(cherry picked from commit eb75804) # Conflicts: # doc/index.rst # doc/realtime_publisher.rst
1 parent 90c9e7a commit a67de85

File tree

5 files changed

+68
-39
lines changed

5 files changed

+68
-39
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@ realtime_tools
55

66
Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
77

8-
Some documentation can be found at [docs.ros.org](http://docs.ros.org/en/rolling/p/realtime_tools/doc/index.html).
8+
Further documentation can be found at [docs.ros.org](https://control.ros.org/rolling/doc/realtime_tools/doc/index.html).
99

1010
## Contributing
1111
As an open-source project, we welcome each contributor, regardless of their background and experience. Pick a [PR](https://github.com/ros-controls/realtime_tools/pulls) and review it, or [create your own](https://github.com/ros-controls/realtime_tools/contribute)!
1212
If you are new to the project, please read the [contributing guide](https://control.ros.org/rolling/doc/contributing/contributing.html) for more information on how to get started. We are happy to help you with your first contribution.
1313

1414
## Build status
15-
ROS2 Distro | Branch | Build status | Documentation | Package Build
15+
ROS2 Distro | Branch | Build status | API Documentation | Package Build
1616
:---------: | :----: | :----------: | :-----------: | :---------------:
1717
**Rolling** | [`master`](https://github.com/ros-controls/realtime_tools/tree/master) | [![Binary Build](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-binary-build.yml/badge.svg?branch=master)](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-binary-build.yml?branch=master) <br> [![Source Build](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-source-build.yml/badge.svg?branch=master)](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-source-build.yml?branch=master) <br> [![build.ros2.org](https://build.ros2.org/buildStatus/icon?job=Rdev__realtime_tools__ubuntu_noble_amd64&subject=build.ros2.org)](https://build.ros2.org/job/Rdev__realtime_tools__ubuntu_noble_amd64/) | [API](http://docs.ros.org/en/rolling/p/realtime_tools/) | [![Build Status](https://build.ros2.org/buildStatus/icon?job=Rbin_uN64__realtime_tools__ubuntu_noble_amd64__binary)](https://build.ros2.org/job/Rbin_uN64__realtime_tools__ubuntu_noble_amd64__binary/)
1818
**Kilted** | [`master`](https://github.com/ros-controls/realtime_tools/tree/master) | see above <br> [![build.ros2.org](https://build.ros2.org/buildStatus/icon?job=Kdev__realtime_tools__ubuntu_noble_amd64&subject=build.ros2.org)](https://build.ros2.org/job/Kdev__realtime_tools__ubuntu_noble_amd64/) | [API](http://docs.ros.org/en/rolling/p/realtime_tools/) | [![Build Status](https://build.ros2.org/buildStatus/icon?job=Kbin_uN64__realtime_tools__ubuntu_noble_amd64__binary)](https://build.ros2.org/job/Kbin_uN64__realtime_tools__ubuntu_noble_amd64__binary/)

‎doc/index.rst‎

Lines changed: 12 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,12 @@
1+
<<<<<<< HEAD
12
Welcome to the documentation for realtime_tools
23
===============================================
34

45
Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
56

67
For more information of the ros2_control framework see `control.ros.org <https://control.ros.org/>`__.
78

8-
Realtime Publisher
9-
------------------
10-
The ``realtime_tools::RealtimePublisher`` allows users that write C++ ros2_controllers to publish messages on a ROS topic from a hard realtime loop. The normal ROS publisher is not realtime safe, and should not be used from within the update loop of a realtime controller. The realtime publisher is a wrapper around the ROS publisher; the wrapper creates an extra non-realtime thread that publishes messages on a ROS topic. The example below shows a typical usage of the realtime publisher in the ``on_configure()`` (non-realtime method) and ``update()`` (realtime method) methods of a realtime controller:
11-
12-
.. code-block:: cpp
13-
14-
#include <realtime_tools/realtime_publisher.h>
15-
16-
class MyController : public controller_interface::ControllerInterface
17-
{
18-
...
19-
private:
20-
std::shared_ptr<realtime_tools::RealtimePublisher<my_msgs::msg::MyMsg>> state_publisher_;
21-
std::shared_ptr<rclcpp::Publisher<my_msgs::msg::MyMsg>> s_publisher_;
22-
}
23-
24-
controller_interface::CallbackReturn MyController::on_configure(
25-
const rclcpp_lifecycle::State & /*previous_state*/)
26-
{
27-
...
28-
s_publisher_ = get_node()->create_publisher<my_msgs::msg::MyMsg>(
29-
"~/status", rclcpp::SystemDefaultsQoS());
30-
state_publisher_ =
31-
std::make_unique<realtime_tools::RealtimePublisher<ControllerStateMsg>>(s_publisher_);
32-
...
33-
}
34-
35-
controller_interface::return_type MyController::update(
36-
const rclcpp::Time & /*time*/, const rclcpp::Duration & /*period*/)
37-
{
38-
...
39-
// Publish controller state
40-
state_publisher_->lock();
41-
state_publisher_->msg_ = some_msg;
42-
state_publisher_->unlockAndPublish();
43-
}
44-
9+
.. include:: realtime_publisher.rst
4510

4611
API documentation
4712
------------------
@@ -57,3 +22,13 @@ Indices and Search
5722

5823
* :ref:`genindex`
5924
* :ref:`search`
25+
=======
26+
:github_url: https://github.com/ros-controls/realtime_tools/blob/{REPOS_FILE_BRANCH}/doc/index.rst
27+
28+
realtime_tools
29+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30+
31+
Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
32+
33+
.. include:: ../realtime_tools/doc/realtime_publisher.rst
34+
>>>>>>> eb75804 (Add docs for control.ros.org (#346))

‎doc/migration.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
:github_url: https://github.com/ros-controls/realtime_tools/blob/{REPOS_FILE_BRANCH}/doc/migration.rst
2+
3+
Migration Guides: Jazzy to Kilted
4+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5+
This list summarizes important changes between Jazzy (previous) and Kilted (current) releases, where changes to user code might be necessary.
6+
7+
RealtimeBox
8+
*******************************
9+
* ``RealtimeBox`` is deprecated. Update your code to use ``realtime_thread_safe_box.hpp`` header, and class name ``RealtimeThreadSafeBox`` instead. (`#318 <https://github.com/ros-controls/realtime_tools/pull/318>`__, `#342 <https://github.com/ros-controls/realtime_tools/pull/342>`__).

‎doc/realtime_publisher.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Realtime Publisher
2+
------------------
3+
The ``realtime_tools::RealtimePublisher`` allows users that write C++ ros2_controllers to publish messages on a ROS topic from a hard realtime loop. The normal ROS publisher is not realtime safe, and should not be used from within the update loop of a realtime controller. The realtime publisher is a wrapper around the ROS publisher; the wrapper creates an extra non-realtime thread that publishes messages on a ROS topic. The example below shows a typical usage of the realtime publisher in the ``on_configure()`` (non-realtime method) and ``update()`` (realtime method) methods of a realtime controller:
4+
5+
.. code-block:: cpp
6+
7+
#include <realtime_tools/realtime_publisher.hpp>
8+
9+
class MyController : public controller_interface::ControllerInterface
10+
{
11+
...
12+
private:
13+
std::shared_ptr<realtime_tools::RealtimePublisher<my_msgs::msg::MyMsg>> state_publisher_;
14+
std::shared_ptr<rclcpp::Publisher<my_msgs::msg::MyMsg>> s_publisher_;
15+
}
16+
17+
controller_interface::CallbackReturn MyController::on_configure(
18+
const rclcpp_lifecycle::State & /*previous_state*/)
19+
{
20+
...
21+
s_publisher_ = get_node()->create_publisher<my_msgs::msg::MyMsg>(
22+
"~/status", rclcpp::SystemDefaultsQoS());
23+
state_publisher_ =
24+
std::make_unique<realtime_tools::RealtimePublisher<ControllerStateMsg>>(s_publisher_);
25+
...
26+
}
27+
28+
controller_interface::return_type MyController::update(
29+
const rclcpp::Time & /*time*/, const rclcpp::Duration & /*period*/)
30+
{
31+
...
32+
// Publish controller state
33+
state_publisher_->lock();
34+
state_publisher_->msg_ = some_msg;
35+
state_publisher_->unlockAndPublish();
36+
}

‎doc/release_notes.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
:github_url: https://github.com/ros-controls/realtime_tools/blob/{REPOS_FILE_BRANCH}/doc/release_notes.rst
2+
3+
Release Notes: Jazzy to Kilted
4+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5+
This list summarizes the changes between Jazzy (previous) and Kilted (current) releases.
6+
7+
RealtimeBox
8+
*******************************
9+
* ``RealtimeBox`` got renamed to ``RealtimeThreadSafeBox`` and uses real-time mutexes now (`#318 <https://github.com/ros-controls/realtime_tools/pull/318>`__, `#342 <https://github.com/ros-controls/realtime_tools/pull/342>`__).

0 commit comments

Comments
 (0)