diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 742791b0d..91b3ec7e3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,21 +15,21 @@ jobs: with: submodules: true - - name: Set up Ruby 2.7 - uses: actions/setup-ruby@v1 + - name: Set up Ruby 3.4.5 + uses: ruby/setup-ruby@v1 with: - ruby-version: 2.7.x + ruby-version: 3.4.5 - name: Install Bundler - run: gem install bundler + run: gem install bundler -v 2.7.2 - - uses: actions/cache@v1 + - uses: actions/cache@v4 with: path: vendor/bundle key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }} restore-keys: | ${{ runner.os }}-gems- - + - name: Bundle install run: | bundle config path vendor/bundle diff --git a/.github/workflows/generate_api_reference.yml b/.github/workflows/generate_api_reference.yml index f55aa4c86..2f666340d 100644 --- a/.github/workflows/generate_api_reference.yml +++ b/.github/workflows/generate_api_reference.yml @@ -10,7 +10,7 @@ on: jobs: generate_rmw_api_reference: runs-on: ubuntu-latest - container: ros:foxy + container: ros:iron steps: - uses: actions/checkout@v3 - run: git config --global --add safe.directory "$GITHUB_WORKSPACE" @@ -28,10 +28,10 @@ jobs: unzip doxybook2-linux-amd64-v1.3.3.zip -d doxybook2 mkdir -p ros2_ws/src; cd ros2_ws - git clone -b foxy https://github.com/eProsima/Micro-CDR src/Micro-CDR - git clone -b foxy https://github.com/eProsima/Micro-XRCE-DDS-Client src/Micro-XRCE-DDS-Client - git clone -b foxy https://github.com/micro-ROS/rosidl_typesupport_microxrcedds src/rosidl_typesupport_microxrcedds - git clone -b foxy https://github.com/micro-ROS/rmw-microxrcedds src/rmw-microxrcedds + git clone -b ros2 https://github.com/eProsima/Micro-CDR src/Micro-CDR + git clone -b ros2 https://github.com/eProsima/Micro-XRCE-DDS-Client src/Micro-XRCE-DDS-Client + git clone -b iron https://github.com/micro-ROS/rosidl_typesupport_microxrcedds src/rosidl_typesupport_microxrcedds + git clone -b iron https://github.com/micro-ROS/rmw-microxrcedds src/rmw-microxrcedds source /opt/ros/$ROS_DISTRO/setup.bash colcon build --packages-up-to rmw_microxrcedds --cmake-args -DBUILD_DOCUMENTATION=ON @@ -50,7 +50,7 @@ jobs: generate_utils_api_reference: runs-on: ubuntu-latest - container: ros:foxy + container: ros:iron steps: - uses: actions/checkout@v3 - run: git config --global --add safe.directory "$GITHUB_WORKSPACE" @@ -61,14 +61,14 @@ jobs: shell: bash run: | apt update - apt install -y doxygen wget git unzip cmake ros-foxy-osrf-testing-tools-cpp + apt install -y doxygen wget git unzip cmake ros-iron-osrf-testing-tools-cpp pushd / wget https://github.com/matusnovak/doxybook2/releases/download/v1.3.3/doxybook2-linux-amd64-v1.3.3.zip unzip doxybook2-linux-amd64-v1.3.3.zip -d doxybook2 mkdir -p ros2_ws/src; cd ros2_ws - git clone -b humble https://github.com/micro-ROS/micro_ros_utilities src/micro_ros_utilities + git clone -b iron https://github.com/micro-ROS/micro_ros_utilities src/micro_ros_utilities source /opt/ros/$ROS_DISTRO/setup.bash colcon build --packages-up-to micro_ros_utilities --cmake-args -DBUILD_DOCUMENTATION=ON diff --git a/Gemfile b/Gemfile index d313333c9..821e42f4d 100644 --- a/Gemfile +++ b/Gemfile @@ -2,6 +2,6 @@ source 'https://rubygems.org' gem 'github-pages', group: :jekyll_plugins # Testing utilities -gem "html-proofer" +gem "html-proofer", "3.19.4" #gemspec \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index cc853657d..b3e3f4c1b 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,61 +1,65 @@ GEM remote: https://rubygems.org/ specs: - activesupport (6.0.4) - concurrent-ruby (~> 1.0, >= 1.0.2) - i18n (>= 0.7, < 2) - minitest (~> 5.1) - tzinfo (~> 1.1) - zeitwerk (~> 2.2, >= 2.2.2) - addressable (2.8.0) - public_suffix (>= 2.0.2, < 5.0) + activesupport (8.0.2.1) + base64 + benchmark (>= 0.3) + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + logger (>= 1.4.2) + minitest (>= 5.1) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + uri (>= 0.13.1) + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + base64 (0.3.0) + benchmark (0.4.1) + bigdecimal (3.2.3) coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.11.1) + coffee-script-source (1.12.2) colorator (1.1.0) - commonmarker (0.23.6) - ruby-enum (~> 0.5) - concurrent-ruby (1.1.9) - dnsruby (1.61.7) - simpleidn (~> 0.1) - em-websocket (0.5.2) + commonmarker (0.23.11) + concurrent-ruby (1.3.5) + connection_pool (2.5.4) + csv (3.3.5) + dnsruby (1.73.0) + base64 (>= 0.2) + logger (~> 1.6) + simpleidn (~> 0.2.1) + drb (2.2.3) + em-websocket (0.5.3) eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.14.0) + http_parser.rb (~> 0) + ethon (0.15.0) ffi (>= 1.15.0) eventmachine (1.2.7) - execjs (2.8.1) - faraday (1.5.1) - faraday-em_http (~> 1.0) - faraday-em_synchrony (~> 1.0) - faraday-excon (~> 1.1) - faraday-httpclient (~> 1.0.1) - faraday-net_http (~> 1.0) - faraday-net_http_persistent (~> 1.1) - faraday-patron (~> 1.0) - multipart-post (>= 1.2, < 3) - ruby2_keywords (>= 0.0.4) - faraday-em_http (1.0.0) - faraday-em_synchrony (1.0.0) - faraday-excon (1.1.0) - faraday-httpclient (1.0.1) - faraday-net_http (1.0.1) - faraday-net_http_persistent (1.1.0) - faraday-patron (1.0.0) - ffi (1.15.4) + execjs (2.10.0) + faraday (2.13.4) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.1) + net-http (>= 0.5.0) + ffi (1.17.2-x86_64-linux-gnu) forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (215) - github-pages-health-check (= 1.17.2) - jekyll (= 3.9.0) - jekyll-avatar (= 0.7.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.1.6) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.15.1) + gemoji (4.1.0) + github-pages (232) + github-pages-health-check (= 1.18.2) + jekyll (= 3.10.0) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) + jekyll-commonmark-ghpages (= 0.5.1) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.13.0) + jekyll-github-metadata (= 2.16.1) + jekyll-include-cache (= 0.2.1) jekyll-mentions (= 1.6.0) jekyll-optional-front-matter (= 0.3.2) jekyll-paginate (= 1.1.0) @@ -64,57 +68,59 @@ GEM jekyll-relative-links (= 0.6.1) jekyll-remote-theme (= 0.4.3) jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.7.1) + jekyll-seo-tag (= 2.8.0) jekyll-sitemap (= 1.4.0) jekyll-swiss (= 1.0.0) - jekyll-theme-architect (= 0.1.1) - jekyll-theme-cayman (= 0.1.1) - jekyll-theme-dinky (= 0.1.1) - jekyll-theme-hacker (= 0.1.2) - jekyll-theme-leap-day (= 0.1.1) - jekyll-theme-merlot (= 0.1.1) - jekyll-theme-midnight (= 0.1.1) - jekyll-theme-minimal (= 0.1.1) - jekyll-theme-modernist (= 0.1.1) - jekyll-theme-primer (= 0.5.4) - jekyll-theme-slate (= 0.1.1) - jekyll-theme-tactile (= 0.1.1) - jekyll-theme-time-machine (= 0.1.1) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.12.0) - kramdown (= 2.3.1) + jemoji (= 0.13.0) + kramdown (= 2.4.0) kramdown-parser-gfm (= 1.1.0) - liquid (= 4.0.3) + liquid (= 4.0.4) mercenary (~> 0.3) minima (= 2.5.1) - nokogiri (>= 1.10.4, < 2.0) - rouge (= 3.26.0) + nokogiri (>= 1.16.2, < 2.0) + rouge (= 3.30.0) terminal-table (~> 1.4) - github-pages-health-check (1.17.2) + webrick (~> 1.8) + github-pages-health-check (1.18.2) addressable (~> 2.3) dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (>= 2.0.2, < 5.0) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) typhoeus (~> 1.3) - html-pipeline (2.14.0) + html-pipeline (2.14.3) activesupport (>= 2) nokogiri (>= 1.4) - html-proofer (3.19.2) + html-proofer (3.19.4) addressable (~> 2.3) mercenary (~> 0.3) - nokogumbo (~> 2.0) - parallel (~> 1.3) + nokogiri (~> 1.13) + parallel (~> 1.10) rainbow (~> 3.0) typhoeus (~> 1.3) yell (~> 2.0) - http_parser.rb (0.6.0) - i18n (0.9.5) + http_parser.rb (0.8.0) + i18n (1.14.7) concurrent-ruby (~> 1.0) - jekyll (3.9.0) + jekyll (3.10.0) addressable (~> 2.4) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) - i18n (~> 0.7) + i18n (>= 0.7, < 2) jekyll-sass-converter (~> 1.0) jekyll-watch (~> 2.0) kramdown (>= 1.17, < 3) @@ -123,27 +129,30 @@ GEM pathutil (~> 0.9) rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - jekyll-avatar (0.7.0) + webrick (>= 1.0) + jekyll-avatar (0.8.0) jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.1.1) + jekyll-coffeescript (1.2.2) coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.3.1) - commonmarker (~> 0.14) - jekyll (>= 3.7, < 5.0) - jekyll-commonmark-ghpages (0.1.6) - commonmarker (~> 0.17.6) - jekyll-commonmark (~> 1.2) - rouge (>= 2.0, < 4.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.15.1) + coffee-script-source (~> 1.12) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.5.1) + commonmarker (>= 0.23.7, < 1.1.0) + jekyll (>= 3.9, < 4.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) jekyll (>= 3.7, < 5.0) jekyll-gist (1.5.0) octokit (~> 4.2) - jekyll-github-metadata (2.13.0) + jekyll-github-metadata (2.16.1) jekyll (>= 3.4, < 5.0) - octokit (~> 4.0, != 4.4.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) jekyll-mentions (1.6.0) html-pipeline (~> 2.3) jekyll (>= 3.7, < 5.0) @@ -163,129 +172,122 @@ GEM rubyzip (>= 1.3.0, < 3.0) jekyll-sass-converter (1.5.2) sass (~> 3.4) - jekyll-seo-tag (2.7.1) + jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) jekyll-sitemap (1.4.0) jekyll (>= 3.7, < 5.0) jekyll-swiss (1.0.0) - jekyll-theme-architect (0.1.1) - jekyll (~> 3.5) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.1.1) - jekyll (~> 3.5) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.1.1) - jekyll (~> 3.5) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.1.2) + jekyll-theme-hacker (0.2.0) jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.1.1) - jekyll (~> 3.5) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.1.1) - jekyll (~> 3.5) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.1.1) - jekyll (~> 3.5) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.1.1) - jekyll (~> 3.5) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.1.1) - jekyll (~> 3.5) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.5.4) + jekyll-theme-primer (0.6.0) jekyll (> 3.5, < 5.0) jekyll-github-metadata (~> 2.9) jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.1.1) - jekyll (~> 3.5) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.1.1) - jekyll (~> 3.5) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.1.1) - jekyll (~> 3.5) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) jekyll-seo-tag (~> 2.0) jekyll-titles-from-headings (0.5.3) jekyll (>= 3.3, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - jemoji (0.12.0) - gemoji (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) html-pipeline (~> 2.2) jekyll (>= 3.0, < 5.0) - kramdown (2.3.1) + json (2.13.2) + kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) - liquid (4.0.3) - listen (3.5.1) + liquid (4.0.4) + listen (3.9.0) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) mercenary (0.3.6) - mini_portile2 (2.8.0) minima (2.5.1) jekyll (>= 3.5, < 5.0) jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) - minitest (5.14.4) - multipart-post (2.1.1) - nokogiri (1.13.6) - mini_portile2 (~> 2.8.0) + minitest (5.25.5) + net-http (0.6.0) + uri + nokogiri (1.18.9-x86_64-linux-gnu) racc (~> 1.4) - nokogumbo (2.0.5) - nokogiri (~> 1.8, >= 1.8.4) - octokit (4.21.0) - faraday (>= 0.9) - sawyer (~> 0.8.0, >= 0.5.3) - parallel (1.21.0) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + parallel (1.27.0) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (4.0.6) - racc (1.6.0) - rainbow (3.0.0) - rb-fsevent (0.11.0) - rb-inotify (0.10.1) + public_suffix (5.1.1) + racc (1.8.1) + rainbow (3.1.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.2.5) - rouge (3.26.0) - ruby-enum (0.9.0) - i18n - ruby2_keywords (0.0.4) - rubyzip (2.3.2) + rexml (3.4.4) + rouge (3.30.0) + rubyzip (2.4.1) safe_yaml (1.0.5) sass (3.7.4) sass-listen (~> 4.0.0) sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.8.2) + sawyer (0.9.2) addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - simpleidn (0.2.1) - unf (~> 0.1.4) + faraday (>= 0.17.3, < 3) + securerandom (0.4.1) + simpleidn (0.2.3) terminal-table (1.8.0) unicode-display_width (~> 1.1, >= 1.1.1) - thread_safe (0.3.6) - typhoeus (1.4.0) - ethon (>= 0.9.0) - tzinfo (1.2.10) - thread_safe (~> 0.1) - unf (0.1.4) - unf_ext - unf_ext (0.0.7.7) - unicode-display_width (1.7.0) + typhoeus (1.5.0) + ethon (>= 0.9.0, < 0.16.0) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (1.8.0) + uri (1.0.3) + webrick (1.9.1) yell (2.2.2) - zeitwerk (2.4.2) PLATFORMS - ruby + x86_64-linux DEPENDENCIES github-pages - html-proofer + html-proofer (= 3.19.4) BUNDLED WITH - 2.1.4 + 2.7.2 diff --git a/README.md b/README.md index 709d97db7..4f504dcb3 100644 --- a/README.md +++ b/README.md @@ -34,10 +34,90 @@ Please note the following third-party elements and content: For details on the open source components included in the micro-ros.github.io repository, see the file [3rd-party-licenses.txt](3rd-party-licenses.txt). ## Running locally +This project uses Jekyll, the static site generator behind GitHub Pages (see [Jekyll Quickstart](https://jekyllrb.com/docs/) for more information). +To preview the site locally, you’ll need to install Ruby, Jekyll, and the project dependencies. + +### Prerequisites +Make sure your system has the necessary build tools and libraries for compiling Ruby and Jekyll dependencies: + +```bash +sudo apt update +sudo apt install -y \ + libffi-dev \ + libyaml-dev \ + git +``` + +### Install Ruby via rbenv +We recommend using rbenv to manage Ruby versions locally: + +```bash +# Install rbenv +sudo apt install -y rbenv + +# Add rbenv to your shell +echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc +source ~/.bashrc + +# Install ruby-build plugin +git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build +git -C "$(rbenv root)"/plugins/ruby-build pull + +# Install Ruby 3.4.5 +rbenv install 3.4.5 +rbenv global 3.4.5 +``` + +### Configure UTF-8 Locale +Jekyll and its plugins require UTF-8 encoding to handle special characters correctly: + +```bash +export LC_ALL="C.UTF-8" +export LANG="en_US.UTF-8" +export LANGUAGE="en_US.UTF-8" +``` + +### Install Jekyll and Bundler + +```bash +gem install jekyll bundler +``` + +Using a Bundler version different from the one recorded in the `Gemfile.lock` (currently 2.7.2) may lead to compatibility issues. +You can check your installed Bundler version by running: + +```bash +bundler -v +``` + +### Clone repository and dependencies +For the includes of README.md files on the micro-ROS demos (in the tutorials chapter) from the corresponding repositories, please init and update the corresponding git submodules: + +```bash +git clone https://github.com/micro-ROS/micro-ROS.github.io.git +cd micro-ROS.github.io/ + +# Fetch tutorials and demos included via submodules +git submodule update --init --recursive +``` + +### Install project dependencies +After installing Jekyll, install all dependencies by running: + +```bash +bundle install +``` + +### Run the Jekyll server +You may launch Jekyll to build and serve the website continuously by running: + +```bash +bundle exec jekyll serve +``` + +By default, the site will be available at http://localhost:4000 -To test locally, you need a local version of Jekyll, the site-generation -engine used by GitHub Pages. See [Jekyll Quickstart](https://jekyllrb.com/docs/) -for installation instructions. After installing Jekyll, install all dependencies by running ```bash @@ -49,7 +129,18 @@ Then, you may launch Jekyll to build and serve the website continuously by bundle exec jekyll serve ``` -For the includes of README.md files on the micro-ROS demos (in the tutorials chapter) from the corresponding repositories, please init and update the corresponding git submodules (i.e. `git submodule init ; git submodule update`). +### (Optional) Regenerate `Gemfile.lock` file + +When updating Ruby or Bundler version it is possible that dependencies no longer resolve cleanly, causing `bundle install` to fail. +It can be fixed by regenerating the `Gemfile.lock` file and commiting the changes: + +```bash +rm Gemfile.lock + +bundle install +``` + +This will resolve all dependencies defined in your `Gemfile` and generate a new `Gemfile.lock` consistent with your current Bundler version and available gems. ## Testing generated site diff --git a/_data/docs.yml b/_data/docs.yml index 9481b4d86..437a5b128 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -74,7 +74,6 @@ - tutorials/advanced/create_custom_transports - tutorials/advanced/create_custom_static_library - tutorials/advanced/benchmarking - - tutorials/advanced/tracing - title: Unmaintained Tutorials docs: diff --git a/_docs/concepts/build_system/external_build_systems/index.md b/_docs/concepts/build_system/external_build_systems/index.md index e0a4e9829..6dad01c45 100644 --- a/_docs/concepts/build_system/external_build_systems/index.md +++ b/_docs/concepts/build_system/external_build_systems/index.md @@ -27,4 +27,4 @@ Along with this support package, there are [detailed instructions](https://githu The [micro-ROS for STM32CubeMX](https://github.com/micro-ROS/micro_ros_stm32cubemx_utils) package is a set of utilities which enables the seamless configuration, set-up and integration of micro-ROS into an STM32 controller based project. As such, it allows micro-ROS to be virtually supported by the full set of boards offered by STMicroelectronics. -Its usage is based on Dockers, via a prepared [Dockerfile](https://github.com/micro-ROS/docker/blob/foxy/micro-ROS-static-library-builder/Dockerfile) which eases micro-ROS library generation outside of a ROS 2 environment. +Its usage is based on Dockers, via a prepared [Dockerfile](https://github.com/micro-ROS/docker/blob/humble/micro-ROS-static-library-builder/Dockerfile) which eases micro-ROS library generation outside of a ROS 2 environment. diff --git a/_docs/concepts/client_library/execution_management/index.md b/_docs/concepts/client_library/execution_management/index.md index b4596d9d9..a376db71e 100644 --- a/_docs/concepts/client_library/execution_management/index.md +++ b/_docs/concepts/client_library/execution_management/index.md @@ -71,11 +71,11 @@ Given the goals for a Real-Time Executor and the limitations of the ROS 2 standa - to model requirements (like latencies, determinism in subsystems) - mapping of ROS 2 framework and operating system schedulers (semi-automated and optimized mapping is desired as well as generic, well-understood framework mechanisms) -Our approach is to provide a real-time-capable Executor for the rcl+rclc layer (as described in section [Introduction to Client Library](../).) in the C programming language . +Our approach is to provide a real-time-capable Executor for the rcl+rclc layer (as described in section [Introduction to Client Library](../).) in the C programming language. As the first step, we propose the rclc Executor for the rcl-layer in C programming language with several new features to support real-time and deterministic execution: It supports 1.) user-defined static sequential execution, 2) conditional execution semantics, 3) multi-threaded execution with scheduling configuration, and 4) logical execution semantics (LET). Sequential execution refers to the runtime behavior, that all callbacks are executed in a pre-defined order independent of the arrival time of messages. Conditional execution is available with a trigger condition which enables typical processing patterns in robotics (which are analyzed in detail in section [Analysis of processing patterns](#analysis-of-processing-patterns). Configuration of scheduling parameters for multi-threaded application accomplishes prioritized execution. The logical execution time concept (LET) provides data synchronization for fixed periodic task scheduling of embedded applications. -Beyond the advanced execution management mechanisms for micro-ROS, we also contributed to improving and extending the Executor concept in rclcpp for standard ROS 2: the callback group-level Executor. It is not a new Executor but rather a refinement of the ROS 2 Executor API allowing to prioritize a group of callbacks which is not possible with the ROS 2 default Executor in its current Humble release. +Beyond the advanced execution management mechanisms for micro-ROS, we also contributed to improving and extending the Executor concept in rclcpp for standard ROS 2: the callback group-level Executor. It is not a new Executor but rather a refinement of the ROS 2 Executor API allowing to prioritize a group of callbacks which is not possible with the ROS 2 default Executor in its current Iron release. ## Analysis of rclcpp standard Executor @@ -218,7 +218,7 @@ Figure 7: Processes with sequentially executed tasks. While there are different ways to assign priorities to a given number of processes, the rate-monotonic scheduling assignment, in which processes with a shorter period have a higher priority, has been shown optimal if the processor utilization is less than 69% [[LL1973](#LL1973)]. - In the last decades many different scheduling approaches have been presented, however fixed-periodic preemptive scheduling is still widely used in embedded real-time systems [[KZH2015](#KZH2015)]. This becomes also obvious, when looking at the features of current operating systems. Like Linux, real-time operating systems, such as NuttX, Zephyr, FreeRTOS, QNX etc., support fixed-periodic preemptive scheduling and the assignment of priorities, which makes the time-triggered paradigm the dominant design principle in this domain. + In the last decades many different scheduling approaches have been presented; however fixed-periodic preemptive scheduling is still widely used in embedded real-time systems [[KZH2015](#KZH2015)]. This becomes also obvious, when looking at the features of current operating systems. Like Linux, real-time operating systems, such as NuttX, Zephyr, FreeRTOS, QNX etc., support fixed-periodic preemptive scheduling and the assignment of priorities, which makes the time-triggered paradigm the dominant design principle in this domain. However, data consistency is often an issue when preemptive scheduling is used and if data is being shared across multiple processes via global variables. Due to scheduling effects and varying execution times of processes, writing and reading these variables could occur sometimes sooner or later. This results in a latency jitter of update times (the timepoint at which a variable change becomes visible to other processes). Race conditions can occur when multiple processes access a variable at the same time. So to solve this problem, the concept of logical-execution time (LET) was introduced in [[HHK2001](#HHK2001)], in which communication of data occurs only at pre-defined periodic time instances: Reading data only at the beginning of the period and writing data only at the end of the period. The cost of an additional latency delay is traded for data consistency and reduced jitter. This concept has also recently been applied to automotive applications[[NSP2018](#NSP2018)]. @@ -350,7 +350,7 @@ The selection of the Executor semantics is optional. The default semantics is "R #### Multi-threading and scheduling configuration -The rclc Executor has been extended for multi-threading. It supports the assignment of scheduling policies, like priorities or more advanced scheduling algorithms as reservation-based scheduling, to subscription callbacks. [[Pull Request](https://github.com/ros2/rclc/pull/87), Pre-print [SLD2021](#SLD2021)]. The overall architecture is shown in Figure 15. One Executor thread is responsible for checking for new data from the DDS queue. For every callback, a thread is spawned with the dedicted scheduling policy provided by the operating system. The Executor then dispatches new data of a subscription to it's corresponding callback function, which is then executed in its own thread by operating system. +The rclc Executor has been extended for multi-threading. It supports the assignment of scheduling policies, like priorities or more advanced scheduling algorithms as reservation-based scheduling, to subscription callbacks. [[Pull Request](https://github.com/ros2/rclc/pull/87), Pre-print [SLD2021](#SLD2021)]. The overall architecture is shown in Figure 15. One Executor thread is responsible for checking for new data from the DDS queue. For every callback, a thread is spawned with the dedicted scheduling policy provided by the operating system. The Executor then dispatches new data of a subscription to its corresponding callback function, which is then executed in its own thread by operating system.
Multi-threaded rclc Executor @@ -429,9 +429,9 @@ rclc_executor_add_subscription(&exe_act, &act, &my_sub_cb4, ON_NEW_DATA); // spin all executors while (true) { - rclc_executor_spin_some(&exe_sense); - rclc_executor_spin_some(&exe_plan); - rclc_executor_spin_some(&exe_act); + rclc_executor_spin_some(&exe_sense, RCL_MS_TO_NS(100)); + rclc_executor_spin_some(&exe_plan, RCL_MS_TO_NS(100)); + rclc_executor_spin_some(&exe_act, RCL_MS_TO_NS(100)); } ``` @@ -455,8 +455,8 @@ rclc_executor_set_trigger(&exe_sense, rclc_executor_trigger_all, NULL); // spin all executors while (true) { - rclc_executor_spin_some(&exe_aggr); - rclc_executor_spin_some(&exe_sense); + rclc_executor_spin_some(&exe_aggr, RCL_MS_TO_NS(100)); + rclc_executor_spin_some(&exe_sense, RCL_MS_TO_NS(100)); } ``` @@ -505,9 +505,9 @@ rclc_executor_spin(&exe); #### Real-time embedded applications example -With seqential execution the co-operative scheduling of tasks within a process can be modeled. The trigger condition is used to periodically activate the process which will then execute all callbacks in a pre-defined order. Data will be communicated using the LET-semantics. Every Executor is executed in its own tread, to which an appropriate priority can be assigned. +With sequential execution, the co-operative scheduling of tasks within a process can be modeled. The trigger condition is used to periodically activate the process which will then execute all callbacks in a pre-defined order. Data will be communicated using the LET-semantics. Every Executor is executed in its own thread, to which an appropriate priority can be assigned. -In the following example, the Executor is setup with 4 handles. We assume a process has three subscriptions `sub1`, `sub2`, `sub3`. The sequential processing order is given by the order as they are added to the Executor. A timer `timer` defines the period. The `trigger_one` with the paramter `timer` is used, so that whenever the timer is ready, all callbacks are processed. Finally the data communication semantics LET is defined. +In the following example, the Executor is setup with 4 handles. We assume a process has three subscriptions `sub1`, `sub2`, `sub3`. The sequential processing order is given by the order as they are added to the Executor. A timer `timer` defines the period. The `trigger_one` with the parameter `timer` is used, so that whenever the timer is ready, all callbacks are processed. Finally the data communication semantics LET is defined. ```C #include "rcl_executor/let_executor.h" @@ -578,10 +578,10 @@ The slides can be downloaded [here](https://ec2a4d36-bac8-4759-b25e-bb1f794177f4 - one publisher that periodically publishes - if Executors are running in multiple threads, publishing needs to be atomic -- Multi-threaded executor with assignment of scheduling policies of unerlying operating system. [[Pull Request](https://github.com/ros2/rclc/pull/87), pre-print [SLD2021](#SLD2021)]. +- Multi-threaded executor with assignment of scheduling policies of underlying operating system. [[Pull Request](https://github.com/ros2/rclc/pull/87), pre-print [SLD2021](#SLD2021)]. ### Download -The rclc Executor can be downloaded from the [ros2/rclc repository](https://github.com/ros2/rclc). It is available for the ROS 2 versions Foxy, Galactic, Humble and Rolling. The repository provides several packages including the [rclc Executor](https://github.com/ros2/rclc/tree/master/rclc) and an [rclc_examples package](https://github.com/ros2/rclc/tree/master/rclc_examples) with several application examples. +The rclc Executor can be downloaded from the [ros2/rclc repository](https://github.com/ros2/rclc). It is available for the ROS 2 versions Humble, Iron and Rolling. The repository provides several packages including the [rclc Executor](https://github.com/ros2/rclc/tree/master/rclc) and an [rclc_examples package](https://github.com/ros2/rclc/tree/master/rclc_examples) with several application examples. ## Callback-group-level Executor diff --git a/_docs/concepts/client_library/features/index.md b/_docs/concepts/client_library/features/index.md index 7da9dd644..104aead20 100644 --- a/_docs/concepts/client_library/features/index.md +++ b/_docs/concepts/client_library/features/index.md @@ -13,4 +13,4 @@ The micro-ROS Client Library, formed by standard [ROS 2 Client Support Library ( * Lifecycle * Parameters -Most features are already available in the Foxy release. Please see our [Feature Overview page](/docs/overview/features/) for details on the status. To learn developing your own application nodes with rcl + rclc, please head to the corresponding [programming tutorial](/docs/tutorials/programming_rcl_rclc/). +Most features are already available in the Humble release. Please see our [Feature Overview page](/docs/overview/features/) for details on the status. To learn developing your own application nodes with rcl + rclc, please head to the corresponding [programming tutorial](/docs/tutorials/programming_rcl_rclc/). diff --git a/_docs/concepts/client_library/lifecycle_and_system_modes/index.md b/_docs/concepts/client_library/lifecycle_and_system_modes/index.md index 5fbea9b16..7eff2d2a0 100644 --- a/_docs/concepts/client_library/lifecycle_and_system_modes/index.md +++ b/_docs/concepts/client_library/lifecycle_and_system_modes/index.md @@ -64,7 +64,7 @@ Our approach is based on the ROS 2 Lifecycle. The primary goal of the ROS 2 life The description of the concept can be found at: [http://design.ros2.org/articles/node_lifecycle.html](http://design.ros2.org/articles/node_lifecycle.html) The implementation of the Lifecycle Node is described at: -[https://index.ros.org/doc/ros2/Managed-Nodes/](https://index.ros.org/doc/ros2/Managed-Nodes/). +[https://design.ros2.org/articles/node_lifecycle.html](https://design.ros2.org/articles/node_lifecycle.html). ## Main Features diff --git a/_docs/concepts/fiware_interoperability/index.md b/_docs/concepts/fiware_interoperability/index.md index 47810978a..31024d44f 100644 --- a/_docs/concepts/fiware_interoperability/index.md +++ b/_docs/concepts/fiware_interoperability/index.md @@ -31,7 +31,7 @@ To accomplish this, two different approaches can be taken: * Relying on an integration platform that uses a common types language representation, and defines a conversion library from/to the generic type to the specific type of each middleware. While the first approach might result in a more lightweight tool, it has several flaws, for instance a more difficult maintenance and the incapability of communicating with any other middleware, rather than ROS2 or micro-ROS. -On the other hand, using an integration service platform, such as [SOSS](https://github.com/eProsima/soss_v2), enables automatically the possibility of communicating with a wide (and growing) set of middlewares, if their System Handle implementation is available. +On the other hand, using an integration service platform, such as [SOSS](https://github.com/eProsima/Integration-Service), enables automatically the possibility of communicating with a wide (and growing) set of middlewares, if their System Handle implementation is available. ## SOSS: System-Of-Systems-Synthesizer @@ -53,7 +53,7 @@ This common representation is provided, user-wise, using IDL definitions, which ## SOSS-FIWARE System Handle The [FIWARE System Handle](https://github.com/eProsima/SOSS-FIWARE/tree/feature/xtypes-support) allows bringing information from and to FIWARE's Context Broker into the SOSS world. -This [System Handle](https://soss.docs.eprosima.com/en/latest/sh_creation.html) is configured and launched in the same way as any SOSS System Handle. +This System Handle is configured and launched in the same way as any SOSS System Handle. Besides the standard information included in any System Handle's configuration (such as system's name and type, which would be `fiware` for this specific System Handle), in the case of the FIWARE System Handle users must specify two extra YAML key-value pairs, which are the host's IP and port in which this System Handle will try to connect to an instance of FIWARE's Orion Context Broker. @@ -61,9 +61,9 @@ in the case of the FIWARE System Handle users must specify two extra YAML key-va Regarding more specific details about the implementation, FIWARE does not allow certain characters in its entities names. For this reason, if a type defined in the topics section of the configuration file has in its name a /, the FIWARE System Handle will map that character into two underscores. This is something important to notice when connecting to ROS2, because in ROS2 most of the types have a / in their names. -To deal with this issue, using SOSS [remapping](https://soss.docs.eprosima.com/en/latest/yaml_config.html?highlight=remap#remapping) capabilities come in handy. +To deal with this issue, using SOSS remapping capabilities come in handy. -Of course, given that micro-ROS applications act as a bridge between microcontrollers and the ROS 2 dataspace (using the micro-ROS Agent), FIROS2 should also take care of communicating FIWARE's Context Broker with ROS 2, leveraging the existing [ROS 2 System Handle](https://github.com/eProsima/soss_v2/tree/feature/xtypes-dds/packages/ros2), which comes natively included into the SOSS package. +Of course, given that micro-ROS applications act as a bridge between microcontrollers and the ROS 2 dataspace (using the micro-ROS Agent), FIROS2 should also take care of communicating FIWARE's Context Broker with ROS 2, leveraging the existing [ROS 2 System Handle](https://github.com/eProsima/Integration-Service), which comes natively included into the SOSS package. This is exactly the situation reflected in the use case that is explained below. @@ -79,7 +79,7 @@ This is exactly the situation reflected in the use case that is explained below. * Clone the SOSS project into the source subfolder. ```bash - $ git clone https://github.com/osrf/soss_v2.git src/soss --branch feature/xtypes-dds + $ git clone https://github.com/eProsima/Integration-Service.git src/soss --branch feature/xtypes-dds ``` * Clone the SOSS-FIWARE project into the source subfolder. @@ -119,7 +119,7 @@ This is exactly the situation reflected in the use case that is explained below. ### Configuration -SOSS must be configured with a [YAML](https://soss.docs.eprosima.com/en/latest/yaml_config.html) file, which tells the program everything it needs to know in order to establish the connection between two or more systems that the user wants. +SOSS must be configured with a YAML file, which tells the program everything it needs to know in order to establish the connection between two or more systems that the user wants. For example, if the user wants to exchange a simple string message between FIWARE and ROS2, the configuration file for SOSS should look as follows: ```yaml diff --git a/_docs/concepts/rtos/comparison/index.md b/_docs/concepts/rtos/comparison/index.md index cd7b7cad1..5a1d5eb88 100644 --- a/_docs/concepts/rtos/comparison/index.md +++ b/_docs/concepts/rtos/comparison/index.md @@ -80,7 +80,7 @@ The comparison regards the features listed below: | ROM | "small footprint" | 5 - 10 kB | "small footprint" | | **Safety Certification** | | | | | Software Development Process DO178B Level A / EUROCAE ED-12B | no | [SafeRTOS: DO178C (Aerspace) by Wittenstein](https://www.highintegritysystems.com/safertos/certification-and-standards/) | no | -| Functional Safety IEC-61508 | no | [SafeRTOS (SIL 3)](https://www.freertos.org/FreeRTOS-Plus/Safety_Critical_Certified/SafeRTOS.shtml) | soon | +| Functional Safety IEC-61508 | no | [SafeRTOS (SIL 3)](http://www.openrtos.net/FreeRTOS-Plus/Safety_Critical_Certified/SafeRTOS-Safety-Critical-Certification.shtml) | soon | | **License** | BSD | MIT and Commercial | Apache 2 | 1 Processes, signals, fpe, segmentation, bus errors, timers, file and directory ops, pipes, c library, IO Port Interface @@ -93,7 +93,7 @@ The comparison regards the features listed below: 5 XDK is based on a microcontroller of the ARM Cortex M3 EFM32GG390F1024 Giant Gecko family by Silicon Labs. Note that the version used in the XDK is not fully supported by Zephyr. -6 [Note: Time slicing](https://www.freertos.org/Documentation/161204_Mastering_the_FreeRTOS_Real_Time_Kernel-A_Hands-On_Tutorial_Guide.pdf) +6 [Note: Time slicing](https://www.freertos.org/media/2018/161204_Mastering_the_FreeRTOS_Real_Time_Kernel-A_Hands-On_Tutorial_Guide.pdf) 7 Hardware-support for Networking and Storage often depends on the platform and sometimes packages of hardware-vendors are available, which work for a particular operating system. But it is in general difficult to determine the harware-support of a given RTOS. diff --git a/_docs/concepts/rtos/index.md b/_docs/concepts/rtos/index.md index 3ba8275e8..625e17e7e 100644 --- a/_docs/concepts/rtos/index.md +++ b/_docs/concepts/rtos/index.md @@ -21,7 +21,7 @@ By clicking on the logos below, you'll be redirected to the Overview section, wh - +

