Consolidate documentation

[carlossvg]

ros-realtime.github.io should be the only documentation website for the RTWG docs. Currently, there are different documents in separated github pages. We should consolidate all the documents in a single place so it's easier to find them.

• Migrate ros-realtime.github.io to mkdocs => @LanderU
• Migrate ros2_realtime_benchmarks reports to markdown format => @carlossvg
• Migrate to mkdocs https://github.com/ros-realtime/ros2_realtime_benchmarks reports => @LanderU
• Migrate https://ros-realtime.github.io/ros2-realtime-examples/ to ros-realtime.github.io => @carlossvg

[JanStaschulat]

Documentation at docs.ros.org

Ressource	What-to-do?	Assignee	status
Tutorial/Building-Realtime-rt_preempt-kernel-for-ROS-2.html	outdated link - same as below
Tutorials/Miscellaneous/Building-Realtime-rt_preempt-kernel-for-ROS-2.html
Tutorials/Demos/Real-Time-Programming.html
How-To-Guides/Building-ROS-2-with-Tracing-Instrumentation.html
How-To-Guides/Installing-on-Raspberry-Pi.html
How-To-Guides/Using-callback-groups.html
Concepts/About-Executors.html

Decide on where to place documentation:

• Tutorial (more in-depth description)
• How-To-Guides (step-by-step description how to implement something specific )

Documentation at ros-realtime.github.io

Ressource	What-to-do?	Assignee	Status
ros-realtime.github.io/Guides
ros-realtime.github.io/Benchmarks
ros-realtime.github.io/Subprojects
ros-realtime.github.io/Related-Projects
ros-realtime.github.io/Resources

My proposal: copy&paste most of this documentation to some page on docs.ros.org.

Other documentation:

Ressource	What-to-do?	Assignee	Status
Executor Workshop	add link to some page
Introduction to Real-time Systems

Documentation Work-In-Progress

Ressource	What-to-do?	Assignee	Status
ros.docs.org/How-To-Guides/Developing-a-real-time-application

[JanStaschulat]

Grand theory of documentation: https://diataxis.fr/
What is the difference between a Tuturial and a How-To-Guide? https://diataxis.fr/tutorials-how-to/#tutorials-how-to

[JanStaschulat]

Link to document for consolidating real-time documentation

[JanStaschulat]

Proposal for restructured real-time documentation at docs.ros.org:
The links are pointing to existing pages on docs.ros.org or other places. These documentation pages might need some update.

Tutorials

• Beginner
• Intermediate
• Advanced
  • Real-Time
    • Real-Time Application Configuration
    • Operating System Setup with RT Linux Kernel
    • ROS 2 Tracing
• Demos
  • Pendulum Demo
• Miscellaneous

How-To-Guides

• Building-Realtime-rt_preempt-kernel-for-ROS-2
• Building-ROS-2-with-Tracing-Instrumentation (merge with: ros2_trace_and_analyze)
• Installing-on-Raspberry-Pi
• Using-callback-groups

Concepts

• About-Real-Time-In-ROS2
• Concepts/About-Executors.html

[JanStaschulat]

Updated the Real-Time Documentation for ROS 2 document.

Please review and add further existing pages in the table in section "Current status". Some items in the new proposed structure contain already a link to an existing pages.

[christophebedard]

• Building-ROS-2-with-Tracing-Instrumentation (merge with: ros2_trace_and_analyze)

I wouldn't merge these two. Keeping the "Building ROS 2 with Tracing Instrumentation" as a standalone guide allows us to link to just that from anywhere. We could of course mention the other guide at the end as a logical follow-up guide.

