ros-realtime / rtwg_documentation Goto Github PK

There's a guide for building a RT kernel here: https://real-time-working-group.readthedocs.io/en/latest/Guides/Real-Time-Operating-System-Setup/Real-Time-Linux/build_rt_kernel.html

but the instructions here are slightly more up-to-date/better: https://github.com/ros-realtime/rt-kernel-docker-builder

Should the guide be updated with the text from the README? And to de-duplicate we can remove it from the README and point to the guide in the documentation.

We would like to add a document explaining what is the RTWG current roadmap. Something like the ROS 2 docs roadmap: https://docs.ros.org/en/rolling/Roadmap.html

@razr It's clear to me that the two biggest tasks right now are "documentation" and "real-time build-farm". How do we want to structure the roadmap? If we follow the same approach as the ROS 2 roadmap the task should be just a high level description and then there will be multiple specific issues related to that task. Do you think it is okay to just add the two tasks I listed above?

Create documentation branches similar to the ROS2 documentation, i.e. rolling, foxy etc.

@razr, would you submit your changes on this regard? Thanks in advance!

I propose to create a concepts section using the same style as in ROS 2 docs (https://docs.ros.org/en/rolling/Concepts.html). Here we can document different issues to take into account when developing a real-time capable application using ROS 2. This issue can work as place to discuss which topics we want to cover. We can open specific issues for each concept once we decide what to include.

Proposal:

• Memory management
  • Real-time capable containers: https://gitlab.com/ApexAI/apex_containers
  • Static Memory Allocation in DDS and rmw implementations
  • Bounded or fixed-sized data types
  • Memory allocations in ROS 2 and middleware
  • Real-time capable memory allocator
    - https://www.youtube.com/watch?v=l14Zkx5OXr4&ab_channel=CppCon
    - https://docs.ros.org/en/foxy/Tutorials/Allocator-Template-Tutorial.html
    - ros2/rosidl#566
  • Memory locking:
    - https://design.ros2.org/articles/realtime_background.html
    - https://wiki.linuxfoundation.org/realtime/documentation/howto/applications/memory
  • Detection of memory allocation and blocking system calls
    - https://github.com/osrf/osrf_testing_tools_cpp
    - https://gitlab.com/ApexAI/apex_test_tools
    - ros-realtime/community#8
• Logging
• Blocking calls
• Executor
  • ROS 2 callback groups
  • Executor Design https://docs.google.com/document/d/1O53xOVlk4zwsfNukLaDbSWfT64wnoD9xh2EjWwX43qo/edit
  • RCLC executor: https://micro.ros.org//docs/concepts/client_library/execution_management/
• Exceptions safety in C++
  • https://github.com/safety-critical-cpp/papers/blob/master/telecon/Exceptions_in_safety_critical_code.pdf
  • https://github.com/ApexAI/static_exception
  • https://drive.google.com/file/d/1nOhV2pHv24lRDlP5_UnAjwpwhzVLKIi8/view
• Concurrency and synchronization primitives
  • Priority inversion
  • Mutex, lock free, etc

In order to get ensure that all the links available in our docs are still on-line. We need to set up a CI to ensure all links works.

After playing a bit with https://pypi.org/project/LinkChecker/ I can see errors if a url is not correct/exists:

lander@landeru-pc:~/github/rtwg_documentation(foxy)$ linkchecker build/index.html
INFO linkcheck.cmdline 2021-04-28 19:03:04,123 MainThread Checking intern URLs only; use --check-extern to check extern URLs.
LinkChecker 10.0.1
Copyright (C) 2000-2016 Bastian Kleineidam, 2010-2021 LinkChecker Authors
LinkChecker comes with ABSOLUTELY NO WARRANTY!
This is free software, and you are welcome to redistribute it under
certain conditions. Look at the file `LICENSE' within this distribution.
Get the newest version at https://linkchecker.github.io/linkchecker/
Write comments and bugs to https://github.com/linkchecker/linkchecker/issues

Start checking at 2021-04-28 19:03:04+002

URL        `jjjjj'
Name       `kk'
Parent URL file:///home/lander/github/rtwg_documentation/build/index.html, line 109, col 4
Real URL   file:///home/lander/github/rtwg_documentation/build/jjjjj
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/lander/github/rtwg_documentation/build/jjjjj'>

Statistics:
Downloaded: 202.34KB.
Content types: 2 image, 16 text, 0 video, 0 audio, 23 application, 0 mail and 13 other.
URL lengths: min=23, max=95, avg=73.

That's it. 54 links in 54 URLs checked. 0 warnings found. 1 error found.
Stopped checking at 2021-04-28 19:03:05+002 (1 seconds)
lander@landeru-pc:~/github/rtwg_documentation(foxy)$ sudo vim build/index.html 
lander@landeru-pc:~/github/rtwg_documentation(foxy)$ linkchecker build/index.html
INFO linkcheck.cmdline 2021-04-28 19:03:17,711 MainThread Checking intern URLs only; use --check-extern to check extern URLs.
LinkChecker 10.0.1
Copyright (C) 2000-2016 Bastian Kleineidam, 2010-2021 LinkChecker Authors
LinkChecker comes with ABSOLUTELY NO WARRANTY!
This is free software, and you are welcome to redistribute it under
certain conditions. Look at the file `LICENSE' within this distribution.
Get the newest version at https://linkchecker.github.io/linkchecker/
Write comments and bugs to https://github.com/linkchecker/linkchecker/issues

Start checking at 2021-04-28 19:03:17+002

Statistics:
Downloaded: 202.32KB.
Content types: 2 image, 16 text, 0 video, 0 audio, 23 application, 0 mail and 12 other.
URL lengths: min=23, max=95, avg=73.

That's it. 53 links in 53 URLs checked. 0 warnings found. 0 errors found.
Stopped checking at 2021-04-28 19:03:19+002 (1 seconds)

Acceptance criteria

• The docs are hosted using a shared account owned by the RTWG
• Copyright is updated

This is a draft for the RTWG documentation structure:

• Guides
  • Real-time Operating System setup
    • Real Time Linux
      • Build a kernel using Preempt-RT
      • Configure kernel
      • Additional settings (ulimits, interrupt threads, network, cgroups, ....)
    • Configuring VXworks => https://github.com/Wind-River/vxworks7-layer-for-ros2
    • Configuring QNX => ros-realtime/community#5
  • How to configure rmw implementations
    • FastDDS
    • CycloneDDS
    • ConnextMicro/Pro
    • Iceoryx
    • ...
  • How to run a ROS 2 real-time application
  • Best practices
• ROS 2 real-time buildfarm
  • Test environment
  • How to run the tests locally
• Concepts
  • Memory management
  • Exceptions
  • Logging
  • ...
• External resources (articles, guides, ....)
• Roadmap
• Contributing
• Feature ideas
• Subprojects
• Related projects

When configuring the Linux real-time kernel it is useful to be able to configure some boot options. For example: CPU isolation, nohz

One wat to do this is to modify kernel cmdline => https://github.com/ros-realtime/reference-system#isolate-cpus

Acceptance criteria

• A document exists explaining how to set some real-time related boot options

We have agreed to set rules like:

• the submitter of the pull request shall set up at least one reviewer
• after the review is completed whether the reviewer or another person who has write access should merge changes

See discussion under #30 (comment)

The tutorial should cover:

• building ROS 2 with ros2_tracing & LTTng on a PREEMPT_RT Linux kernel (let's start with userspace tracing only)
• running and trace performance_test
• analyzing the trace data using tracetools_analysis to plot the callback durations

Somewhat linked to ros-realtime/community#24. I think writing this tutorial first and then re-using it to write that one would be a good idea.

The goal is to create a document that serves as a starting point for users interested in ROS 2 and real-time. This document would cover:

• What real-time really means. Very fast” versus “deterministic”.
• What is required to have ROS 2 real-time capable applications
  - Design principles of the ROS 2 real-time system.
  - What software and hardware to select. Safety aspects consideration.
  - Programming Language choice.
  - Real-time operating system overview.
  - ROS 2 RTOS support.
• Current status and future work in ROS 2

We can use this document as a reference: http://design.ros2.org/articles/realtime_background.html. We shouldn't overlap the scope of this document with the concepts section or the best practices guide. Those topics should be covered in separate documents.

Acceptance Criteria

• Add ROS 2 and real-time introductory document

I see that there is nothing updated for raspberry pi real time kernel, so I was wondering when will it be updated, or if possible you you suggest some links to keep a real time kernel