FreeRTOS
Zephyr
Zephyr
NuttX
diff --git a/_docs/overview/ROS_2_feature_comparison/index.md b/_docs/overview/ROS_2_feature_comparison/index.md index 4b1d74f2f..3931788fa 100644 --- a/_docs/overview/ROS_2_feature_comparison/index.md +++ b/_docs/overview/ROS_2_feature_comparison/index.md @@ -3,7 +3,7 @@ title: ROS 2 Feature Comparison permalink: /docs/overview/ROS_2_feature_comparison/ --- -Comparison of micro-ROS features with ROS 2 features. The following list has been compiled from [https://index.ros.org/doc/ros2/Features/](https://index.ros.org/doc/ros2/Features/) and [https://index.ros.org/doc/ros2/Roadmap/](https://index.ros.org/doc/ros2/Roadmap/), and the features have been organized into sub-tables according to the macrocategories defined in the [Features and Architecture page](https://micro-ros.github.io//docs/overview/features/). +Comparison of micro-ROS features with ROS 2 features. The following list has been compiled from [https://docs.ros.org/en/rolling/The-ROS2-Project/Features.html](https://docs.ros.org/en/rolling/The-ROS2-Project/Features.html) and [https://docs.ros.org/en/rolling/The-ROS2-Project/Roadmap.html](https://docs.ros.org/en/rolling/The-ROS2-Project/Roadmap.html), and the features have been organized into sub-tables according to the macrocategories defined in the [Features and Architecture page](https://micro-ros.github.io//docs/overview/features/).