Edit: also, we want to enable instrumentation by default (ros2/ros2#1177), so the first guide will eventually not be required in order to follow the second guide.

[nightduck]

Tutorials

• Beginner
• Intermediate
• Advanced
  • Real-Time
    • Real-Time Application Configuration
    • Operating System Setup with RT Linux Kernel
    • ROS 2 Tracing
• Demos
  • Pendulum Demo

I think Pendulum Demo and Real-time Application configuration could be merged into one (heavily-rewritten) tutorial. The Pendulum could serve as the hello world program for real-time.

[JanStaschulat]

Thank you very much for your active discussion in todays RTWG meeting. I updated our proposal for a consolidated real-time documentation. Next step would be, that we create and/or update the pages in our fork of ros2_documentation.

[JanStaschulat]

Made an initial commit in the branch update-real-time in our fork of the ros2_documentation repository. I just created the subsection "Real-Time" and moved the existing pages there. Also added one page in Concepts section.

I would propose, to first come up with a good outline in Develop-Real-Time-Application.

[JanStaschulat]

Created real-time tutorial (using real-time threads): https://github.com/ros-realtime/ros2_documentation/blob/feature/update-real-time/source/Tutorials/Advanced/Real-Time/Real-Time-Processing-with-multiple-threads.rst

Added code example to ros2-realtime-examples: ros-realtime/ros2-realtime-examples#10

[christophebedard]

@nightduck I think you mentioned during a RTWG meeting a few weeks ago that you were working on porting/moving the "How to use ros2_tracing to trace and analyze an application" tutorial to docs.ros.org. What is the status? I can help.

[JanStaschulat]

Hi @christophebedard . We have not created any page yet. The idea is to have a seperate page about "ros2 tracing" outside the Tutorial/Advanced/RealTime tab. So, from my perspective, you can just go ahead. Any help very much appreciated.

[nightduck]

@christophebedard sorry for the late response, I was at a conference. The page has been ported, but we're not submitting a pull request until we've finished other modifications we're making. You can track our progress by monitoring that branch and the viewing the document @JanStaschulat linked Feb 9th:

Updated the Real-Time Documentation for ROS 2 document.

[christophebedard]

but we're not submitting a pull request until we've finished other modifications we're making.

The "How to use ros2_tracing to trace and analyze an application" tutorial doesn't really need to wait until everything else has been ported (it's better to make smaller PRs instead of a single big one), but sure, that's fine.

[JanStaschulat]

@christophebedard , Yes, I agree. As the ros2_tracing tutorial will not be part of the Advanced/Tutorial/Realtime tab, you can go ahead and update the documentation in a separate PR.

[christophebedard]

@nightduck do you want to do it, or should I?

[nightduck]

I can do it. Will ping you with the new PR later today

…

On Tue, May 16, 2023, 12:50 PM Christophe Bedard ***@***.***> wrote: @nightduck <https://github.com/nightduck> do you want to do it, or should I? — Reply to this email directly, view it on GitHub <#41 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACNQEJ6TDVJZWCVZVUICWDDXGO46BANCNFSM5YJDDQJA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[JanStaschulat]

@carlossvg @shuhaowu @nightduck

I updated

• the tutorial https://github.com/ros-realtime/ros2_documentation/blob/feature/update-real-time/source/Tutorials/Advanced/Real-Time/Real-Time-Processing-with-multiple-threads.rst and
• the demo code example added minimal_scheduling_real_time_tutorial.cpp ros2-realtime-examples#10

Could you have a look and review?

[carlossvg]

@JanStaschulat I didn't find a PR to add my comments so I will post them here in the meanwhile.

The real-time setup is tested by counting the number of context switches of other kernel processes.

I would rephrase this. It sounds like we count the context switches for other processes different than the example.

It should be zero for the real-time callback.

I would clarify it is expected to see some involuntary context switches even with a real-time priority. There might be other threads with higher priority or interrupts preempting the real-time callback execution.

The complete source file of this tutorial is available here.

The link seems to be broken.

Then, we assign to the realtime_thread the priority, that was passed by the command line argument. We are not assigning any scheduling parameter to the default_thread, so that the Publisher and the non real-time Subscription will be processed with default Linux settings.

We should clarify this tutorial is specific for Linux.

Note, that this construction of the thread function calls the spin()-function of the Executor. That implies that all callbacks that are managed by the Executor will be processed by this thread and regarding the execution timing "inherit" the scheduling policy of this thread.

I would clarify what we mean here with execution timing. Also, the term inherit could be misleading, it could be confusing when talking about middleware thread which could inherit the parent's thread scheduling attributes.

We should probably mention what happens to those threads in this example. In this particular thread only the thread we create to spin the executor will have real-time priority while the middleware threads won't.

[JanStaschulat]

@carlossvg (CC @christophebedard @nightduck @razr) Thank you for your review comments. I updated the tutorial accordingly. I created a pull request ros2/ros2_documentation#3756 but put it in DRAFT mode. I still need to write the tutorial with callack groups and I'd like to ask Andrei to update the operating systems tutorial.