diff --git a/.circleci/config.yml b/.circleci/config.yml index 0a39c3a9c7f..a54fe5d281d 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -276,33 +276,6 @@ references: file: lcov/project_coverage.info flags: project when: always - setup_doc_dependencies: &setup_doc_dependencies - run: - name: Install Doc Dependencies - command: | - apk --no-cache add python3 - python3 -m ensurepip - pip3 install sphinx==1.7.5 docutils==0.14 sphinx_rtd_theme breathe==4.9.1 sphinxcontrib-plantuml - apk --no-cache add make - apk --no-cache add doxygen - apk --no-cache add graphviz - apk --no-cache add ttf-dejavu - apk --no-cache add openjdk8-jre - apk --no-cache add bash git openssh - make_docs: &make_docs - run: - command: | - cd src/navigation2/sphinx_doc - make html - store_docs: &store_docs - store_artifacts: - path: /opt/overlay_ws/src/navigation2/sphinx_doc/_build/html - destination: html - publish_docs: &publish_docs - run: - command: | - cd src/navigation2/sphinx_doc - make publish install_deployment_key: &install_deployment_key add_ssh_keys: fingerprints: @@ -349,19 +322,6 @@ commands: steps: - *collect_overlay_coverage - *upload_overlay_coverage - install_doc_dependencies: - description: "Install documentation dependencies" - steps: - - *setup_doc_dependencies - build_docs: - description: "Build docs" - steps: - - *make_docs - - *store_docs - publish_docs_to_gh_pages_branch: - description: "Commit newly built docs to gh-pages branch" - steps: - - *publish_docs executors: debug_exec: @@ -382,12 +342,6 @@ executors: CACHE_NONCE: "Release" OVERLAY_MIXINS: "release ccache" UNDERLAY_MIXINS: "release ccache" - docs_exec: - docker: - - image: alpine:latest - working_directory: /opt/overlay_ws - environment: - <<: *common_environment jobs: debug_build: &debug_build @@ -424,25 +378,6 @@ jobs: <<: *release_test environment: RMW_IMPLEMENTATION: "rmw_fastrtps_cpp" - docs_build: - executor: docs_exec - steps: - - install_doc_dependencies - - *on_checkout - - build_docs - - persist_to_workspace: - root: src/navigation2 - paths: - - sphinx_doc - docs_publish: - executor: docs_exec - steps: - - install_doc_dependencies - - *on_checkout - - *install_deployment_key - - attach_workspace: - at: src/navigation2 - - publish_docs_to_gh_pages_branch workflows: version: 2 @@ -456,15 +391,6 @@ workflows: - release_test: requires: - release_build - build_and_publish_docs: - jobs: - - docs_build - - docs_publish: - requires: - - docs_build - filters: - branches: - only: master nightly: jobs: - debug_build diff --git a/sphinx_doc/LICENSE b/sphinx_doc/LICENSE deleted file mode 100644 index 62da4936b3b..00000000000 --- a/sphinx_doc/LICENSE +++ /dev/null @@ -1 +0,0 @@ -Apache 2.0 diff --git a/sphinx_doc/Makefile b/sphinx_doc/Makefile deleted file mode 100644 index 3ffb456a7cf..00000000000 --- a/sphinx_doc/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -ifeq ($(VERBOSE),1) - Q = -else - Q = @ -endif - -# You can set these variables from the command line. -SPHINXOPTS ?= -q -SPHINXBUILD = sphinx-build -SPHINXPROJ = "Navigation 2 Documentation" -SOURCEDIR = . -BUILDDIR = _build - -DOC_TAG ?= development -RELEASE ?= latest -PUBLISHDIR = /tmp/navigation2 - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - @echo "" - @echo "make publish" - @echo " publish generated html to thesofproject.github.io site:" - @echo " specify RELEASE=name to publish as a tagged release version" - @echo " and placed in a version subfolder. Requires repo merge permission." - -.PHONY: help Makefile - -# Generate the doxygen xml (for Sphinx) and copy the doxygen html to the -# api folder for publishing along with the Sphinx-generated API docs. - -html: - $(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O) - -# Remove generated content (Sphinx and doxygen) - -clean: - rm -fr $(BUILDDIR) - -# Copy material over to the GitHub pages staging repo -# along with a README - -publish: - git clone --reference .. git@github.com:ros-planning/navigation2.git $(PUBLISHDIR) - cd $(PUBLISHDIR) && \ - git checkout gh-pages && \ - git config user.email "navigation2-ci@circleci.com" && \ - git config user.name "navigation2-ci" - rm -fr $(PUBLISHDIR)/* - cp -r $(BUILDDIR)/html/* $(PUBLISHDIR) - cp scripts/.nojekyll $(PUBLISHDIR)/.nojekyll - cd $(PUBLISHDIR) && \ - git add -A && \ - git diff-index --quiet HEAD || \ - (git commit -s -m "[skip ci] publish $(RELEASE)" && git push origin) - - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile doxy - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/sphinx_doc/README.md b/sphinx_doc/README.md deleted file mode 100644 index ff7c1c80994..00000000000 --- a/sphinx_doc/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Navigation2 Documentation - -This folder holds the source and configuration files used to generate the -[Navigation2 documentation](https://ros-planning.github.io/navigation2/) web site. - -Learn how to setup and generate documentation by reading the [howtos](https://ros-planning.github.io/navigation2/howtos/index.html). diff --git a/sphinx_doc/_themes/otc_tcs_sphinx_theme/.gitignore b/sphinx_doc/_themes/otc_tcs_sphinx_theme/.gitignore deleted file mode 100644 index bee8a64b79a..00000000000 --- a/sphinx_doc/_themes/otc_tcs_sphinx_theme/.gitignore +++ /dev/null @@ -1 +0,0 @@ -__pycache__ diff --git a/sphinx_doc/_themes/otc_tcs_sphinx_theme/layout.html b/sphinx_doc/_themes/otc_tcs_sphinx_theme/layout.html deleted file mode 100644 index 1bdd7ce4602..00000000000 --- a/sphinx_doc/_themes/otc_tcs_sphinx_theme/layout.html +++ /dev/null @@ -1,14 +0,0 @@ -{% extends "sphinx_rtd_theme/layout.html" %} - -{% block extrahead %} - - - -{% endblock %} - - -{% block footer %} - - - -{% endblock %} diff --git a/sphinx_doc/_themes/otc_tcs_sphinx_theme/readme.rst b/sphinx_doc/_themes/otc_tcs_sphinx_theme/readme.rst deleted file mode 100644 index 7f5f284f281..00000000000 --- a/sphinx_doc/_themes/otc_tcs_sphinx_theme/readme.rst +++ /dev/null @@ -1,23 +0,0 @@ -OTC-TCS Sphinx Theme -#################### - -Built on top of the popular Read the Docs Sphinx theme, this theme -has a few small formatting/color improvements and implements collapsible -sections. It is in active development in order to support OTC and other -Intel organizations to publish high quality, consistent documentation -for open source projects. - -How to use it -************* - -#. Download or clone the repository -#. Create a ``_themes`` directory in main directory of your sphinx - documentation -#. Install sphinx_rtd_theme using pip: ``pip3 install sphinx_rtd_theme`` -#. copy ``otc_tcs_sphinx_theme`` directory into the new ``_themes`` directory -#. Add the following to your ``conf.py``: - - .. code-block:: python - - html_theme = 'otc_tcs_sphinx_theme' - html_theme_path = ['_themes'] diff --git a/sphinx_doc/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/sphinx_doc/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css deleted file mode 100644 index 02d5051b2d1..00000000000 --- a/sphinx_doc/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css +++ /dev/null @@ -1,172 +0,0 @@ -/* -- Extra CSS styles for content (RTD theme) ----------------------- */ - -/* make the page width fill the window */ -.wy-nav-content { - max-width: 1080px; -} - -/* increase the size of the side bar from 300px default to 320px */ -.wy-nav-side { - width: 320px; -} - -.wy-side-scroll { - width: 340px; -} - -.wy-side-nav-search { - width: 320px; -} - -.wy-menu-vertical { - width: 320px; -} - -/* (temporarily) add an under development tagline to the bread crumb -.wy-breadcrumbs::after { - content: " (Content under development)"; - background-color: #FFFACD; - color: red; - font-weight: bold; -} -*/ - -/* code block highlight color in rtd changed to lime green, no no no */ - -.rst-content tt.literal, .rst-content code.literal, .highlight { - background: #f0f0f0; -} -.rst-content tt.literal, .rst-content code.literal { - color: #000000; -} - -/* Make the version number more visible */ -.wy-side-nav-search>div.version { - color: rgba(255,255,255,1); -} - -/* squish the space between a paragraph before a list */ -div > p + ul, div > p + ol { - margin-top: -20px; -} - -/* add some space before the figure caption */ -p.caption { - border-top: 1px solid; - margin-top: 1em; -} - -/* add a colon after the figure/table number (before the caption) */ -span.caption-number::after { - content: ": "; -} - -p.extrafooter { - text-align: right; - margin-top: -36px; -} - -table.align-center { - display: table !important; -} - - -.code-block-caption { - color: #000; - font: italic 85%/1 arial,sans-serif; - padding: 1em 0; - text-align: center; -} - -/* make .. hlist:: tables fill the page */ -table.hlist { - width: 95% !important; -} - -/* override rtd theme white-space no-wrap in table heading and content */ -th,td { - white-space: normal !important; -} - -/* tweak for doxygen-generated API headings (for RTD theme) */ -.rst-content dl.group>dt, .rst-content dl.group>dd>p { - display:none !important; -} -.rst-content dl.group { - margin: 0 0 12px 0px; -} -.rst-content dl.group>dd { - margin-left: 0 !important; -} -.rst-content p.breathe-sectiondef-title { - text-decoration: underline; /* for API sub-headings */ - font-size: 1.25rem; - font-weight: bold; - margin-bottom: 12px; -} - -.rst-content div.breathe-sectiondef { - padding-left: 0 !important; -} - -.clps1 { - font-size: 175%; -} - -.clps2 { - font-size: 150%; -} - -.clps3 { - font-size: 125%; -} - -.clps4 { - font-size: 115%; -} - -.clps5 { - font-size: 110%; -} - -.clps6 { - font-size: 100%; -} - -.collapsible { - margin-left: -10px; - background-color: #f1f1f1; - cursor: pointer; - padding: 18px 18px 18px 10px; - width: 100%; - border: none; - text-align: left; - outline: none; - font-weight: 700; - font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif; -} - -.collapsible:hover { - background-color: #d8d8d8; -} - -.collapsible:after { - content: '\002B'; - font-weight: bold; - float: right; - margin-left: 5px; -} - -.active:after { - content: "\2212"; -} - -.content-collapse { - overflow: hidden; - transition: max-height 0.2s ease-out; -} - -.header__menu_list li { - display: inline; - margin-left: 20px; -} \ No newline at end of file diff --git a/sphinx_doc/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js b/sphinx_doc/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js deleted file mode 100644 index 9064b9f7743..00000000000 --- a/sphinx_doc/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js +++ /dev/null @@ -1,50 +0,0 @@ -var i; -var contents = document.getElementsByClassName("content-collapse section"); - -for (i = 0; i < contents.length; i++) { - - //Make sure the "content-collapse section" class is occurring in
- if (contents[i].tagName.toLowerCase() == 'div') { - var element = contents[i].children[0]; - var element_type = element.tagName.toLowerCase(); - var span_id; - var spanElement; - - //if the next element is a span grab the id and skip to the header - if (element_type == 'span') { - span_id = element.id; - element.id = ""; - element = contents[i].children[1]; - element_type = element.tagName.toLowerCase(); - } - - var btn = document.createElement("BUTTON"); - //If it is a header capture which level and pass on to button - if (element_type.length == 2 && element_type[0] == 'h') { - var newClass = 'clps' + element_type[1]; - //collapses the section by default only if javascript is working - contents[i].style.maxHeight = 0; - //Build the button and define behavior - btn.className += " " + newClass; - btn.innerHTML = element.innerHTML; - btn.className += " collapsible"; - btn.id = span_id; - btn.addEventListener("click", function() { - this.classList.toggle("active"); - var content = this.nextElementSibling; - if (content.style.maxHeight != "0px"){ - content.style.maxHeight = 0; - } else { - content.style.maxHeight = content.scrollHeight + "px"; - } - }); - - //Add the button to the page and remove the header - contents[i].parentNode.insertBefore(btn, contents[i]); - contents[i].removeChild(element); - }else{ - //reset span id if it isn't followed by Hx element - spanElement.id = span_id; - } - } -} \ No newline at end of file diff --git a/sphinx_doc/_themes/otc_tcs_sphinx_theme/theme.conf b/sphinx_doc/_themes/otc_tcs_sphinx_theme/theme.conf deleted file mode 100644 index fc97c5522da..00000000000 --- a/sphinx_doc/_themes/otc_tcs_sphinx_theme/theme.conf +++ /dev/null @@ -1,2 +0,0 @@ -[theme] -inherit = sphinx_rtd_theme diff --git a/sphinx_doc/about/images/coming_soon.jpeg b/sphinx_doc/about/images/coming_soon.jpeg deleted file mode 100644 index 3fe5980c233..00000000000 Binary files a/sphinx_doc/about/images/coming_soon.jpeg and /dev/null differ diff --git a/sphinx_doc/about/images/move_base_compare_2.png b/sphinx_doc/about/images/move_base_compare_2.png deleted file mode 100644 index 5b1a31cec3a..00000000000 Binary files a/sphinx_doc/about/images/move_base_compare_2.png and /dev/null differ diff --git a/sphinx_doc/about/images/rb1.png b/sphinx_doc/about/images/rb1.png deleted file mode 100644 index f04040137bb..00000000000 Binary files a/sphinx_doc/about/images/rb1.png and /dev/null differ diff --git a/sphinx_doc/about/images/rover.png b/sphinx_doc/about/images/rover.png deleted file mode 100644 index 416fa6889ea..00000000000 Binary files a/sphinx_doc/about/images/rover.png and /dev/null differ diff --git a/sphinx_doc/about/images/tb2.png b/sphinx_doc/about/images/tb2.png deleted file mode 100644 index c0d4138c1c3..00000000000 Binary files a/sphinx_doc/about/images/tb2.png and /dev/null differ diff --git a/sphinx_doc/about/images/tb3.png b/sphinx_doc/about/images/tb3.png deleted file mode 100644 index 05811eea596..00000000000 Binary files a/sphinx_doc/about/images/tb3.png and /dev/null differ diff --git a/sphinx_doc/about/images/tiago.png b/sphinx_doc/about/images/tiago.png deleted file mode 100644 index 28570cee278..00000000000 Binary files a/sphinx_doc/about/images/tiago.png and /dev/null differ diff --git a/sphinx_doc/about/images/yunji.png b/sphinx_doc/about/images/yunji.png deleted file mode 100644 index 695c5da056e..00000000000 Binary files a/sphinx_doc/about/images/yunji.png and /dev/null differ diff --git a/sphinx_doc/about/index.rst b/sphinx_doc/about/index.rst deleted file mode 100644 index 0e1420d5017..00000000000 --- a/sphinx_doc/about/index.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _about: - -About and Contact -################# - -.. toctree:: - :hidden: - - robots.rst - ros1_comparison.rst - -About -***** - -Navigation is a community effort to lower the barrier of entry of mobile robotics technology for all. -This project is one of the flagship projects along with MoveIt that acts as an applications entry point and frameworks for ROS. -Navigation in ROS2 builds on the wild success of the original Navigation Stack (Nav Stack) in ROS (1). -This project has been used by researchers, educators, and industry for over 10 years. -There are very few projects that have lasted as long or were as successful as ROS (1) Navigation. -We would like to thank David Lu!! and Mike Ferguson for their tireless over the span of a decade to keep the Nav Stack alive and well. -Without their hard work, this project would not have been able to happen. -If you're interested in a comparison between ROS1 Navigation and ROS2 Navigation, see :ref:`ros1_comparison`. -For a list of robots using Navigation2, see :ref:`robots`. - -Aslas, as time moves on, so must we. -ROS (1) had a great run and those of us that build projects using it will remember it fondly(ish). -With change comes possibilities. -Navigation2 builds on the success but redesigns the framework to be more flexible and the feedback gathered over 10 years. - -We strive to create an open community and encourage new ROS users and experts alike to collaborate. -However, that can't happen without your issues, pull requests, and support. -Navigation, like all open-source projects, is kept going by a dedicated group of developers, maintainers, users, and collaborators. -We would like to thank here our current and past contributors and maintainers. - -If you or your organization are interested in sponsoring Navigation or any work around it, please reach out to the current project lead. - -Our current leadership team includes: - -+----------------+-------------------+-----------------+--------------+ -| Name | Organization | GitHub ID | Current Role | -+================+===================+=================+==============+ -| Steve Macenski | Samsung Research | SteveMacenski_ | Project Lead | -+----------------+-------------------+-----------------+--------------+ -| Carl Delsey | Intel Corporation | crdelsey_ | Maintainer | -+----------------+-------------------+-----------------+--------------+ -| Ruffin White | UC San Diego | ruffsl_ | CI Wizard | -+----------------+-------------------+-----------------+--------------+ - -.. _SteveMacenski: https://github.com/SteveMacenski -.. _crdelsey: https://github.com/crdelsey -.. _ruffsl: https://github.com/ruffsl - -Our former leadership team includes: - -+----------------+-------------------+-----------------+---------------------+ -| Name | Organization | GitHub ID | Role | -+================+===================+=================+=====================+ -| Matt Hansen | Intel Corporation | mkhansen_ | Former Project Lead | -+----------------+-------------------+-----------------+---------------------+ -| Brian Wilcox | Intel Corporation | bpwilcox_ | Former Maintainer | -+----------------+-------------------+-----------------+---------------------+ - -.. _mkhansen: https://github.com/mkhansen-intel -.. _bpwilcox: https://github.com/bpwilcox - -Contact -******* - -If you are interested in contacting someone about Navigation, ROS2, or related projects, please email the project leader. -We intentionally make our emails easy to find. -If your inquiry relates to bugs or open-source feature requests, consider posting a ticket on our GitHub project. -If your inquiry relates to configuration support or private feature development, reach out and we may be able to connect you with -independent consultants or contractors that know this project well. diff --git a/sphinx_doc/about/robots.rst b/sphinx_doc/about/robots.rst deleted file mode 100644 index 69367e6f84b..00000000000 --- a/sphinx_doc/about/robots.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _robots: - -Robots Using -############ - -It's always helpful (and fun!) to have a list of robots using or ship with our work. -Below is a very early list of robots we have encountered using our software as examples. - -Click on the images below for a link to the drivers or navigation configurations. - -+------------------------+------------------------+------------------------+ -| |tb2| + |tb3| + |rover| | -+------------------------+------------------------+------------------------+ -| |yunji| + |RB1| + |Tiago| | -+------------------------+------------------------+------------------------+ -| |soon| + |soon| + |soon| | -+------------------------+------------------------+------------------------+ - -.. |tb2| image:: images/tb2.png - :width: 100% - :align: middle - :alt: Turtlebot2 - :target: https://github.com/kobuki-base/kobuki_ros - -.. |tb3| image:: images/tb3.png - :width: 100% - :align: middle - :alt: Turtlebot3 - :target: https://github.com/ROBOTIS-GIT/turtlebot3 - -.. |rover| image:: images/rover.png - :width: 100% - :align: middle - :alt: Rover Robotics - :target: https://github.com/RoverRobotics/openrover-ros2 - -.. |yunji| image:: images/yunji.png - :width: 100% - :align: middle - :alt: Yunji Robot - :target: https://en.yunjichina.com.cn/a/53.html - -.. |RB1| image:: images/rb1.png - :width: 100% - :align: middle - :alt: Robotnik Rb1 base - :target: https://github.com/IntelligentRoboticsLabs/marathon_ros2 - -.. |Tiago| image:: images/tiago.png - :align: middle - :height: 350px - :alt: Tiago Robot - :target: https://github.com/IntelligentRoboticsLabs/marathon_ros2 - - -.. |soon| image:: images/coming_soon.jpeg - :width: 100% - :align: middle - :alt: Coming Soon - :target: https://www.youtube.com/watch?v=oHg5SJYRHA0 diff --git a/sphinx_doc/about/ros1_comparison.rst b/sphinx_doc/about/ros1_comparison.rst deleted file mode 100644 index 363caec89c3..00000000000 --- a/sphinx_doc/about/ros1_comparison.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _ros1_comparison: - -ROS to ROS2 Navigation -###################### - -``move_base`` has been split into multiple components. -Rather than a single monolithic state machine, navigation 2 makes use of action servers and ROS2's -low-latency, reliable communication to separate ideas. A behavior tree is used to orchestrate these tasks. -This allows Navigation2 to have highly configurable navigation behavior without programming by rearranging tasks -in a behavior tree xml file. - -The *nav2_bt_navigator* replaces ``move_base`` at the top level, with an *Action* interface to complete a navigation task with a tree-based action model. -It uses *Behavior Trees* to make it possible to have more complex state machines and to add in recovery behaviors as additional *Action Servers*. -These behavior trees are configurable XMLs and we provide several starting examples. - -The planning, recovery, and controller servers are also action servers that the BT navigator can call to compute. -All 3 servers can host many plugins of many algorithms each and individually called from the navigation behavior tree for specific behaviors. -The default plugins provided are ported from ROS1, namely: DWB, NavFn, and similar recoveries such as spinning and clearing costmaps. -A new recovery for waiting a fixed duration was also added. -These servers are called from the BT navigator through their action servers to compute a result or complete a task. -The state is maintained by the BT navigator behavior tree. - -All these changes make it possible to replace any of these nodes at launch/run time with any other algorithm that implements that same interface. -See each package README.md for more details. - -.. image:: images/move_base_compare_2.png - :align: center - :width: 700px - :alt: Move Base -> Navigation2 Overview - -Note: ``nav2_simple_navigator`` no longer exists, it has been replaced by ``nav2_bt_navigator``. - -**In Summary:** - -Ported packages: - - * amcl: Ported to nav2_amcl - * map_server: Ported to nav2_map_server - * nav2_planner: Replaces global_planner, hosts ``N`` planner plugins - * nav2_controller: Replaces local_planner, hosts ``N`` controller plugins - * Navfn: Ported to nav2_navfn_planner - * DWB: Replaces DWA and ported to ROS2 under nav2_dwb_controller metapackage - * nav_core: Ported as nav2_core with updates to interfaces - * costmap_2d: Ported as nav2_costmap_2d - -New packages: - - * nav2_bt_navigator: replaces ``move_base`` state machine - * nav2_lifecycle_manager: Handles the server program lifecycles - * nav2_waypoint_follower: Can take in many waypoints to execute a complex task through - * nav2_system_tests: A set of integration tests for CI and basic tutorials in simulation - * nav2_rviz_plugins: An rviz plugin to control the Navigation2 servers, command, cancel, and navigation with - * nav2_experimental: Experimental (and incomplete) work for deep reinforement learning controllers - * navigation2_behavior_trees: wrappers for the behavior tree library to call ROS action servers diff --git a/sphinx_doc/build_instructions/build_docs/build_troubleshooting_guide.rst b/sphinx_doc/build_instructions/build_docs/build_troubleshooting_guide.rst deleted file mode 100644 index 055b76d5a5e..00000000000 --- a/sphinx_doc/build_instructions/build_docs/build_troubleshooting_guide.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _build-troubleshooting-guide: - -Build Troubleshooting Guide -********************************************** - -Common Navigation2 Dependencies Build Failures -============================================== - -* Make sure that .bashrc file has no ROS environment variables in it. Open new terminals and try to build the packages again. - -* Make sure to run rosdep for the correct ROS 2 distribution. - ``rosdep install -y -r -q --from-paths src --ignore-src --rosdistro `` - -* Make sure that the ``setup.bash`` is sourced in the ROS 2 installation or ROS 2 master build workspace, if applicable. Check if you can run talker and listener nodes. - -* Make sure that the ``setup.bash`` in ``nav2_depend_ws/install`` is sourced. - -* Check if you have the correct ROS version and distribution. ``printenv | grep -i ROS`` - -* If you see a bunch of errors on startup about ``map`` or ``odom`` frame not existing, remember to activate drivers (or gazebo for simulation) and set an initial pose in ``map`` frame. Costmap2D will block activation until a full TF tree is available. - -* Make sure you've activated the lifecycle nodes if you're not seeing transforms or servers running. - -* Search `GitHub Issues `_ - -Still can't solve it? Let us know about your issue. `Open a ticket `_. - -Reporting Issue -=============== - -- If you run into any issues when building Navigation2, you can use the search tool in the issues tab on `GitHub `_ and always feel free to `open a ticket `_. diff --git a/sphinx_doc/build_instructions/index.rst b/sphinx_doc/build_instructions/index.rst deleted file mode 100644 index 307e213f4b2..00000000000 --- a/sphinx_doc/build_instructions/index.rst +++ /dev/null @@ -1,198 +0,0 @@ -.. _build-instructions: - -Build and Install -################# - -Install -******* - -Navigation2 and its dependencies are released as binaries. -You may install it via the following to get the latest stable released version: - - ``sudo apt install ros--navigation2 ros--nav2-bringup ros--turtlebot3*`` - -Build -***** - -There are 3 ways to build Navigation2. -Building for a specific released distribution (e.g. ``eloquent``, ``foxy``), build Navigation2 on master branch using a quickstart setup script, or building master branch manually. - -.. rst-class:: content-collapse - -Build Navigation2 For Released Distribution -=========================================== - -Install ROS ------------ - -Please install ROS2 via the usual `build instructions `_ for your desired distribution. - -Build Navigation2 ------------------ - -We're going to create a new workspace, ``navigation2_ws``, clone our Navigation2 branch into it, and build. -``rosdep`` will be used to get the dependency binaries for navigation2 in your specific distribution. - -.. code:: bash - - mkdir -p ~/navigation2_ws/src - cd ~/navigation2_ws/src - git clone https://github.com/ros-planning/navigation2.git --branch -devel - cd ~/navigation2_ws - rosdep install -y -r -q --from-paths src --ignore-src --rosdistro - colcon build --symlink-install - -Note: You need to change ``--rosdistro`` to the selected ROS 2 distribution name (e.g ``eloquent``, ``foxy``). - - - -.. rst-class:: content-collapse - -Quickstart Build Master -======================= - -Steps ------ - -Install all ROS 2 dependencies from the `ROS2 Installation page `_. -Ensure there are no ROS environment variables set in your terminal or `.bashrc` file before taking the steps below.* - - -.. code:: bash - - mkdir - cd - wget https://raw.githubusercontent.com/ros-planning/navigation2/master/tools/initial_ros_setup.sh - chmod a+x initial_ros_setup.sh - ./initial_ros_setup.sh - - -**Summary of what's being done** - -The ``initial_ros_setup.sh`` script downloads three ROS workspaces and then builds them in the correct order. The three workspaces are: - -- **ROS 2 release**: This is the latest ROS 2 release as defined by the repos file found `here `_ -- **ROS 2 dependencies**: This is a set of ROS 2 packages that aren't included in the ROS 2 release yet. However, you need them to be able to build Navigation2. This also includes packages that are part of the ROS 2 release where Navigation2 uses a different version. -- **Navigation2**: This repository. - -After all the workspaces are downloaded, run the `navigation2/tools/build_all.sh` script. `build_all.sh` builds each repo in the order listed above using the `colcon build --symlink-install` command. - -Options -------- - -The `initial_ros_setup.sh` accepts the following options: - -- `--no-ros2` This skips downloading and building the ROS 2 release. Instead it uses the binary packages and ``setup.sh`` installed in ``/opt/ros/`` -- ``--download-only`` This skips the build steps - - -.. rst-class:: content-collapse - -Manually Build Master -===================== - -Build ROS 2 Master ------------------- - -.. warning:: - - When building ROS 2 from source, make sure that the `ros2.repos` file is from the `master` branch. - -Build ROS2 master using the `build instructions `_ provided in the ROS2 documentation. - - -Build Navigation2 Dependencies ------------------------------- - -Since we're not building for a released distribution, we must build the dependencies ourselves rather than using binaries. -First, source the setup.bash file in the ROS 2 build workspace. - - ``source ~/ros2_ws/install/setup.bash`` - -Next, we're going to get the ``ros2_dependencies.repos`` file from Navigation2. -Then, use ``vcs`` to clone the repos and versions in it into a workspace. - -.. code:: bash - - source ros2_ws/install/setup.bash - mkdir -p ~/nav2_depend_ws/src - cd ~/nav2_depend_ws - wget https://raw.githubusercontent.com/ros-planning/navigation2/master/tools/ros2_dependencies.repos - vcs import src < ros2_dependencies.repos - colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release - -Build Navigation2 Master ------------------------- - -Finally, now that we have ROS2 master and the necessary dependencies, we can now build Navigation2 master itself. -We'll source the ``nav2_depend_ws``, which will also source the ROS2 master build workspace packages, to build with dependencies. -The rest of this should look familiar. - -.. code:: bash - - source ~/nav2_depend_ws/install/setup.bash - mkdir -p ~/navigation2_ws/src - cd ~/navigation2_ws/src - git clone https://github.com/ros-planning/navigation2.git --branch master - cd ~/navigation2_ws - colcon build --symlink-install - -Docker -****** - - -There are 2 options for docker with Navigation2: -building a container and using the DockerHub container. - -.. rst-class:: content-collapse - -Building Docker Container -========================= - -To build an image from the Dockerfile in the navigation2 folder: -First, clone the repo to your local system (or see Building the source above) - -.. code:: bash - - sudo docker build -t nav2/latest . - -If proxies are needed: - -.. code:: bash - - sudo docker build -t nav2/latest --build-arg http_proxy=http://proxy.my.com:### --build-arg https_proxy=http://proxy.my.com:### . - -Note: You may also need to configure your docker for DNS to work. See article here for details: https://development.robinwinslow.uk/2016/06/23/fix-docker-networking-dns/ - -.. rst-class:: content-collapse - -Using DockerHub Container -========================= - -We allow for you to pull the latest docker image from the master branch at any time. As new releases and tags are made, docker containers on docker hub will be versioned as well to chose from. - -.. code:: bash - - sudo docker pull rosplanning/navigation2:latest - -!!!! - -Generate Doxygen -**************** - -Run ``doxygen`` in the root of the Navigation2 repository. -It will generate a ``/doc/*`` directory containing the documentation. -The documentation entrypoint in a browser is index.html. - -!!!! - -Help -**** - -:ref:`build-troubleshooting-guide` - - -.. toctree:: - :hidden: - - build_docs/build_troubleshooting_guide.rst diff --git a/sphinx_doc/concepts/index.rst b/sphinx_doc/concepts/index.rst deleted file mode 100644 index d132c0d4be8..00000000000 --- a/sphinx_doc/concepts/index.rst +++ /dev/null @@ -1,258 +0,0 @@ -.. _concepts: - -Navigation Concepts -################### - -This page is to help familiarize new robotists to the concepts of mobile robot navigation, in particular, with the concepts required to appreciating and working with this project. - -ROS2 -**** - -ROS2 is the core middleware used for Navigation2. If you are unfamilar with this, please visit `the ROS2 documentation `_ before continuing. - -Action Server -============= - -Just as in ROS, action servers are a common way to control long running tasks like navigation. -This stack makes more extensive use of actions, and in some cases, without an easy topic interface. -It is more important to understand action servers as a developer in ROS2. -Some simple CLI examples can be found in the `ROS2 documementation `_. - -Action servers are similar to a canonical service server. -A client will request some task to be completed, except, this task may take a long time. -An example would be moving the shovel up from a bulldozer or ask a robot to travel 10 meters to the right. - -In this situation, action servers and clients allow us to call a long-running task in another process or thread and return a future to its result. -It is permissible at this point to block until the action is complete, however, you may want to occasionally check if the action is complete and continue to process work in the client thread. -Since it is long-running, action servers will also provide feedback to their clients. -This feedback can be anything and is defined in the ROS ``.action`` along with the request and result types. -In the bulldozer example, a request may be an angle, a feedback may be the angle remaining to be moved, and the result is a success or fail boolean with the end angle. -In the navigation example, a request may be a position, a feedback may be the time its been navigating for and the distance to the goal, and the result a boolean for success. - -Feedback and results can be gathered synchronously by registering callbacks with the action client. -They may also be gathered by asychronously requesting information from the shared future objects. -Both require spinning the client node to process callback groups. - -Action servers are used in this stack to communicate with the highest level BT navigator through a ``NavigateToPose`` action message. -They are also used for the BT navigator to communicate with the subsequent smaller action servers to compute plans, control efforts, and recoveries. -Each will have their own unique ``.action`` type in ``nav2_msgs`` for interacting with the servers. - -Lifecycle Nodes -=============== - -Lifecycle (or Managed, more correctly) nodes are unique to ROS2. -More information can be `found here `_. -They are nodes that contain state machine transitions for bringup and teardown of ROS2 servers. -This helps in determinstic behavior of ROS systems in startup and shutdown. -It also helps users structure their programs in reasonable ways for commercial uses and debugging. - -When a node is started, it is in the unconfigured state, only processing the node's constructor which should **not** contain any ROS networking setup or parameter reading. -By the launch system, or the supplied lifecycle manager, the nodes need to be transitioned to inactive by configuring. -After, it is possible to activate the node by transitioning through the activing stage. - -This state will allow the node to process information and be fully setup to run. -The configuration stage, triggering the ``on_configure()`` method, will setup all parameters, ROS networking interfaces, and for safety systems, all dynamically allocated memory. -The activation stage, triggering the ``on_activate()`` method, will active the ROS networking interfaces and set any states in the program to start processing information. - -To shutdown, we transition into deactivating, cleaning up, shutting down and end in the finalized state. -The networking interfaces are deactivated and stop processing, deallocate memory, exit cleanly, in those stages, respectively. - -The lifecycle node framework is used extensively through out this project and all servers utilize it. -It is best convention for all ROS systems to use lifecycle nodes if it is possible. - -Behavior Trees -************** - -Behavior trees (BT) are becoming increasingly common in complex robotics tasks. -They are a tree structure of tasks to be completed. -It creates a more scalable and human-understandable framework for defining multi-step or many state applications. -This is opposed to a finite state machine (FSM) which may then have dozens or states and hundreds of transitions. -An example would be a soccer playing robot. -Embedding the logic of soccer game play into a FSM would be challenging and error prone with many possible states and rules. -Additionally, modeling choices like to shoot at the goal from the left, right, or center, is particularly unclear. -With a BT, basic primitives like "kick" "walk" "go to ball" can be created and reused for many behaviors. -More information can be found `in this book `_. -I **strongly** recommend reading chapters 1-3 to get a good understanding of the nomenclature and workflow. -It should only take about 30 minutes. - -For this project, we use `BehaviorTree CPP V3 `_ as the behavior tree library. -We create node plugins which can be constructed into a tree, inside the ``BT Navigato``. -The node plugins are loaded into the BT and when the XML file of the tree is parsed, the registered names are associated. -At this point, we can march through the behavior tree to navigate. - -One reason this library is used is its ability to load subtrees. This means that the Navigation2 behavior tree can be loaded into another higher-level BT to use this project as node plugin. -An example would be in soccer play, using the Navigation2 behavior tree as the "go to ball" node with a ball detection as part of a larger task. -Additionally, we supply a ``NavigateToPoseAction`` plugin for BT so the Navigation2 stack can be called from a client application through the usual action interface. - - -Navigation Servers -****************** - -Planners and controllers are at the heart of a navigation task. -Recoveries are used to get the robot out of a bad situation or attempt to deal with various forms of issues to make the system fault-tolerant. -In this section, the general concepts around them and their uses in this project are analyzed. - -Planner, Controller, and Recovery Servers -========================================= - -Three of the action servers in this project are the planner, recovery, and controller servers. -These action servers are used to host a map of algorithm plugins to complete various tasks. -They also host the environmental representation used by the algorithm plugins to compute their outputs. - -The planner and controller servers will be configured at runtime with the names (aliases) and types of algorithms to use. -These types are the pluginlib names that have been registered and the names are the aliases for the task. -An example would be the DWB controller used with name ``FollowPath``, as it follows a reference path. -In this case, then all parameters for DWB would be placed in that namespace, e.g. ``FollowPath.``. - -These two servers then expose an action interface corresponding to its task. -When the behavior tree ticks the corresponding BT node, it will call the action server to process its task. -The action server callback inside the server will call the chosen algorithm by its name (e.g. ``FollowPath``) that maps to a specific algorithm. -This allows a user to abstract the algorithm used in the behavior tree to classes of algorithms. -For instance, you can have ``N`` plugin controllers to follow paths, dock with charger, avoid dynamic obstacles, or interface with a tool. -Having all of these plugins in the same server allows the user to make use of a single environmental representation object, which is costly to duplicate. - -For the recovery server, each of the recoveries also contains their own name, however, each plugin will also expose its own special action server. -This is done because of the wide variety of recovery actions that may be created cannot have a single simple interface to share. -The recovery server also contains a costmap subscriber to the local costmap, receiving real-time updates from the controller server, to compute its tasks. -We do this to avoid having multiple instances of the local costmap which are computationally expensive to duplicate. - -Alternatively, since the BT nodes are trivial plugins calling an action, new BT nodes can be created to call other action servers with other action types. -It is advisable to use the provided servers if possible at all times. -If, due to the plugin or action interfaces, a new server is needed, that can be sustained with the framework. -The new server should use the new type and plugin interface, similar to the provided servers. -A new BT node plugin will need to be created to call the new action server -- however no forking or modification is required in the navigation2 repo itself by making extensive use of servers and plugins. - -If you find that you require a new interface to the pluginlib definition or action type, please file a ticket and see if we can rectify that in the same interfaces. - -Planners -======== - -The task of a planner is to compute a path to complete some objective function. -The path can also be known as a route, depending on the nomenclature and algorithm selected. -Two canonical examples are computing a plan to a goal (e.g. from current position to a goal) or complete coverage (e.g. plan to cover all free space). -The planner will have access to a global environmental representation and sensor data buffered into it. -Planners can be written to: - -- Compute shortest path -- Compute complete coverage path -- Compute paths along sparse or predefined routes - -The general task in Navigation2 for the planner is to compute a valid, and potentially optimal, path from the current pose to a goal pose. -However, many classes of plans and routes exist which are supported. - -Controllers -=========== - -Controllers, also known as local planners in ROS1, are the way we follow the globally computed path or complete a local task. -The controller will have access to a local environment representation to attempt to compute feasible control efforts for the base to follow. -Many controller will project the robot forward in space and compute a locally feasible path at each update iteration. -Controllers can be written to: - -- Follow a path -- Dock with a charging station using detectors in the odometric frame -- Board an elevator -- Interface with a tool - -The general task in Navigation2 for a controller is to compute a valid control effort to follow the global plan. -However, many classes of controllers and local planners exist. -It is the goal of this project that all controller algorithms can be plugins in this server for common research and industrial tasks. - -Recoveries -========== - -Recoveries are a mainstay of fault-tolerant systems. -The goal of recoveries are to deal with unknown or failure conditions of the system and autonomously handle them. -Examples may include faults in the perception system resulting in the environmental representation being full of fake obstacles. -The clear costmap recovery would then be triggered to allow the robot to move. - -Another example would be if the robot was stuck due to dynamic obstacles or poor control. -Backing up or spinning in place, if permissible, allow the robot to move from a poor location into free space it may navigate successfully. - -Finally, in the case of a total failure, a recovery may be implemented to call an operators attention for help. -This can be done with email, SMS, Slack, Matrix, etc. - - -State Estimation -**************** - -Within the navigation project, there are 2 major transformations that need to be provided, according to community standards. -The ``map`` to ``odom`` transform is provided by a positioning system (localization, mapping, SLAM) and ``odom`` to ``base_link`` by an odometry system. - -.. note:: - - There is **no** requirement on using a LIDAR on your robot to use the navigation system. There is no requirement to use lidar-based collision avoidance, - localization, or slam. However, we do provide instructions and support tried and true implementations of these things using lidars. - You can be equally as successful using a vision or depth based positioning system and using other sensors for collision avoidance. - The only requirement is that you follow the standards below with your choice of implementation. - -Standards -========= - -`REP 105 `_ defines the frames and conventions required for navigation and the larger ROS ecosystem. -These conventions should be followed at all times to make use of the rich positioning, odometry, and slam projects available in the community. - -In a nutshell, REP-105 says that you must, at minimum, build a TF tree that contains a full ``map`` -> ``odom`` -> ``base_link`` -> ``[sensor frames]`` for your robot. -TF2 are the time-variant transformation library in ROS2 we use to represent and obtain time synchronized transformations. -It is the job of the global positioning system (GPS, SLAM, Motion Capture) to, at minimum, provide the ``map`` -> ``odom`` transformation. -It is then the role of the odometry system to provide the ``odom`` -> ``base_link`` transformation. -The remainder of the transformations relative to ``base_link`` should be static and defined in your `URDF `_. - -Global Positioning: Localization and SLAM -========================================= - -It is the job of the global positioning system (GPS, SLAM, Motion Capture) to, at minimum, provide the ``map`` -> ``odom`` transformation. -We provide ``amcl`` which is an Adaptive Monte-Carlo Localization technique based on a particle filter for localization of a static map. -We also provide SLAM Toolbox as the default SLAM algorithm for use to position and generate a static map. - -These methods may also produce other output including position topics, maps, or other metadata, but they must provide that transformation to be valid. -Multiple positioning methods can be fused together using robot localization, discussed more below. - - -Odometry -======== - -It is the role of the odometry system to provide the ``odom`` -> ``base_link`` transformation. -Odometry can come from many sources including LIDAR, RADAR, wheel encoders, VIO, and IMUs. -The goal of the odometry is to provide a smooth and continuous local frame based on robot motion. -The global positioning system will update the transformation relative to the global frame to account for the odometric drift. - -`Robot Localization `_ is typically used for this fusion. -It will take in ``N`` sensors of various types and provide a continuous and smooth odometry to TF and to a topic. -A typical mobile robotics setup may have odometry from wheel encoders, IMUs, and vision fused in this manor. - -The smooth output can be used then for dead-reckoning for precise motion and updating the position of the robot accurately between global position updates. - - - -Environmental Representation -**************************** - -The environmental representation is the way the robot perceives its environment. -It also acts as the central localization for various algorithms and data sources to combine their information into a single space. -This space is then used by the controllers, planners, and recoveries to compute their tasks safely and efficiently. - -Costmaps and Layers -=================== - -The current environmental representation is a costmap. -A costmap is a regular 2D grid of cells containing a cost from unknown, free, occupied, or inflated cost. -This costmap is then searched to compute a global plan or sampled to compute local control efforts. - -Various costmap layers are implemented as pluginlib plugins to buffer information into the costmap. -This includes information from LIDAR, RADAR, sonar, depth, images, etc. -It may be wise to process sensor data before inputting it into the costmap layer, but that is up to the developer. - -Costmap layers can be created to detect and track obstacles in the scene for collision avoidance using camera or depth sensors. -Additionally, layers can be created to algorithmically change the underlying costmap based on some rule or heuristic. -Finally, they may be used to buffer live data into the 2D or 3D world for binary obstacle marking. - -Other Forms -=========== - -Various other forms of environmental representations exist. -These include: - -- gradient maps, which are similar to costmaps but represent surface gradients to check traversibility over -- 3D costmaps, which represent the space in 3D, but then also requires 3D planning and collision checking -- Mesh maps, which are similar to gradient maps but with surface meshes at many angles -- "Vector space", taking in sensor information and using machine learning to detect individual items and locations to track rather than buffering discrete points. diff --git a/sphinx_doc/conf.py b/sphinx_doc/conf.py deleted file mode 100644 index d907dc86159..00000000000 --- a/sphinx_doc/conf.py +++ /dev/null @@ -1,193 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Project SOF documentation build configuration file, created by -# sphinx-quickstart on Wed Jan 10 20:51:29 2018. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys -sys.path.insert(0, os.path.abspath('.')) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', 'sphinx.ext.extlinks'] - -graphviz_output_format='png' -graphviz_dot_args=[ - '-Nfontname="verdana"', - '-Gfontname="verdana"', - '-Efontname="verdana"'] - -plantuml = 'java -jar ' + os.path.join(os.path.abspath('.'), 'scripts/plantuml.jar') -plantuml_output_format = 'png' - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Navigation 2' -copyright = u'2020' -author = u'Various' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. - -version = release = "1.0.0" - -# -# The short X.Y version. -# version = u'0.1' -# The full version, including alpha/beta/rc tags. -# release = u'0.1' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build','_themes','scripts' ] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -try: - import sphinx_rtd_theme -except ImportError: - html_theme = 'alabaster' - # This is required for the alabaster theme - # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars - html_sidebars = { - '**': [ - 'relations.html', # needs 'show_related': True theme option to display - 'searchbox.html', - ] - } - sys.stderr.write('Warning: sphinx_rtd_theme missing. Use pip to install it.\n') -else: - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - html_theme_options = { - 'canonical_url': '', - 'analytics_id': '', - 'logo_only': False, - 'display_version': True, - 'prev_next_buttons_location': 'None', - # Toc options - 'collapse_navigation': False, - 'sticky_navigation': True, - 'navigation_depth': 4, - } - -html_theme_path = ['_themes'] -html_theme = 'otc_tcs_sphinx_theme' - -# Here's where we (manually) list the document versions maintained on -# the published doc website. On a daily basis we publish to the -# /latest folder but when releases are made, we publish to a / -# folder (specified via RELEASE=name on the make command). - -if tags.has('release'): - current_version = version -else: - version = current_version = "latest" - -html_context = { - 'current_version': current_version, - 'versions': ( ("latest", "/latest/"), -# ("0.1-rc4", "/0.1-rc4/"), - ) - } - - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -html_logo = 'images/logo_white_200w.png' -html_favicon = 'images/favicon-48x48.png' - -numfig = True -#numfig_secnum_depth = (2) -numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Code Block %s'} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -html_show_sphinx = False - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = False - -# If not '', a 'Last updated on:' timestamp is inserted at every page -# bottom, -# using the given strftime format (ei %b %d, %Y). -html_last_updated_fmt = None - -# -- Options for HTMLHelp output ------------------------------------------ - - -rst_epilog = """ -.. include:: /substitutions.txt -""" - - -breathe_projects = { - "SOF Project" : "doxygen/xml", -} -breathe_default_project = "SOF Project" -breathe_default_members = ('members', 'undoc-members', 'content-only') - -extlinks = {'projectfile': - ('https://github.com/ros-planning/navigation2/blob/master/%s', 'filepath ')} diff --git a/sphinx_doc/configuration/configuring-the-controller.rst b/sphinx_doc/configuration/configuring-the-controller.rst deleted file mode 100644 index 3f90309c1bc..00000000000 --- a/sphinx_doc/configuration/configuring-the-controller.rst +++ /dev/null @@ -1,388 +0,0 @@ -.. _configuring_the_controller: - -Configuring The Controller -########################## - -Controller Server -================= - -The controller server responds to FollowPath action requests. It runs a loop -that continuously computes new command velocities until the goal is reached, -cancelled or an error occurs. It computes command velocities by using the -services of a controller plugin. The parameters in this section are set on the -controller_server node - -Parameters -********** - -:controller_frequency: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 20.0 | - +----------------+----------------------------------------------------------------------------+ - |**units** | Hz | - +----------------+----------------------------------------------------------------------------+ - |**description** | This parameter controls how often a new command velocity is | - | | published. It also controls how often the controller checks if the goal is| - | | reached. Faster robots may need to increase this value. Slower robots can | - | | use a lower value. | - +----------------+----------------------------------------------------------------------------+ - -:controller_plugin_ids: - +----------------+----------------------------------------------------------------------------+ - |**type** | vector | - +----------------+----------------------------------------------------------------------------+ - |**default** | "FollowPath" | - +----------------+----------------------------------------------------------------------------+ - |**description** | The name of each controller plugin to be loaded into the controller server.| - | | Multiple controller plugins can be loaded simultaneously so they can share | - | | a costmap instance. The name assigned to the plugin using this parameter | - | | determines how it should be addressed in the *controller_id* field of the | - | | FollowPath action request. | - +----------------+----------------------------------------------------------------------------+ - - -:controller_plugin_types: - +----------------+----------------------------------------------------------------------------+ - |**type** | vector | - +----------------+----------------------------------------------------------------------------+ - |**default** | "dwb_core::DWBLocalPlanner" | - +----------------+----------------------------------------------------------------------------+ - |**description** | The data type of each controller plugin to be loaded into the controller | - | | server. This is used by pluginlib to dyanmically load the object. This | - | | needs to be a class derived from nav2_core::LocalPlanner. The default | - | | controller is an instance of DWB whose parameters are here | - | | `DWB Controller`_ | - +----------------+----------------------------------------------------------------------------+ - -Progress Checker -================= - -This is a component of the controller server that verifies that the robot has moved sufficiently. -If the robot fails to make progress, the controller fails and triggers recoveries in the -behavior tree. The parameters in this section are set on the controller_server node. - -Parameters -********** - -:required_movement_radius: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 0.5 | - +----------------+----------------------------------------------------------------------------+ - |**units** | m | - +----------------+----------------------------------------------------------------------------+ - |**description** | The absolute distance the robot must move from the previous checkpoint. If | - | | the robot doesn't move this far in *movement_time_allowance* seconds, an | - | | error is thrown. Once the robot moves this distance the time is reset | - +----------------+----------------------------------------------------------------------------+ - -:movement_time_allowance: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 10.0 | - +----------------+----------------------------------------------------------------------------+ - |**units** | s | - +----------------+----------------------------------------------------------------------------+ - |**description** | Controls how much time the robot has time to show progress. If the robot | - | | fails to move more than *required_movement_radius* meters in this time, an | - | | error is thrown. For slow robots, this time should be extended. Reducing | - | | this time will cause the robot to recover more quickly if it is stuck, | - | | but too little time doesn't give the robot enough time to manoeuver in | - | | dyanamic enviroments | - +----------------+----------------------------------------------------------------------------+ - -DWB Controller -============== - -The DWB controller is the default controller in |PN|. It is a fork of `David Lu's -controller `_ -modified for ROS 2. - -.. warning:: - - The parameters below are not properly scoped. The exact parameter names are - likely to change in the near future - -Parameters -********** - -:trajectory_generator_name: - +----------------+----------------------------------------------------------------------------+ - |**type** | string | - +----------------+----------------------------------------------------------------------------+ - |**default** | "dwb_plugins::StandardTrajectoryGenerator" | - +----------------+----------------------------------------------------------------------------+ - |**description** | This is the name of the pluginlib class to use as the trajectory generator.| - | | The trajectory generator projects a sample of possible trajectories the | - | | robot can follow from its current pose and velocity. These trajectories | - | | are then provided to the critics to score. | - | | | - | | You can create a custom trajectory generator by inheriting from the | - | | dwb_core::TrajectoryGenerator base class | - | | | - | | The trajectory generators provided with |PN| are: | - | | | - | | * dwb_plugins::StandardTrajectoryGenerator | - | | * dwb_plugins::LimitedAccelGenerator | - +----------------+----------------------------------------------------------------------------+ - -:critics: - +----------------+----------------------------------------------------------------------------+ - |**type** | vector | - +----------------+----------------------------------------------------------------------------+ - |**default** | ["RotateToGoal", "Oscillation", "ObstacleFootprint", "GoalAlign", | - | | "PathAlign", "PathDist", "GoalDist"] | - +----------------+----------------------------------------------------------------------------+ - |**description** | This is a list of critic plugins that will evaluate the trajectories | - | | generated by the trajectory generator. Each critic evaluates the | - | | trajectories according to its own criteria. The scores from each critic | - | | will be combined, and the trajectory with the best score will be chosen. By| - | | weighting the different critics appropriately, the quality of the chosen | - | | trajectory can be modified. | - | | | - | | You can create a custom critic by inheriting from the | - | | dwb_core::TrajectoryCritic base class | - | | | - | | The critics provided with |PN| are: | - | | | - | | * dwb_critics::PreferForwardCritic | - | | * dwb_critics::GoalDistCritic | - | | * dwb_critics::PathAlignCritic | - | | * dwb_critics::GoalAlignCritic | - | | * dwb_critics::PathDistCritic | - | | * dwb_critics::OscillationCritic | - | | * dwb_critics::RotateToGoalCritic | - | | * dwb_critics::BaseObstacleCritic | - | | * dwb_critics::ObstacleFootprintCritic | - | | * dwb_critics::TwirlingCritic | - +----------------+----------------------------------------------------------------------------+ - -:goal_checker_name: - +----------------+----------------------------------------------------------------------------+ - |**type** | string | - +----------------+----------------------------------------------------------------------------+ - |**default** | "dwb_plugins::SimpleGoalChecker" | - +----------------+----------------------------------------------------------------------------+ - |**description** | This is the plugin that evaluates the current pose and velocity to | - | | determine if the goal has been reached | - | | | - | | You can create a custom goal checker by inheriting from the | - | | nav2_core::GoalChecker base class | - | | | - | | The critics provided with |PN| are: | - | | | - | | * dwb_plugins::SimpleGoalChecker | - | | * dwb_plugins::StoppedGoalChecker | - +----------------+----------------------------------------------------------------------------+ - -.. rst-class:: content-collapse - -Additional Parameters -********************* - -:prune_plan: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, the path evaluated by the controller is trimmed to only include | - | | points within *prune_distance* of the current robot pose. This improves CPU| - | | performance, and also has the effect of making the Goal* critics aim for a | - | | more nearby goal | - +----------------+----------------------------------------------------------------------------+ - -:prune_distance: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 1.0 | - +----------------+----------------------------------------------------------------------------+ - |**units** | m | - +----------------+----------------------------------------------------------------------------+ - |**description** | If *prune_plan* is true, all points in the path that are further away from | - | | the robot than this distance are discarded. | - | | This is re-evaluated each time the controller is run, so the points are not| - | | permanently discared. | - +----------------+----------------------------------------------------------------------------+ - -:transform_tolerance: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 0.1 | - +----------------+----------------------------------------------------------------------------+ - |**units** | s | - +----------------+----------------------------------------------------------------------------+ - |**description** | When determining the current robot pose, if the transform data is older | - | | than this, an error is returned | - +----------------+----------------------------------------------------------------------------+ - -Debug Parameters -================ - -:debug_trajectory_details: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | false | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true and if all trajectories are rejected by the critics, DWB will print| - | | statistics on the console indicating which critics rejected the | - | | trajectories and for what reason. | - +----------------+----------------------------------------------------------------------------+ - -:publish_cost_grid_pc: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | false | - +----------------+----------------------------------------------------------------------------+ - |**description** | Certain trajectory critics compute scores based on location in the costmap.| - | | For those critics, if this parameter is true, DWB will publish a PointCloud| - | | on the **cost_cloud** topic showing that critic's score for each cell. This| - | | can be visualized in RViz. | - | | | - | | The standard critics provided with |PN| that provide this capability are: | - | | | - | | * dwb_critics::GoalDistCritic | - | | * dwb_critics::PathAlignCritic | - | | * dwb_critics::GoalAlignCritic | - | | * dwb_critics::PathDistCritic | - | | * dwb_critics::BaseObstacleCritic | - | | * dwb_critics::ObstacleFootprintCritic | - +----------------+----------------------------------------------------------------------------+ - -:publish_evaluation: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, publishes all evaluated trajectories and the scores each critic | - | | assigned them. This is the most detailed information on what is going on in| - | | DWB, but can be hard to visualize. The data is published on the | - | | **evaluation** topic | - +----------------+----------------------------------------------------------------------------+ - -:publish_global_plan: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, publishes the path recieved by the controller. This is published | - | | on the **received_global_plan** topic and can be visualized in RViz | - +----------------+----------------------------------------------------------------------------+ - - -:publish_local_plan: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, published the chosen trajectory on the **local_plan** topic. This | - | | can be visualized in RViz. | - +----------------+----------------------------------------------------------------------------+ - - -:publish_trajectories: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, all evaluated trajectories are published on the **marker** topic. | - | | The trajectories can be visualized in RViz and are color coded. Black means| - | | a critic rejected that particular trajectory as invalid. The remaining | - | | trajectories are scaled from red to green, with the best trajectories being| - | | the most green and the worst being the most red. | - +----------------+----------------------------------------------------------------------------+ - - | | | - -:publish_transformed_plan: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, publishes the received path after it has been transformed into the| - | | local frame of reference. This is published on the | - | | **transformed_global_plan** topic and can be visualized in RViz | - +----------------+----------------------------------------------------------------------------+ - -:short_circuit_trajectory_evaluation: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | This parameter allows process to move forward if trajectories score by | - | | critics is just equal to the best score. As after this point it would be | - | | pointless to increse the score as it will always be more than best score. | - +----------------+----------------------------------------------------------------------------+ - -:trans_stopped_velocity: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 0.25 | - +----------------+----------------------------------------------------------------------------+ - |**description** | Minimal speed to check if the robot traj is if rotating near the goal. | - +----------------+----------------------------------------------------------------------------+ - -:slowing_factor: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | 5.0 | - +----------------+----------------------------------------------------------------------------+ - |**description** | If true, publishes the received path after it has been transformed into the| - | | local frame of reference. This is published on the | - | | **transformed_global_plan** topic and can be visualized in RViz | - +----------------+----------------------------------------------------------------------------+ - -:lookahead_time: - +----------------+----------------------------------------------------------------------------+ - |**type** | double | - +----------------+----------------------------------------------------------------------------+ - |**default** | -1.0 | - +----------------+----------------------------------------------------------------------------+ - |**description** | If the `lookahead_time` parameter is negative, the pose evaluated will be | - | | the last pose in the trajectory, which is the same as DWA's behavior. This | - | | is the default. Otherwise, a new pose will be projected using the | - | | dwb_local_planner::projectPose. By using a lookahead time shorter than | - | | sim_time, the critic will be less concerned about overshooting the goal yaw| - | | and thus will continue to turn faster for longer. | - +----------------+----------------------------------------------------------------------------+ - -:stateful: - +----------------+----------------------------------------------------------------------------+ - |**type** | bool | - +----------------+----------------------------------------------------------------------------+ - |**default** | true | - +----------------+----------------------------------------------------------------------------+ - |**description** | If the this parameter is set to true (which it is by default), once | - | | the desired cartesian difference is obtained, it will not check the | - | | cartesian difference again (until reset) and only check the yaw tolerance. | - | | This handles cases where the robot may accidentally leave the desired | - | | `xy_goal_tolerance` while rotating to the desired yaw. If `stateful` | - | | is true, this won't force the robot to try to move closer to the goal | - | | again, and instead just rotate to the goal. | - +----------------+----------------------------------------------------------------------------+ - -DWB Plugins -=========== - -.. toctree:: - :maxdepth: 1 - - dwb-plugins/trajectory-generators.rst - dwb-plugins/trajectory-critics.rst - dwb-plugins/goal-checkers.rst diff --git a/sphinx_doc/configuration/dwb-plugins/goal-checkers.rst b/sphinx_doc/configuration/dwb-plugins/goal-checkers.rst deleted file mode 100644 index 89e4ad88abd..00000000000 --- a/sphinx_doc/configuration/dwb-plugins/goal-checkers.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _dwb_goal_checkers: - -Goal Checkers -############# - -.. warning:: - - The parameters below are not properly scoped. The exact parameter names are - likely to change in the near future - -Common Parameters -================= - -:xy_goal_tolerance: - -:yaw_goal_tolerance: - -Simple Goal Checker -=================== - -Stopped Goal Checker -==================== diff --git a/sphinx_doc/configuration/dwb-plugins/trajectory-critics.rst b/sphinx_doc/configuration/dwb-plugins/trajectory-critics.rst deleted file mode 100644 index 8320027dee2..00000000000 --- a/sphinx_doc/configuration/dwb-plugins/trajectory-critics.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. _dwb_trajectory_critics: - -Trajectory Critics -################## - -.. warning:: - - The parameters below are not properly scoped. The exact parameter names are - likely to change in the near future - -Base Obstacle -============= -:BaseObstacle.class: - -:BaseObstacle.scale: - -:BaseObstacle.sum_scores: - - -Goal Align -========== -:GoalAlign.aggregation_type: - -:GoalAlign.class: - -:GoalAlign.forward_point_distance: - -:GoalAlign.scale: - - -Goal Distance -============= -:GoalDist.aggregation_type: - -:GoalDist.class: - -:GoalDist.scale: - - -Oscillation -=========== -:Oscillation.class: - -:Oscillation.oscillation_reset_angle: - -:Oscillation.oscillation_reset_dist: - -:Oscillation.oscillation_reset_time: - -:Oscillation.scale: - -:Oscillation.x_only_threshold: - - -Obstacle Footprint -================== - -Path Align -========== - -Parameters -********** - -:PathAlign.forward_point_distance: - -:PathAlign.scale: - -.. rst-class:: content-collapse - -Additional Parameters -********************* - -:PathAlign.aggregation_type: - -:PathAlign.class: - - -Path Distance -============= - -Parameters -********** - -:PathDist.scale: - -.. rst-class:: content-collapse - -Additional Parameters -********************* - -:PathDist.aggregation_type: - -:PathDist.class: - -Prefer Forward -============== - -Rotate To Goal -============== - -Parameters -********** - -:RotateToGoal.scale: - -:RotateToGoal.xy_goal_tolerance: - -:RotateToGoal.stateful: - -:RotateToGoal.trans_stopped_velocity: - -:RotateToGoal.slowing_factor: - -:RotateToGoal.lookahead_time: - -.. rst-class:: content-collapse - -Additional Parameters -********************* - -:RotateToGoal.class: - - -Twirling -======== diff --git a/sphinx_doc/configuration/dwb-plugins/trajectory-generators.rst b/sphinx_doc/configuration/dwb-plugins/trajectory-generators.rst deleted file mode 100644 index 247624c4c08..00000000000 --- a/sphinx_doc/configuration/dwb-plugins/trajectory-generators.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _dwb_trajectory_generators: - -Trajectory Generators -##################### - -.. warning:: - - The parameters below are not properly scoped. The exact parameter names are - likely to change in the near future - -Common Parameters -================= - -:acc_lim_theta: - -:acc_lim_x: - -:acc_lim_y: - -:decel_lim_theta: - -:decel_lim_x: - -:decel_lim_y: - -:max_speed_xy: - -:max_vel_theta: - -:max_vel_x: - -:max_vel_y: - -:min_speed_theta: - -:min_speed_xy: - -:min_theta_velocity_threshold: - -:min_vel_x: - -:min_vel_y: - -:min_x_velocity_threshold: - -:min_y_velocity_threshold: - -:vx_samples: - -:vy_samples: - -:discretize_by_time: - -:sim_time: - - -Standard Trajectory Generator -============================= - -Limited Acceleration Trajectory Generator -========================================= diff --git a/sphinx_doc/configuration/index.rst b/sphinx_doc/configuration/index.rst deleted file mode 100644 index 0cbd9ae643c..00000000000 --- a/sphinx_doc/configuration/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _configuration: - -Configuration Guidelines -######################## - -This guide provides a process through which the user can adjust the tunable parameters to obtain -the best navigation performance. - -.. toctree:: - :maxdepth: 1 - - configuring-the-controller.rst - params/tunable-params.rst diff --git a/sphinx_doc/configuration/params/tunable-params.rst b/sphinx_doc/configuration/params/tunable-params.rst deleted file mode 100644 index 48f151a877a..00000000000 --- a/sphinx_doc/configuration/params/tunable-params.rst +++ /dev/null @@ -1,419 +0,0 @@ -.. _docs_tunable-params: - -Tunable Parameters -################## - -Below is a list of all tunable parameters per node with some example values. -Only relevant nodes are shown. - -Also, the `nav2_bringup pkg`_ contains a `nav2_params file`_ with the default values to use for TB3. - -.. rst-class:: content-collapse - -AMCL -==== - -.. code-block:: yaml - - amcl: - ros__parameters: - alpha1: 0.2 - alpha2: 0.2 - alpha3: 0.2 - alpha4: 0.2 - alpha5: 0.2 - always_reset_initial_pose: false - base_frame_id: base_footprint - beam_skip_distance: 0.5 - beam_skip_error_threshold: 0.9 - beam_skip_threshold: 0.3 - do_beamskip: false - global_frame_id: map - lambda_short: 0.1 - laser_likelihood_max_dist: 2.0 - laser_max_range: 100.0 - laser_min_range: -1.0 - laser_model_type: likelihood_field - max_beams: 60 - max_particles: 2000 - min_particles: 500 - odom_frame_id: odom - pf_err: 0.05 - pf_z: 0.99 - recovery_alpha_fast: 0.0 - recovery_alpha_slow: 0.0 - resample_interval: 1 - robot_model_type: differential - save_pose_rate: 0.5 - set_initial_pose: false - sigma_hit: 0.2 - tf_broadcast: true - transform_tolerance: 1.0 - update_min_a: 0.2 - update_min_d: 0.25 - use_sim_time: true - z_hit: 0.5 - z_max: 0.05 - z_rand: 0.5 - z_short: 0.05 - - -.. rst-class:: content-collapse - -Controller Server -================= - -Hosts the `DWB` controller. - -.. code-block:: yaml - - controller_server: - ros__parameters: - BaseObstacle: - scale: 0.02 - sum_scores: false - BaseObstacle/class: BaseObstacle - GoalAlign: - aggregation_type: last - scale: 0.0 - GoalAlign/class: GoalAlign - GoalDist: - aggregation_type: last - scale: 24.0 - GoalDist/class: GoalDist - Oscillation: - scale: 1.0 - x_only_threshold: 0.05 - Oscillation/class: Oscillation - PathAlign: - aggregation_type: last - scale: 0.0 - PathAlign/class: PathAlign - PathDist: - aggregation_type: last - scale: 32.0 - PathDist/class: PathDist - RotateToGoal: - scale: 32.0 - RotateToGoal/class: RotateToGoal - acc_lim_theta: 3.2 - acc_lim_x: 2.5 - acc_lim_y: 0.0 - controller_frequency: 20.0 - critics: - - RotateToGoal - - Oscillation - - BaseObstacle - - GoalAlign - - PathAlign - - PathDist - - GoalDist - debug_trajectory_details: true - decel_lim_theta: -3.2 - decel_lim_x: -2.5 - decel_lim_y: 0.0 - discretize_by_time: false - goal_checker_name: dwb_plugins::SimpleGoalChecker - local_controller_plugin: dwb_core::DWBLocalPlanner - max_speed_xy: 0.26 - max_vel_theta: 1.0 - max_vel_x: 0.26 - max_vel_y: 0.0 - min_speed_theta: 0.0 - min_speed_xy: 0.0 - min_theta_velocity_threshold: 0.001 - min_vel_x: 0.0 - min_vel_y: 0.0 - min_x_velocity_threshold: 0.001 - min_y_velocity_threshold: 0.5 - prune_distance: 1.0 - prune_plan: true - publish_cost_grid_pc: false - publish_evaluation: true - publish_global_plan: true - publish_local_plan: true - publish_trajectories: true - publish_transformed_plan: true - sim_time: 1.7 - trajectory_generator_name: dwb_plugins::StandardTrajectoryGenerator - transform_tolerance: 0.2 - use_sim_time: true - vx_samples: 20 - vy_samples: 5 - xy_goal_tolerance: 0.25 - yaw_goal_tolerance: 0.25 - short_circuit_trajectory_evaluation: True - trans_stopped_velocity: 0.25 - slowing_factor: 5.0 - lookahead_time: -1.0 - stateful: True - - -.. rst-class:: content-collapse - -Local Costmap -================= - -Hosted on the `PlannerServer` node. - -.. code-block:: yaml - - local_costmap: - ros__parameters: - always_send_full_costmap: true - clearable_layers: - - obstacle_layer - footprint: '[]' - footprint_padding: 0.01 - global_frame: odom - height: 3 - inflation_layer: - cost_scaling_factor: 3.0 - enabled: true - inflate_unknown: false - inflation_radius: 0.55 - lethal_cost_threshold: 100 - map_topic: /map - observation_sources: '' - obstacle_layer: - combination_method: 1 - enabled: true - footprint_clearing_enabled: true - max_obstacle_height: 2.0 - observation_sources: scan - scan: - clearing: true - data_type: LaserScan - expected_update_rate: 0.0 - inf_is_valid: false - marking: true - max_obstacle_height: 2.0 - min_obstacle_height: 0.0 - observation_persistence: 0.0 - obstacle_range: 2.5 - raytrace_range: 3.0 - sensor_frame: '' - topic: /scan - origin_x: 0.0 - origin_y: 0.0 - plugin_names: - - obstacle_layer - - voxel_layer - - inflation_layer - plugin_types: - - nav2_costmap_2d::ObstacleLayer - - nav2_costmap_2d::VoxelLayer - - nav2_costmap_2d::InflationLayer - publish_frequency: 1.0 - resolution: 0.05 - robot_base_frame: base_link - robot_radius: 0.22 - rolling_window: true - track_unknown_space: false - transform_tolerance: 0.3 - trinary_costmap: true - unknown_cost_value: 255 - update_frequency: 5.0 - use_maximum: false - use_sim_time: true - voxel_layer: - combination_method: 1 - enabled: true - footprint_clearing_enabled: true - mark_threshold: 0 - max_obstacle_height: 2.0 - observation_sources: pointcloud - origin_z: 0.0 - pointcloud: - clearing: true - data_type: PointCloud2 - expected_update_rate: 0.0 - inf_is_valid: false - marking: true - max_obstacle_height: 2.0 - min_obstacle_height: 0.0 - observation_persistence: 0.0 - obstacle_range: 2.5 - raytrace_range: 3.0 - sensor_frame: '' - topic: /intel_realsense_r200_depth/points - publish_voxel_map: true - unknown_threshold: 15 - z_resolution: 0.2 - z_voxels: 10 - width: 3 - - -.. rst-class:: content-collapse - -Planner Server -================= - -Hosts the `NAVFN` controller. - -.. code-block:: yaml - - planner_server: - ros__parameters: - allow_unknown: true - planner_plugin: nav2_navfn_planner/NavfnPlanner - tolerance: 0.0 - use_astar: false - use_sim_time: true - - -.. rst-class:: content-collapse - -Global Costmap -================= - -Hosted on the `ControllerServer` node. - -.. code-block:: yaml - - global_costmap: - ros__parameters: - always_send_full_costmap: true - clearable_layers: - - obstacle_layer - footprint: '[]' - footprint_padding: 0.01 - global_frame: map - height: 10 - inflation_layer: - cost_scaling_factor: 10.0 - enabled: true - inflate_unknown: false - inflation_radius: 0.55 - lethal_cost_threshold: 100 - map_topic: /map - observation_sources: '' - obstacle_layer: - combination_method: 1 - enabled: true - footprint_clearing_enabled: true - max_obstacle_height: 2.0 - observation_sources: scan - scan: - clearing: true - data_type: LaserScan - expected_update_rate: 0.0 - inf_is_valid: false - marking: true - max_obstacle_height: 2.0 - min_obstacle_height: 0.0 - observation_persistence: 0.0 - obstacle_range: 2.5 - raytrace_range: 3.0 - sensor_frame: '' - topic: /scan - origin_x: 0.0 - origin_y: 0.0 - plugin_names: - - static_layer - - obstacle_layer - - voxel_layer - - inflation_layer - plugin_types: - - nav2_costmap_2d::StaticLayer - - nav2_costmap_2d::ObstacleLayer - - nav2_costmap_2d::VoxelLayer - - nav2_costmap_2d::InflationLayer - publish_frequency: 1.0 - resolution: 0.1 - robot_base_frame: base_link - robot_radius: 0.22 - rolling_window: false - static_layer: - enabled: true - map_subscribe_transient_local: true - subscribe_to_updates: false - track_unknown_space: false - transform_tolerance: 0.3 - trinary_costmap: true - unknown_cost_value: 255 - update_frequency: 5.0 - use_maximum: false - use_sim_time: true - voxel_layer: - combination_method: 1 - enabled: true - footprint_clearing_enabled: true - mark_threshold: 0 - max_obstacle_height: 2.0 - observation_sources: pointcloud - origin_z: 0.0 - pointcloud: - clearing: true - data_type: PointCloud2 - expected_update_rate: 0.0 - inf_is_valid: false - marking: true - max_obstacle_height: 2.0 - min_obstacle_height: 0.0 - observation_persistence: 0.0 - obstacle_range: 2.5 - raytrace_range: 3.0 - sensor_frame: '' - topic: /intel_realsense_r200_depth/points - publish_voxel_map: true - unknown_threshold: 15 - z_resolution: 0.2 - z_voxels: 10 - width: 10 - - -.. rst-class:: content-collapse - -Map Server -================= - -.. code-block:: yaml - - map_server: - ros__parameters: - use_sim_time: true - yaml_filename: turtlebot3_world.yaml - - -.. rst-class:: content-collapse - -Recovery Server -================= - -Hosts multiple recovery actions - -.. code-block:: yaml - - recoveries_server: - ros__parameters: - costmap_topic: local_costmap/costmap_raw - cycle_frequency: 10.0 - footprint_topic: local_costmap/published_footprint - max_rotational_vel: 1.0 - min_rotational_vel: 0.4 - plugin_names: - - Spin - - BackUp - - Wait - plugin_types: - - nav2_recoveries/Spin - - nav2_recoveries/BackUp - - nav2_recoveries/Wait - rotational_acc_lim: 3.2 - simulate_ahead_time: 2.0 - use_sim_time: true - - -.. rst-class:: content-collapse - -BT Navigator -================= -Behavior-Tree-based Navigator - -.. code-block:: yaml - - bt_navigator: - ros__parameters: - bt_xml_filename: navigate_w_replanning_and_recovery.xml - use_sim_time: true diff --git a/sphinx_doc/contribute/index.rst b/sphinx_doc/contribute/index.rst deleted file mode 100644 index a83c105f7e5..00000000000 --- a/sphinx_doc/contribute/index.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _contribute: - -Getting Involved -################ - -As an open-source project, we welcome and encourage the community to -submit patches directly to the |LPN|. In our collaborative open -source environment, standards and methods for submitting changes help -reduce the chaos that can result from an active development community. - -This document explains how to participate in project conversations, log -and track bugs and enhancement requests, and submit patches to the -project so your patch will be accepted quickly in the codebase. - -Getting Involved -**************** - -If you're interested in getting involved in Navigation 2, first of all, welcome! -We encourage everyone to get involved from students, to junior developers, to senior developers, and executives. -There's something to do for everyone from bug fixes, to feature development, new algorithms, and refactoring. - -All ROS2 TSC Working Groups have their meetings on the `working group calendar `_. -Here, you can find the date and time of the Navigation2 working group meeting. Make sure you're checking in your local timezone. -From this calendar, you can add yourself to the event so it will appear on your google calendar and get the event link to the call through Google Hangouts. -We encourage everyone interested to come to the meeting to introduce yourself, your project, and see what everyone is working on. - -Further, `ROS Discourse `_ is a good place to follow larger discussions happening in the community and announcements. This is **not** the correct place to post questions or ask for assistance. Please visit `ROS Answers `_ for Q&A. - -If you're looking to contribute code or bugs, please see the Process section below. - -Over time, for developers that have an interest and have shown technical competence in an area of the stack, we elevate developers to a maintainers status. -That allows push rights to our protected branches, first-reviewers rights, and getting your name on :ref:`about`. -There currently is not a clear process for getting to be a maintainer, but if you've been involved and contributing over a duration of several months, you may be a good candidate and should email the project lead listed on :ref:`about`. - -Process -******* - -After you've introduced yourself in a working group meeting (recommended, not required), you're ready to get started! -We recommend a typical open-source project flow and value detail and transparency. -If you commit to something and need to pull back, say so. -We all know priorities change and appreciate the heads up so that task can go into the open queue of tasks. - -The process is simple and is as follow: - -1. Create a ticket for any issues or features you'd like to see. You are not required to fix / implement patches required, but it would be helpful. Reporting bugs is also a valuable contribution. - -2. If this ticket, or another existing ticket, is something you would like to work on, comment in the ticket claiming ownership over it. It would be helpful at this time if you declared a strategy and a timeline for planning purposes of other folks working around you. Over time, update the ticket with progress of key markers and engage in any constructive feedback maintainers or other users may have. - -3. Once you've completed the task you set out to complete, submit a PR! Please fill out the PR template in complete to ensure that we have a full understanding of your work. At that point, 1-2 reviewers will take a look at your work and give it some feedback to be merged into the codebase. For trivial changes, a single maintainer may merge it after review if they're happy with it, up to their discretion. Any substantial changes should be approved by at least 1 maintainer and 1 other community member. - -Note: We take code quality seriously and strive for high-quality and consistent code. -We make use of the linting and static analysis tools provided in ROS2 (``ament_cpplint``, ``ament_uncrustify``, ``ament_cppcheck``, etc). -All PRs are built in CI with the appropriate ROS distributions and run through a set of unit and system level tests including static analysis. -You can see the results of these tests in the pull request. -It is expected for feature development for tests to cover this work to be added. -If any documentation must be updated due to your changes, that should be included in your pull request. - -Licensing -********* - -Licensing is very important to open source projects. It helps ensure the -software continues to be available under the terms that the author -desired. - -Because much of the source code is ported from other ROS 1 projects, each -package has it's own license. Contributions should be made under the predominant -license of that package. Entirely new packages should be made available under -the `Apache 2.0 license `_. - -A license tells you what rights you have as a developer, as provided by -the copyright holder. It is important that the contributor fully -understands the licensing rights and agrees to them. Sometimes the -copyright holder isn't the contributor, such as when the contributor is -doing work on behalf of a company. - -If for some reason Apache 2.0 or BSD licenses are not appropriate for your work, please get in contact with a project maintainer and discuss your concerns or requirements. -We may consider special exceptions for exceptional work, within reason (we will not accept any licenses that makes it unsuitable for commercial use). - -.. _DCO: - -Developer Certification of Origin (DCO) -*************************************** - -To make a good faith effort to ensure licensing criteria are met, -|LPN| encourages the Developer Certificate of Origin (DCO) process -to be followed. - -The DCO is an attestation attached to every contribution made by a -developer. In the commit message of the contribution, (described more -fully later in this document), the developer simply adds a -``Signed-off-by`` statement and thereby agrees to the DCO. - -In practice, its easier to just ``git commit -s -m "commit messsage."``. -Where ``-s`` adds this automatically. -If you forgot to add this to a commit, it is easy to append via: ``git commit --amend -s``. - -When a developer submits a patch, it is a commitment that the -contributor has the right to submit the patch per the license. The DCO -agreement is shown below and at http://developercertificate.org/. - -.. code-block:: none - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the - best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to - submit that work with modifications, whether created in whole - or in part by me, under the same open source license (unless - I am permitted to submit under a different license), as - Indicated in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. - diff --git a/sphinx_doc/getting_started/images/navigation_with_recovery_behaviours.gif b/sphinx_doc/getting_started/images/navigation_with_recovery_behaviours.gif deleted file mode 100644 index 850882eab5f..00000000000 Binary files a/sphinx_doc/getting_started/images/navigation_with_recovery_behaviours.gif and /dev/null differ diff --git a/sphinx_doc/getting_started/index.rst b/sphinx_doc/getting_started/index.rst deleted file mode 100644 index 20277be5449..00000000000 --- a/sphinx_doc/getting_started/index.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. _getting_started: - -Getting Started -############### - -This document will take you through the process of installing the |PN| binaries -and navigating a simulated Turtlebot 3 in the Gazebo simulator. - -.. note:: - - See the :ref:`build-instructions` for other situations such as building from source or - working with other types of robots. - -.. warning:: - - This is a simplified version of the Turtlebot 3 instructions. We highly - recommend you follow the `official Turtlebot 3 manual`_ if you intend to - continue working with this robot beyond the minimal example provided here. - -Installation -************ - -1. Install the `ROS 2 binary packages`_ as described in the official docs -2. Install the |PN| packages using your operating system's package manager: - - .. code-block:: bash - - sudo apt install ros--navigation2 - sudo apt install ros--nav2-bringup - -3. Install the Turtlebot 3 packages: - - .. code-block:: bash - - sudo apt install ros--turtlebot3* - -Running the Example -******************* - -1. Start a terminal in your GUI -2. Set key environment variables: - - .. code-block:: bash - - source /opt/ros//setup.bash - export TURTLEBOT3_MODEL=waffle - export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:/opt/ros//share/turtlebot3_gazebo/models - -3. In the same terminal, run - - .. code-block:: bash - - ros2 launch nav2_bringup tb3_simulation_launch.py - - This launch file will launch Navigation2 with the AMCL localizer in the - ``turtlebot3_world`` world. - It will also launch a the robot state publisher to provide transforms, - a Gazebo instance with the Turtlebot3 URDF, and RVIZ. - - If everything has started correctly, you will see the RViz and Gazebo GUIs like - this: - - .. image:: /images/rviz/rviz-not-started.png - :width: 45% - .. image:: /images/gazebo/gazebo_turtlebot1.png - :width: 46% - -4. Click the "Startup" button in the bottom left corner of RViz. This will - cause |PN| to change to the Active state. It should - change appearance to show the map. - - .. image:: /images/rviz/rviz_initial.png - :width: 700px - :align: center - :alt: Initial appearance of RViz transitioning to the Active state - -Navigating -********** - -After starting, the robot initially has no idea where it is. By default, -|PN| waits for you to give it an approximate starting position. Take a look -at where the robot is in the Gazebo world, and find that spot on the map. Set -the initial pose by clicking the "2D Pose Estimate" button in RViz, and then -down clicking on the map in that location. You set the orientation by dragging -forward from the down click. - -If you are using the defaults so far, the robot should look roughly like this. - - .. image:: /images/rviz/rviz-set-initial-pose.png - :width: 700px - :align: center - :alt: Approximate starting location of Turtlebot - -If you don't get the location exactly right, that's fine. |PN| will refine -the position as it navigates. You can also, click the "2D Pose -Estimate" button and try again, if you prefer. - -Once you've set the initial pose, the transform tree will be complete and -|PN| is fully active and ready to go. You should see the robot and particle -cloud now. - - .. image:: /images/rviz/navstack-ready.png - :width: 700px - :align: center - :alt: |PN| is ready. Transforms and Costmap show in RViz. - -Next, click the "Navigaton2 Goal" button and choose a destination. -This will call the BT navigator to go to that goal through an action server. -You can pause (cancel) or reset the action through the navigation2 rviz plugin shown. - - .. image:: /images/rviz/navigate-to-pose.png - :width: 700px - :align: center - :alt: Setting the goal pose in RViz. - -Now watch the robot go! - -.. image:: images/navigation_with_recovery_behaviours.gif - :width: 700px - :alt: Navigation2 with Turtlebot 3 Demo - :align: center diff --git a/sphinx_doc/images/architectural_diagram.png b/sphinx_doc/images/architectural_diagram.png deleted file mode 100644 index 9801ef9d690..00000000000 Binary files a/sphinx_doc/images/architectural_diagram.png and /dev/null differ diff --git a/sphinx_doc/images/favicon-16x16.png b/sphinx_doc/images/favicon-16x16.png deleted file mode 100644 index e9a16774c98..00000000000 Binary files a/sphinx_doc/images/favicon-16x16.png and /dev/null differ diff --git a/sphinx_doc/images/favicon-48x48.png b/sphinx_doc/images/favicon-48x48.png deleted file mode 100644 index ce2315d5353..00000000000 Binary files a/sphinx_doc/images/favicon-48x48.png and /dev/null differ diff --git a/sphinx_doc/images/gazebo/gazebo_turtlebot1.png b/sphinx_doc/images/gazebo/gazebo_turtlebot1.png deleted file mode 100644 index b5776b16f40..00000000000 Binary files a/sphinx_doc/images/gazebo/gazebo_turtlebot1.png and /dev/null differ diff --git a/sphinx_doc/images/logo_dark.png b/sphinx_doc/images/logo_dark.png deleted file mode 100644 index 0af0b3cc92c..00000000000 Binary files a/sphinx_doc/images/logo_dark.png and /dev/null differ diff --git a/sphinx_doc/images/logo_dark_120w.png b/sphinx_doc/images/logo_dark_120w.png deleted file mode 100644 index 888f5f1632f..00000000000 Binary files a/sphinx_doc/images/logo_dark_120w.png and /dev/null differ diff --git a/sphinx_doc/images/logo_white.png b/sphinx_doc/images/logo_white.png deleted file mode 100644 index 71aa3c69a74..00000000000 Binary files a/sphinx_doc/images/logo_white.png and /dev/null differ diff --git a/sphinx_doc/images/logo_white_200w.png b/sphinx_doc/images/logo_white_200w.png deleted file mode 100644 index b446b057cd0..00000000000 Binary files a/sphinx_doc/images/logo_white_200w.png and /dev/null differ diff --git a/sphinx_doc/images/rviz/navigate-to-pose.png b/sphinx_doc/images/rviz/navigate-to-pose.png deleted file mode 100644 index 0634a46c8c1..00000000000 Binary files a/sphinx_doc/images/rviz/navigate-to-pose.png and /dev/null differ diff --git a/sphinx_doc/images/rviz/navigating.png b/sphinx_doc/images/rviz/navigating.png deleted file mode 100644 index 3e84ce8098d..00000000000 Binary files a/sphinx_doc/images/rviz/navigating.png and /dev/null differ diff --git a/sphinx_doc/images/rviz/navstack-ready.png b/sphinx_doc/images/rviz/navstack-ready.png deleted file mode 100644 index 43e89ea6caf..00000000000 Binary files a/sphinx_doc/images/rviz/navstack-ready.png and /dev/null differ diff --git a/sphinx_doc/images/rviz/rviz-not-started.png b/sphinx_doc/images/rviz/rviz-not-started.png deleted file mode 100644 index 733471141b6..00000000000 Binary files a/sphinx_doc/images/rviz/rviz-not-started.png and /dev/null differ diff --git a/sphinx_doc/images/rviz/rviz-set-initial-pose.png b/sphinx_doc/images/rviz/rviz-set-initial-pose.png deleted file mode 100644 index c732e2ecf53..00000000000 Binary files a/sphinx_doc/images/rviz/rviz-set-initial-pose.png and /dev/null differ diff --git a/sphinx_doc/images/rviz/rviz_initial.png b/sphinx_doc/images/rviz/rviz_initial.png deleted file mode 100644 index 5a1a4e505b1..00000000000 Binary files a/sphinx_doc/images/rviz/rviz_initial.png and /dev/null differ diff --git a/sphinx_doc/index.rst b/sphinx_doc/index.rst deleted file mode 100644 index 0db0a7bfc65..00000000000 --- a/sphinx_doc/index.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _documentation_home: - -***** -|LPN| -***** - -.. raw:: html - -

-
-
- - -
-
-

- -Overview -######## - -The Navigation 2 project is the spiritual successor of the ROS Navigation Stack. -This project seeks to find a safe way to have a mobile robot move from point A to -point B. This will complete dynamic path planning, compute velocities for motors, -avoid obstacles, and structure recovery behaviors. To learn more about this project see :ref:`about`. - -Navigation 2 uses behavior trees to call modular servers to complete an action. -An action can be to compute a path, control effort, recovery, or any other navigation -related action. These are each separate nodes that communicate with the behavior tree (BT) -over a ROS action server. The diagram below will give you a good first-look at the structure -of Navigation 2. Note: It is possible to have multiple plugins for controllers, planners, -and recoveries in each of their servers with matching BT plugins. This can be used to -create contextual navigation behaviors. -If you would like to see a comparison between this project and ROS (1) Navigation, see :ref:`ros1_comparison`. - -The expected inputs to Navigation2 (Nav2) are TF transformations conforming to REP-105, a -map source if utilizing the Static Costmap Layer, a BT XML file, and any relevant sensor data -sources. It will then provide valid velocity commands for the motors of a holonomic or -non-holonomic robot to follow. We currently support holonomic and differential-drive base types -but plan to support Ackermann (car-like) robots as well in the near future. - - -It has tools to: - -- load, serve, and store maps (Map Server) -- localize the robot on the map (AMCL) -- plan a path from A to B around obstacles (Nav2 Planner) -- control the robot as it follows the path (Nav2 Controller) -- convert sensor data into a costmap representation of the world (Nav2 Costmap 2D) -- build complicated robot behaviors using behavior trees (Nav2 Behavior Trees and BT Navigator) -- Compute recovery behaviors in case of failure (Nav2 Recoveries) -- Follow sequential waypoints (Nav2 Waypoint Follower) -- Manage the lifecycle of the servers (Nav2 Lifecycle Manager) -- Plugins to enable your own custom algorithms and behaviors (Nav2 Core) - -.. image:: images/architectural_diagram.png - :width: 700px - :align: center - :alt: Navigation2 Block Diagram - -We also provide a set of starting plugins to get you going. NavFn computes the shortest path -from a pose to a goal pose using A* or Dijkstra's algorithm. DWB will use the DWA algorithm -to compute a control effort to follow a path, with several plugins of its own for trajectory -critics. There are recovery behaviors included: waiting, spinning, clearing costmaps, and -backing up. There are a set of BT plugins for calling these servers and computing conditions. -Finally, there are a set of Rviz plugins for interacting with the stack and controlling the -lifecycle. A list of all user-reported plugins can be found on :ref:`plugins`. - -Here is the documentation on how to install and use |PN| with an example robot, Turtlebot -3 (TB3), as well as how to customize it for other robots, tune the behavior for better -performance, as well as customize the internals for advanced results. Below is an example -of the TB3 navigating in a small lounge. - -.. raw:: html - -

-
- -
-

- -.. toctree:: - :hidden: - - getting_started/index.rst - build_instructions/index.rst - concepts/index.rst - tutorials/index.rst - configuration/index.rst - plugins/index.rst - migration/index.rst - contribute/index.rst - about/index.rst diff --git a/sphinx_doc/make.bat b/sphinx_doc/make.bat deleted file mode 100644 index 0825fc7298c..00000000000 --- a/sphinx_doc/make.bat +++ /dev/null @@ -1,263 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - echo. coverage to run coverage check of the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 2> nul -if errorlevel 9009 goto sphinx_python -goto sphinx_ok - -:sphinx_python - -set SPHINXBUILD=python -m sphinx.__init__ -%SPHINXBUILD% 2> nul -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -:sphinx_ok - - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\ClearLinux.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\ClearLinux.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -:end diff --git a/sphinx_doc/migration/Dashing.rst b/sphinx_doc/migration/Dashing.rst deleted file mode 100644 index e22a8a5d3e3..00000000000 --- a/sphinx_doc/migration/Dashing.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _dashing_migration: - -Dashing to Eloquent -################### - -Moving from ROS2 Dashing to Eloquent, a number of stability improvements were added that we will not specifically address here. - -New Packages -************ - -Navigation2 now includes a new package ``nav2_waypoint_follower``. -The waypoint follower is an action server that will take in a list of waypoints to follow and follow them in order. -There is a parameter ``stop_on_failure`` whether the robot should continue to the next waypoint on a single waypoint failure, -or to return fail to the action client. -The waypoint follower is also a reference application for how to use the Navigation2 action server to complete a basic autonomy task. - - -Navigation2 now supports new algorithms for control and SLAM. -The Timed-Elastic Band (TEB) controller was implemented `and can be found here `_. -It is its own controller plugin that can be used instead of the DWB controller. -Nav2 also supports SLAM Toolbox as the default SLAM implementation for ROS2. -This replaces the use of Cartographer. - -New Plugins -*********** - -Eloquent introduces back in pluginlib plugins to the navigation stack. -``nav2_core`` defines the plugin header interfaces to be used to implement controller, planner, recovery, and goal checker plugins. -All algorithms (NavFn, DWB, recoveries) were added as plugin interfaces and the general packages for servers were created. -``nav2_planner`` is the action server for planning that hosts a plugin for the planner. -``nav2_controller`` is the action server for controller that hosts a plugin for the controller. -``nav2_recovery`` is the action server for recovery that hosts a plugin for recovery. - -New recovery plugins were added including backup, which will take in a distance to back up, if collision-free. -Additionally, the wait recovery was added that will wait a configurable period of time before trying to navigate again. -This plugin is especially helpful for time-dependent obstacles or pausing navigation for a scene to become less dynamic. - -Many new behavior tree nodes were added. These behavior tree nodes are hard-coded in the behavior tree engine. -Behavior tree cpp v3 supports plugins and will be converted in the next release. - -Navigation2 Architectural Changes -********************************* - -The ``nav2_world_model`` package was removed. The individual ``nav2_planner`` and ``nav2_controller`` servers now host their relevent costmaps. -This was done to reduce network traffic and ensure up-to-date information for the safety-critical elements of the system. -As above mentions, plugins were introduced into the stack and these servers each host plugins for navigation, control, and costmap layers. - -Map server was substantially refactored but the external API remains the same. It now uses the SDL library for image loading. - -TF-based positioning is now used for pose-estimation everywhere in the stack. -Prior, some elements of the navigation stack only updated its pose from the ``/amcl_pose`` topic publishing at an irregular rate. -This is obviously low-accuracy and high-latency. -All positioning is now based on the TF tree from the global frame to the robot frame. - -Prior to Eloquent, there were no ROS2 action servers and clients available. -Navigation2, rather, used an interface we called Tasks. -Eloquent now contains actions and a simple action server interface was created and is used now throughout the stack. -Tasks were removed. diff --git a/sphinx_doc/migration/Eloquent.rst b/sphinx_doc/migration/Eloquent.rst deleted file mode 100644 index 54235d35341..00000000000 --- a/sphinx_doc/migration/Eloquent.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _eloquent_migration: - -Eloquent to Foxy -################ - -Moving from ROS2 Eloquent to Foxy, a number of stability improvements were added that we will not specifically address here. -We will specifically mention, however, the reduction in terminal noise. -TF2 transformation timeout errors and warnings on startup have been largely removed or throttled to be more tractable. -Additionally, message filters filling up resulting in messages being dropped were resolved in costmap 2d. - -General -******* - -The lifecycle manager was split into 2 unique lifecycle managers. -They are the ``navigation_lifecycle_manager`` and ``localization_lifecycle_manager``. -This gives each process their own manager to allow users to switch between SLAM and localization without effecting Navigation. -It also reduces the redundant code in ``nav2_bringup``. - -A fix to the BT navigator was added to remove a rare issue where it may crash due to asynchronous issues. -As a result, a behavior tree is created for each navigation request rather than resetting an existing tree. -The creation of this tree will add a small amount of latency. -Proposals to reduce this latency will be considered before the next release. - -Server Updates -************** -All plugin servers (controller, planner, recovery) now supports the use of multiple plugins. -This can be done by loading a map of plugins, mapping the name of the plugin to its intended use-case. -An example: ``FollowPath`` controller of type ``dwb_local_planner/DWBLocalPlanner`` and a ``DynamicFollowPath`` of type ``teb_local_planner/TEBLocalPlanner``. -Each plugin will load the parameters in their namespace, e.g. ``FollowPath.max_vel_x``, rather than globally in the server namespace. -This will allow multiple plugins of the same type with different parameters and reduce conflicting parameter names. - -DWB Contains new parameters as an update relative to the ROS1 updates, `see here for more information `_. -Additionally, the controller and planner interfaces were updated to include a ``std::string name`` parameter on initialization. -This was added to the interfaces to allow the plugins to know the namespace it should load its parameters in. -E.g. for a controller to find the parameter ``FollowPath.max_vel_x``, it must be given its name, ``FollowPath`` to get this parameter. -All plugins will be expected to look up parameters in the namespace of its given name. - -New Plugins -*********** - -Many new behavior tree nodes were added. -These behavior tree nodes are now BT plugins and dynamically loadable at run-time using behavior tree cpp v3. -See ``nav2_behavior_tree`` for a full listing, or :ref:`plugins` for the current list of behavior tree plugins and their descriptions. -These plugins are set as default in the ``nav2_bt_navigator`` but may be overrided by the ``bt_plugins`` parameter to include your specific plugins. - -Map Server Re-Work -****************** - -``map_saver`` was re-worked and divided into 2 parts: CLI and server. -CLI part is a command-line tool that listens incoming map topic, saves map once into a file and finishes its work. This part is remained to be almost untouched: CLI executable was renamed from ``map_saver`` to ``map_saver_cli`` without changing its functionality. -Server is a new part. It spins in the background and can be used to save map continuously through a ``save_map`` service. By each service request it tries to listen incoming map topic, receive a message from it and write obtained map into a file. - -``map_server`` was dramatically simplified and cleaned-up. ``OccGridLoader`` was merged with ``MapServer`` class as it is intended to work only with one ``OccupancyGrid`` type of messages in foreseeable future. - -Map Server now has new ``map_io`` dynamic library. All functions saving/loading ``OccupancyGrid`` messages were moved from ``map_server`` and ``map_saver`` here. These functions could be easily called from any part of external ROS2 code even if Map Server node was not started. - -``map_loader`` was completely removed from ``nav2_util``. All its functionality already present in ``map_io``. Please use it in your code instead. - -Please refer to the `original GitHub ticket `_ and `Map Server README `_ for more information. diff --git a/sphinx_doc/migration/index.rst b/sphinx_doc/migration/index.rst deleted file mode 100644 index 9c9ba065351..00000000000 --- a/sphinx_doc/migration/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _migration: - -Migration Guides -################ - -Navigation2 guides for migration between distributions. - -.. raw:: html - -

-
- -
-

- -.. toctree:: - :hidden: - :maxdepth: 1 - - Dashing.rst - Eloquent.rst diff --git a/sphinx_doc/plugins/index.rst b/sphinx_doc/plugins/index.rst deleted file mode 100644 index e20a83a178a..00000000000 --- a/sphinx_doc/plugins/index.rst +++ /dev/null @@ -1,206 +0,0 @@ -.. _plugins: - -Navigation Plugins -################## - -There are a number of plugin interfaces for users to create their own custom applications or algorithms with. -Namely, the costmap layer, planner, controller, behavior tree, and recovery plugins. -A list of all known plugins are listed here below for ROS2 Navigation. -If you know of a plugin, or you have created a new plugin, please consider submitting a pull request with that information. - -This file can be found and editted under ``sphinx_docs/plugins/index.rst``. -For tutorials on creating your own plugins, please see :ref:`writing_new_costmap2d_plugin`. - -Costmap Layers -============== - -+--------------------------------+------------------------+----------------------------------+ -| Plugin Name | Creator | Description | -+================================+========================+==================================+ -| `Voxel Layer`_ | Eitan Marder-Eppstein | Maintains persistant | -| | | 3D voxel layer using depth and | -| | | laser sensor readings and | -| | | raycasting to clear free space | -+--------------------------------+------------------------+----------------------------------+ -| `Static Layer`_ | Eitan Marder-Eppstein | Gets static ``map`` and loads | -| | | occupancy information into | -| | | costmap | -+--------------------------------+------------------------+----------------------------------+ -| `Inflation Layer`_ | Eitan Marder-Eppstein | Inflates lethal obstacles in | -| | | costmap with exponential decay | -+--------------------------------+------------------------+----------------------------------+ -| `Obstacle Layer`_ | Eitan Marder-Eppstein | Maintains persistent 2D costmap | -| | | from 2D laser scans with | -| | | raycasting to clear free space | -+--------------------------------+------------------------+----------------------------------+ -| `Spatio-Temporal Voxel Layer`_ | Steve Macenski | Maintains temporal 3D sparse | -| | | volumetric voxel grid with decay | -| | | through sensor models | -+--------------------------------+------------------------+----------------------------------+ -| `Non-Persistent Voxel Layer`_ | Steve Macenski | Maintains 3D occupancy grid | -| | | consisting only of the most | -| | | sets of measurements | -+--------------------------------+------------------------+----------------------------------+ - -.. _Voxel Layer: https://github.com/ros-planning/navigation2/tree/master/nav2_costmap_2d/plugins -.. _Static Layer: https://github.com/ros-planning/navigation2/tree/master/nav2_costmap_2d/plugins -.. _Inflation Layer: https://github.com/ros-planning/navigation2/tree/master/nav2_costmap_2d/plugins -.. _Obstacle Layer: https://github.com/ros-planning/navigation2/tree/master/nav2_costmap_2d/plugins -.. _Spatio-Temporal Voxel Layer: https://github.com/SteveMacenski/spatio_temporal_voxel_layer/ -.. _Non-Persistent Voxel Layer: https://github.com/SteveMacenski/nonpersistent_voxel_layer - -Controllers -=========== - -+--------------------------+--------------------+----------------------------------+ -| Plugin Name | Creator | Description | -+==========================+====================+==================================+ -| `DWB Controller`_ | David Lu!! | A highly configurable DWA | -| | | implementation with plugin | -| | | interfaces | -+--------------------------+--------------------+----------------------------------+ -| `TEB Controller`_ | Christoph Rösmann | A MPC-like controller suitable | -| | | for ackermann, differential, and | -| | | holonomic robots. | -+--------------------------+--------------------+----------------------------------+ - -.. _DWB Controller: https://github.com/ros-planning/navigation2/tree/master/nav2_dwb_controller -.. _TEB Controller: https://github.com/rst-tu-dortmund/teb_local_planner - -Planners -======== - -+-------------------+---------------------------------------+------------------------------+ -| Plugin Name | Creator | Description | -+===================+=======================================+==============================+ -| `NavFn Planner`_ | Eitan Marder-Eppstein & Kurt Konolige | A navigation function | -| | | using A* or Dijkstras | -| | | expansion, assumes 2D | -| | | holonomic particle | -+-------------------+---------------------------------------+------------------------------+ - -.. _NavFn Planner: https://github.com/ros-planning/navigation2/tree/master/nav2_navfn_planner - -Recoveries -========== - -+----------------------+------------------------+----------------------------------+ -| Plugin Name | Creator | Description | -+======================+========================+==================================+ -| `Clear Costmap`_ | Eitan Marder-Eppstein | A service to clear the given | -| | | costmap in case of incorrect | -| | | perception or robot is stuck | -+----------------------+------------------------+----------------------------------+ -| `Spin`_ | Steve Macenski | Rotate recovery of configurable | -| | | angles to clear out free space | -| | | and nudge robot out of potential | -| | | local failures | -+----------------------+------------------------+----------------------------------+ -| `Back Up`_ | Brian Wilcox | Back up recovery of configurable | -| | | distance to back out of a | -| | | situation where the robot is | -| | | stuck | -+----------------------+------------------------+----------------------------------+ -| `Wait`_ | Steve Macenski | Wait recovery with configurable | -| | | time to wait in case of time | -| | | based obstacle like human traffic| -| | | or getting more sensor data | -+----------------------+------------------------+----------------------------------+ - -.. _Rotate: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Back Up: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Spin: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Wait: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Clear Costmap: https://github.com/ros-planning/navigation2/blob/master/nav2_costmap_2d/src/clear_costmap_service.cpp - -Behavior Tree Nodes -=================== - -+--------------------------------------------+---------------------+----------------------------------+ -| Action Plugin Name | Creator | Description | -+============================================+=====================+==================================+ -| `Back Up Action`_ | Michael Jeronimo | Calls backup recovery action | -+--------------------------------------------+---------------------+----------------------------------+ -| `Clear Costmap Service`_ | Carl Delsey | Calls clear costmap service | -+--------------------------------------------+---------------------+----------------------------------+ -| `Compute Path to Pose Action`_ | Michael Jeronimo | Calls Nav2 planner server | -+--------------------------------------------+---------------------+----------------------------------+ -| `Follow Path Action`_ | Michael Jeronimo | Calls Nav2 controller server | -+--------------------------------------------+---------------------+----------------------------------+ -| `Navigate to Pose Action`_ | Michael Jeronimo | BT Node for other | -| | | BehaviorTree.CPP BTs to call | -| | | Navigation2 as a subtree action | -+--------------------------------------------+---------------------+----------------------------------+ -| `Reinitalize Global Localization Service`_ | Carl Delsey | Reinitialize AMCL to a new pose | -+--------------------------------------------+---------------------+----------------------------------+ -| `Spin Action`_ | Carl Delsey | Calls spin recovery action | -+--------------------------------------------+---------------------+----------------------------------+ -| `Wait Action`_ | Steve Macenski | Calls wait recovery action | -+--------------------------------------------+---------------------+----------------------------------+ - -.. _Back Up Action: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Clear Costmap Service: https://github.com/ros-planning/navigation2/blob/master/nav2_costmap_2d/src/clear_costmap_service.cpp -.. _Compute Path to Pose Action: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Follow Path Action: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Navigate to Pose Action: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Reinitalize Global Localization Service: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Spin Action: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Wait Action: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins - - -+------------------------------------+--------------------+------------------------+ -| Condition Plugin Name | Creator | Description | -+====================================+====================+========================+ -| `Goal Reached Condition`_ | Carl Delsey | Checks if goal is | -| | | reached within tol. | -+------------------------------------+--------------------+------------------------+ -| `Initial Pose received Condition`_ | Carl Delsey | Checks if initial pose | -| | | has been set | -+------------------------------------+--------------------+------------------------+ -| `Is Stuck Condition`_ | Michael Jeronimo | Checks if robot is | -| | | making progress or | -| | | stuck | -+------------------------------------+--------------------+------------------------+ -| `Transform Available Condition`_ | Steve Macenski | Checks if a TF | -| | | transformation is | -| | | available. When | -| | | succeeds returns | -| | | sucess for subsequent | -| | | calls. | -+------------------------------------+--------------------+------------------------+ - -.. _Goal Reached Condition: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Initial Pose received Condition: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Is Stuck Condition: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Transform Available Condition: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins - -+-----------------------+-------------------+----------------------------------+ -| Decorator Plugin Name | Creator | Description | -+=======================+===================+==================================+ -| `Rate Controller`_ | Michael Jeronimo | Throttles child node to a given | -| | | rate | -+-----------------------+-------------------+----------------------------------+ - -.. _Rate Controller: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins - -+-----------------------+------------------------+----------------------------------+ -| Control Plugin Name | Creator | Description | -+=======================+========================+==================================+ -| `Pipeline Sequence`_ | Carl Delsey | A variant of a sequence node that| -| | | will re-tick previous children | -| | | even if another child is running | -+-----------------------+------------------------+----------------------------------+ -| `Recovery`_ | Carl Delsey | Node must contain 2 children | -| | | and returns success if first | -| | | succeeds. If first fails, the | -| | | second will be ticked. If | -| | | successful, it will retry the | -| | | first and then return its value | -+-----------------------+------------------------+----------------------------------+ -| `Round Robin`_ | Mohammad Haghighipanah | Will tick ``i`` th child until | -| | | a result and move on to ``i+1`` | -+-----------------------+------------------------+----------------------------------+ - -.. _Pipeline Sequence: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Recovery: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins -.. _Round Robin: https://github.com/ros-planning/navigation2/tree/master/nav2_recoveries/plugins diff --git a/sphinx_doc/scripts/.nojekyll b/sphinx_doc/scripts/.nojekyll deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/sphinx_doc/scripts/_nojekyll b/sphinx_doc/scripts/_nojekyll deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/sphinx_doc/scripts/docker/Dockerfile b/sphinx_doc/scripts/docker/Dockerfile deleted file mode 100644 index 9b6747f68a0..00000000000 --- a/sphinx_doc/scripts/docker/Dockerfile +++ /dev/null @@ -1,13 +0,0 @@ -FROM alpine:latest - -#ENV http_proxy -#ENV https_proxy - -RUN apk --no-cache add python3 -RUN python3 -m ensurepip -RUN pip3 install sphinx==1.7.5 docutils==0.14 sphinx_rtd_theme breathe==4.9.1 sphinxcontrib-plantuml -RUN apk --no-cache add make -RUN apk --no-cache add doxygen -RUN apk --no-cache add graphviz -RUN apk --no-cache add ttf-dejavu -RUN apk --no-cache add openjdk8-jre diff --git a/sphinx_doc/scripts/plantuml.jar b/sphinx_doc/scripts/plantuml.jar deleted file mode 100644 index a84c5a0fcdf..00000000000 Binary files a/sphinx_doc/scripts/plantuml.jar and /dev/null differ diff --git a/sphinx_doc/scripts/publish-README.md b/sphinx_doc/scripts/publish-README.md deleted file mode 100644 index 11048566052..00000000000 --- a/sphinx_doc/scripts/publish-README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Documentation Generated by SPHINX -This Documentation was programmatically generated for GitHub Pages. -Do not make changes directly in this repo. Instead, edit content -in the -docs repo, re-generate the HTML with -Sphinx (make html), and push the updated content here for publishing -(make publish). diff --git a/sphinx_doc/scripts/publish-index.html b/sphinx_doc/scripts/publish-index.html deleted file mode 100644 index 11ffbf05ebb..00000000000 --- a/sphinx_doc/scripts/publish-index.html +++ /dev/null @@ -1,10 +0,0 @@ - - -SOF Project documentation - - - - -Please visit the latest SOF documentation - - diff --git a/sphinx_doc/scripts/requirements.txt b/sphinx_doc/scripts/requirements.txt deleted file mode 100644 index 939919ae87e..00000000000 --- a/sphinx_doc/scripts/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -breathe==4.9.1 -sphinx==1.7.5 -docutils==0.14 -sphinx_rtd_theme -sphinxcontrib-plantuml diff --git a/sphinx_doc/substitutions.txt b/sphinx_doc/substitutions.txt deleted file mode 100644 index cc7a2ab752f..00000000000 --- a/sphinx_doc/substitutions.txt +++ /dev/null @@ -1,40 +0,0 @@ -.. |br| raw:: html .. force a line break in HTML output (blank lines needed here) - -
-.. |PN| replace:: Navigation 2 - -.. |LPN| replace:: ROS 2 Navigation - -.. _project repo: https://github.com/ros-planning/navigation2 - -.. _documentation repo: https://github.com/ros-planning/navigation2/doc - -.. _nav2_bringup pkg: https://github.com/ros-planning/navigation2/tree/master/nav2_bringup/bringup - -.. _nav2_params file: https://github.com/ros-planning/navigation2/blob/master/nav2_bringup/bringup/params/nav2_params.yaml - -.. _documentation site: https://rosplanning.github.io/navigation2/ - -.. _project website: https://rosplanning.github.io/navigation2/ - -.. |PP| replace:: https://github.com/ros-planning/navigation2/blob/master - -.. _`ROS 2 binary packages`: https://index.ros.org/doc/ros2/Installation/ - -.. _`official Turtlebot 3 manual`: http://emanual.robotis.com/docs/en/platform/turtlebot3/ros2/#ros2 - -.. These are replacement strings for non-ASCII characters used within the project - using the same name as the html entity names (e.g., ©) for that character - -.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN - :ltrim: -.. |trade| unicode:: U+02122 .. TRADEMARK SIGN - :ltrim: -.. |reg| unicode:: U+000AE .. REGISTERED TRADEMARK SIGN - :ltrim: -.. |deg| unicode:: U+000B0 .. DEGREE SIGN - :ltrim: -.. |plusminus| unicode:: U+000B1 .. PLUS-MINUS SIGN - :rtrim: -.. |micro| unicode:: U+000B5 .. MICRO SIGN - :rtrim: diff --git a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png b/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png deleted file mode 100644 index 8c91a80d588..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png b/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png deleted file mode 100644 index ed5f5d2080d..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png b/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png deleted file mode 100644 index 1cb3a59609d..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png b/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png deleted file mode 100644 index 2475fa6e9cd..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png b/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png deleted file mode 100644 index 42fa031eb8f..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Navigation2_with_SLAM/navigation2_with_slam.gif b/sphinx_doc/tutorials/docs/images/Navigation2_with_SLAM/navigation2_with_slam.gif deleted file mode 100644 index 77eb8a83af3..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Navigation2_with_SLAM/navigation2_with_slam.gif and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_explanation.png b/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_explanation.png deleted file mode 100644 index c4984297658..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_explanation.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_layer_preview.gif b/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_layer_preview.gif deleted file mode 100644 index 289e38207fb..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_layer_preview.gif and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_layer_run.png b/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_layer_run.png deleted file mode 100644 index 900d5a9c575..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Writing_new_Costmap2D_plugin/gradient_layer_run.png and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/images/Writing_new_nav2planner_plugin/nav2_straightline_gif.gif b/sphinx_doc/tutorials/docs/images/Writing_new_nav2planner_plugin/nav2_straightline_gif.gif deleted file mode 100644 index 646c65aff8e..00000000000 Binary files a/sphinx_doc/tutorials/docs/images/Writing_new_nav2planner_plugin/nav2_straightline_gif.gif and /dev/null differ diff --git a/sphinx_doc/tutorials/docs/navigation2_on_real_turtlebot3.rst b/sphinx_doc/tutorials/docs/navigation2_on_real_turtlebot3.rst deleted file mode 100644 index 6b1f910caf0..00000000000 --- a/sphinx_doc/tutorials/docs/navigation2_on_real_turtlebot3.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _navigation2-on-real-turtlebot3: - -Navigating with a Physical Turtlebot 3 -************************************** - -- `Overview`_ -- `Requirements`_ -- `Tutorial Steps`_ - -.. raw:: html - -

-
- -
-

- -Overview -======== - -This tutorial shows how to control and navigate Turtlebot 3 using the ROS2 Navigation2 on a physical Turtlebot 3 robot. -Before completing this tutorials, completing :ref:`getting_started` is highly recommended especially if you are new to ROS and Navigation2. - -This tutorial may take about 1 hour to complete. -It depends on your experience with ROS, robots, and what computer system you have. - -Requirements -============ - -You must install Navigation2, Turtlebot3. -If you don't have them installed, please follow :ref:`getting_started`. - -Tutorial Steps -============== - -0- Setup Your Enviroment Variables ----------------------------------- - -Run the following commands first whenever you open a new terminal during this tutorial. - -- ``source /opt/ros//setup.bash`` -- ``export TURTLEBOT3_MODEL=waffle`` - -1- Launch Turtlebot 3 ---------------------- - -You will need to launch your robot's interface, - - ``ros2 launch turtlebot3_bringup robot.launch.py use_sim_time:=False`` - -2- Launch Navigation2 ---------------------- - -You need to have a map of the environment where you want to Navigate Turtlebot 3, or create one live with SLAM. - -In case you are interested, there is a use case tutorial which shows how to use Navigation2 with SLAM. -`Navigation2 with SLAM `_ - -Required files: - - - ``your-map.map`` - - ``your-map.yaml`` - -``.yaml`` is the configuration file for the map we want to provide Navigation2. -In this case, it has the map resolution value, threshold values for obstacles and free spaces, and a map file location. -You need to make sure these values are correct. -More information about the map.yaml can be found `here `_. - -Launch Navigation 2. If you set autostart:=False, you need to click on the start button in RViz to initialize the nodes. -Make sure `use_sim time` is set to **False**, because we want to use the system time instead of the time simulation time from Gazebo. - -``ros2 launch nav2_bringup bringup_launch.py use_sim_time:=False autostart:=False map:=/path/to/your-map.yaml`` - -Note: Don't forget to change **/path/to/your-map.yaml** to the actual path to the your-map.yaml file. - -3- Launch RVIZ ---------------- - -Launch RVIZ with a pre-defined configuration file. - - ``ros2 run rviz2 rviz2 -d $(ros2 pkg prefix nav2_bringup)/share/nav2_bringup/launch/nav2_default_view.rviz`` - -Now, you should see a shadow of Turtlebot 3 robot model in the center of the plot in Rviz. -Click on the Start button (Bottom Left) if you set the auto_start parameter to false. -Then, the map should appear in RViz. - -.. image:: images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png - :width: 48% -.. image:: images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png - :width: 45% - -4- Initialize the Location of Turtlebot 3 ------------------------------------------ - -First, find where the robot is on the map. Check where your robot is in the room. - -Set the pose of the robot in RViz. -Click on the 2D Pose Estimate button and point the location of the robot on the map. -The direction of the green arrow is the orientation of Turtlebot. - -.. image:: images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png - :width: 700px - :align: center - :alt: Set initial pose in RViz - -Now, the 3D model of Turtlebot should move to that location. -A small error in the estimated location is tolerable. - -5- Send a Goal Pose --------------------- - -Pick a target location for Turtlebot on the map. -You can send Turtlebot 3 a goal position and a goal orientation by using the **Navigation2 Goal** or the **GoalTool** buttons. - -Note: Navigation2 Goal button uses a ROS2 Action to send the goal and the GoalTool publishes the goal to a topic. - -.. image:: images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png - :width: 700px - :align: center - :alt: Send goal pose in RViz - -Once you define the target pose, Navigation2 will find a global path and start navigating the robot on the map. - -.. image:: images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png - :width: 700px - :align: center - :alt: Robot navigating in RViz - -Now, you can see that Turtlebot 3 moves towards the goal position in the room. See the video below. diff --git a/sphinx_doc/tutorials/docs/navigation2_with_slam.rst b/sphinx_doc/tutorials/docs/navigation2_with_slam.rst deleted file mode 100644 index 3c69699e2b1..00000000000 --- a/sphinx_doc/tutorials/docs/navigation2_with_slam.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _navigation2-with-slam: - -(SLAM) Navigating While Mapping -******************************* - -- `Overview`_ -- `Requirements`_ -- `Tutorial Steps`_ - -Overview -======== - -This document explains how to use Navigation 2 with SLAM. -The following steps show ROS 2 users how to generate occupancy grid maps and use Navigation 2 to move their robot around. -This tutorial applies to both simulated and physical robots, but will be completed here on physical robot. - -Before completing this tutorial, completing the :ref:`getting_started`. is highly recommended especially if you are new to ROS and Navigation2. - - -In this tutorial we'll be using SLAM Toolbox. More information can be found in the `ROSCon talk for SLAM Toolbox `_ - -Requirements -============ - -You must install Navigation2, Turtlebot3, and SLAM Toolbox. -If you don't have them installed, please follow :ref:`getting_started`. - -SLAM Toolbox can be installed via: - - ``sudo apt install ros--slam-toolbox`` - -or from built from source in your workspace with: - - ``git clone -b -devel git@github.com:stevemacenski/slam_toolbox.git`` - - -Tutorial Steps -============== - -0- Launch Robot Interfaces --------------------------- - -For this tutorial, we will use the turtlebot3. -If you have another robot, replace with suitable instructions. - -Run the following commands first whenever you open a new terminal during this tutorial. - -- ``source /opt/ros//setup.bash`` -- ``export TURTLEBOT3_MODEL=waffle`` - - -Launch your robot's interface and robot state publisher, - - ``ros2 launch turtlebot3_bringup robot.launch.py`` - -1- Launch Navigation2 ---------------------- - -Launch Navigation without nav2_amcl and nav2_map_server. -It is assumed that the SLAM node(s) will publish to /map topic and provide the map->odom transform. - - ``ros2 launch nav2_bringup nav2_navigation_launch.py`` - -2- Launch SLAM --------------- - -Bring up your choice of SLAM implementation. -Make sure it provides the map->odom transform and /map topic. -Run Rviz and add the topics you want to visualize such as /map, /tf, /laserscan etc. -For this tutorial, we will use `SLAM Toolbox `_. - - - ``ros2 launch slam_toolbox online_async_launch.py`` - -3- Working with SLAM --------------------- - -Move your robot by requesting a goal through RViz or the ROS2 CLI, ie: - -.. code-block:: bash - - ros2 topic pub /goal_pose geometry_msgs/PoseStamped "{header: {stamp: {sec: 0}, frame_id: 'map'}, pose: {position: {x: 0.2, y: 0.0, z: 0.0}, orientation: {w: 1.0}}}" - -You should see the map update live! To save this map to file: - - ``ros2 run nav2_map_server map_saver -f ~/map`` - -.. image:: images/Navigation2_with_SLAM/navigation2_with_slam.gif - :width: 700px - :alt: Navigation2 with SLAM - :align: center diff --git a/sphinx_doc/tutorials/docs/navigation2_with_stvl.rst b/sphinx_doc/tutorials/docs/navigation2_with_stvl.rst deleted file mode 100644 index cb7d111fdf4..00000000000 --- a/sphinx_doc/tutorials/docs/navigation2_with_stvl.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. _stvl: - -(STVL) Using an External Costmap Plugin -*************************************** - -- `Overview`_ -- `Costmap2D and STVL`_ -- `Tutorial Steps`_ - -.. raw:: html - -

-
- -
-

- -Overview -======== - -This tutorial shows how to load and use an external plugin. -This example uses the `Spatio Temporal Voxel Layer `_ (STVL) costmap `pluginlib `_ plugin as an example. -STVL is a demonstrative pluginlib plugin and the same process can be followed for other costmap plugins as well as plugin planners, controllers, and recoveries. - -Before completing this tutorial, please look at the previous two tutorials on navigation in simulation and physical hardware, if available. -This tutorial assumes knowledge of navigation and basic understanding of costmaps. - -Costmap2D and STVL -================== - -Costmap 2D is the data object we use to buffer sensor information into a global view that the robot will use to create plans and control efforts. -Within Costmap2D, there are pluginlib plugin interfaces available to create custom behaviors loadable at runtime. -Examples of included pluginlib plugins for Costmap2D are the Obstacle Layer, Voxel Layer, Static Layer, and Inflation Layer. - -However, these are simply example plugins offered by the base implementation. -Another available pluginlib plugin for Costmap2D in Navigation2 is STVL. - -STVL is another 3D perception plugin similar to the Voxel Layer. -A more detailed overview of how it works can be found `in this repo `_, however it buffers 3D data from depth cameras, sonars, lidars, and more into a sparse volumetic world model and removes voxels over time proportional with a sensor model and time-based expiration. -This can be especially useful for robots in highly dynamic envrionments and decreases the resource utilization for 3D sensor processing by up to 2x. -STVL also treats 3D lidars and radars as first class citizens for support. -The ROSCon talk for STVL can be found `in this video `_. - -Tutorial Steps -============== - -0- Setup --------- - -Follow the same process as in :ref:`getting_started` for installing and setting up a robot for hardware testing or simulation, as applicable. Ensure ROS2, Navigation2, and Gazebo are installed. - -1- Install STVL ---------------- - -STVL can be installed in ROS2 via the ROS Build Farm: - -- ``sudo apt install ros--spatio-temporal-voxel-layer`` - -It can also be built from source by cloning the repository into your Navigation2 workspace: - -- ``git clone -b -devel git@github.com:stevemacenski/spatio_temporal_voxel_layer`` - -1- Modify Navigation2 Parameter -------------------------------- - -STVL is an optional plugin, like all plugins, in Costmap2D. Costmap Plugins in Navigation2 are loaded in the ``plugin_names`` and ``plugin_types`` variables inside of their respective costmaps. -For example, the following will load the static and obstacle layer plugins into the name ``static_layer`` and ``obstacle_layer``, respectively: - -.. code-block:: yaml - - global_costmap: - global_costmap: - ros__parameters: - use_sim_time: True - plugin_names: ["static_layer", "obstacle_layer"] - plugin_types: ["nav2_costmap_2d::StaticLayer", "nav2_costmap_2d::ObstacleLayer"] - -To load the STVL plugin, a new plugin name and type must be added. -For example, if the application required an STVL layer and no obstacle layer, our file would be: - -.. code-block:: yaml - - global_costmap: - global_costmap: - ros__parameters: - use_sim_time: True - plugin_names: ["static_layer", "stvl_layer"] - plugin_types: ["nav2_costmap_2d::StaticLayer", "spatio_temporal_voxel_layer/SpatioTemporalVoxelLayer"] - -Similar to the Voxel Layer, after registering the plugin, we can add the configuration of the STVL layer under the namespace ``stvl_layer``. -An example fully-described parameterization of an STVL configuration is: - -.. code-block:: yaml - - stvl_layer: - enabled: true - voxel_decay: 15. - decay_model: 0 - voxel_size: 0.05 - track_unknown_space: true - max_obstacle_height: 2.0 - unknown_threshold: 15 - mark_threshold: 0 - update_footprint_enabled: true - combination_method: 1 - obstacle_range: 3.0 - origin_z: 0.0 - publish_voxel_map: true - transform_tolerance: 0.2 - mapping_mode: false - map_save_duration: 60.0 - observation_sources: pointcloud - pointcloud: - data_type: PointCloud2 - topic: /intel_realsense_r200_depth/points - marking: true - clearing: true - min_obstacle_height: 0.0 - max_obstacle_height: 2.0 - expected_update_rate: 0.0 - observation_persistence: 0.0 - inf_is_valid: false - voxel_filter: false - clear_after_reading: true - max_z: 7.0 - min_z: 0.1 - vertical_fov_angle: 0.8745 - horizontal_fov_angle: 1.048 - decay_acceleration: 15.0 - model_type: 0 - -Please copy-paste the text above, with the ``plugin_names`` and ``plugin_types`` registration, into your ``nav2_params.yaml`` to enable STVL in your application. -Make sure to change both the local and global costmaps. - -Note: Pluginlib plugins for other Navigation2 servers such as planning, recovery, and control can be set in this same way. - -2- Launch Navigation2 ---------------------- - -Follow the same process as in :ref:`getting_started` to launch a simulated robot in gazebo with Navigation2. -Navigation2 is now using STVL as its 3D sensing costmap layer. - -3- RVIZ --------- - -With RViz open and ``publish_voxel_map: true``, you can visualize the underlying data structure's 3D grid using the ``{local, global}_costmap/voxel_grid`` topics. -Note: It is recommended in RViz to set the ``PointCloud2`` Size to your voxel size and the style to ``Boxes`` with a neutral color for best visualization. diff --git a/sphinx_doc/tutorials/docs/writing_new_costmap2d_plugin.rst b/sphinx_doc/tutorials/docs/writing_new_costmap2d_plugin.rst deleted file mode 100644 index 92bd2a47deb..00000000000 --- a/sphinx_doc/tutorials/docs/writing_new_costmap2d_plugin.rst +++ /dev/null @@ -1,247 +0,0 @@ -.. _writing_new_costmap2d_plugin: - -Writing a New Costmap2D Plugin -****************************** - -- `Overview`_ -- `Requirements`_ -- `Tutorial Steps`_ - -.. image:: images/Writing_new_Costmap2D_plugin/gradient_layer_preview.gif - :width: 700px - :align: center - :alt: Animated gif with gradient demo - -Overview -======== - -This tutorial shows how to create your own simple `plugin `_ for Costmap2D. - -Before starting the tutorial, please check this `video `_ which contains information about Costmap2D layers design and plugins basic operational principals. - -Requirements -============ - -It is assumed that ROS2, Gazebo and TurtleBot3 packages are installed or built locally. Please make sure that Navigation2 project is also built locally as it was made in :ref:`build-instructions`. - -Tutorial Steps -============== - -1- Write a new Costmap2D plugin -------------------------------- - -For a demonstration, this example will creates a costmap plugin that puts repeating costs gradients in the costmap. -The annotated code for this tutorial can be found in `navigation2_tutorials `_ repository as the ``nav2_gradient_costmap_plugin`` ROS2-package. -Please refer to it when making your own layer plugin for Costmap2D. - -The plugin class ``nav2_gradient_costmap_plugin::GradientLayer`` is inherited from basic class ``nav2_costmap_2d::Layer``: - -.. code-block:: c - - namespace nav2_gradient_costmap_plugin - { - - class GradientLayer : public nav2_costmap_2d::Layer - -The basic class provides the set of virtual methods API for working with costmap layers in a plugin. These methods are calling in runtime by ``LayeredCostmap``. The list of methods, their description and necessity to have these methods in plugin's code is presented in the table below: - -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| **Virtual method** | **Method description** | **Requires override?** | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| onInitialize() | Method is called at the end of plugin initialization. There is usually | No | -| | declarations of ROS parameters. This is where any required initialization | | -| | should occur. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| updateBounds() | Method is called to ask the plugin: which area of costmap layer it needs | Yes | -| | to update. There are 3 input parameters of method: robot position and | | -| | orientation and 4 output parameters: pointers to window bounds. | | -| | These bounds are used for performance reasons: to update the area | | -| | inside the window where is new info available, avoiding updates of whole | | -| | costmap on every iteration. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| updateCosts() | Method is called each time when costmap re-calculation is required. It | Yes | -| | updates the costmap layer only within its bounds window. There are 4 input | | -| | parameters of method: calculation window bounds and 1 output parameter: | | -| | reference to a resulting costmap ``master_grid``. The ``Layer`` class | | -| | provides the plugin with an internal costmap, ``costmap_``, for updates. | | -| | The ``master_grid`` should be updated with values within the window bounds | | -| | using one of the following update methods: ``updateWithAddition()``, | | -| | ``updateWithMax()``, ``updateWithOverwrite()`` or | | -| | ``updateWithTrueOverwrite()``. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| matchSize() | Method is called each time when map size was changed. | No | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| onFootprintChanged() | Method is called each time when footprint was changed. | No | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| reset() | It may have any code to be executed during costmap reset. | Yes | -+----------------------+----------------------------------------------------------------------------+-------------------------+ - -In our example these methods have the following functionality: - -1. ``GradientLayer::onInitialize()`` contains declaration of ROS parameter with its default value: - -.. code-block:: c - - declareParameter("enabled", rclcpp::ParameterValue(true)); - node_->get_parameter(name_ + "." + "enabled", enabled_); - -and sets ``need_recalculation_`` bounds recalculation indicator: - -.. code-block:: c - - need_recalculation_ = false; - -2. ``GradientLayer::updateBounds()`` re-calculates window bounds if ``need_recalculation_`` is ``true`` and updates them regardless of ``need_recalculation_`` value. - -3. ``GradientLayer::updateCosts()`` - in this method the gradient is writing directly to the resulting costmap ``master_grid`` without merging with previous layers. This is equal to working with internal ``costmap_`` and then calling ``updateWithTrueOverwrite()`` method. Here is the gradient making algorithm for master costmap: - -.. code-block:: c - - int gradient_index; - for (int j = min_j; j < max_j; j++) { - // Reset gradient_index each time when reaching the end of re-calculated window - // by OY axis. - gradient_index = 0; - for (int i = min_i; i < max_i; i++) { - int index = master_grid.getIndex(i, j); - // setting the gradient cost - unsigned char cost = (LETHAL_OBSTACLE - gradient_index*GRADIENT_FACTOR)%255; - if (gradient_index <= GRADIENT_SIZE) { - gradient_index++; - } else { - gradient_index = 0; - } - master_array[index] = cost; - } - } - -where the ``GRADIENT_SIZE`` is the size of each gradient period in map cells, ``GRADIENT_FACTOR`` - decrement of costmap's value per each step: - -.. image:: images/Writing_new_Costmap2D_plugin/gradient_explanation.png - -These parameters are defined in plugin's header file. - -4. ``GradientLayer::onFootprintChanged()`` just resets ``need_recalculation_`` value. - -5. ``GradientLayer::reset()`` method is dummy: it is not used in this example plugin. It remaining there since pure virtual function ``reset()`` in parent ``Layer`` class required to be overriden. - -2- Export and make GradientLayer plugin ---------------------------------------- - -The written plugin will be loaded in runtime as it's basic parent class and then will be called by plugin handling modules (for costmap2d by ``LayeredCostmap``). Pluginlib opens a given plugin in run-time and provides methods from exported classes to be callable. The mechanism of class exporting tells pluginlib which basic class should be used during these calls. This allows to extend an application by plugins without knowing application source code or recompiling it. - -In our example the ``nav2_gradient_costmap_plugin::GradientLayer`` plugin's class should be dynamically loaded as a ``nav2_costmap_2d::Layer`` basic class. For this the plugin should be registered as follows: - -1. Plugin's class should be registered with a basic type of loaded class. For this there is a special macro ``PLUGINLIB_EXPORT_CLASS`` should be added to any source-file composing the plugin library: - -.. code-block:: text - - #include "pluginlib/class_list_macros.hpp" - PLUGINLIB_EXPORT_CLASS(nav2_gradient_costmap_plugin::GradientLayer, nav2_costmap_2d::Layer) - -This part is usually placed at the end of cpp-file where the plugin class was written (in our example ``gradient_layer.cpp``). It is good practice to place these lines at the end of the file but technically, you can also place at the top. - -2. Plugin's inormation should be stored to plugin description file. This is done by using separate XML (in our example ``gradient_plugins.xml``) in the plugin's package. This file contains information about: - - - ``path``: Path and name of library where plugin is placed. - - ``name``: Plugin type referenced in ``plugin_types`` parameter (see next section for more details). It could be whatever you want. - - ``type``: Plugin class with namespace taken from the source code. - - ``basic_class_type``: Basic parent class from which plugin class was derived. - - ``description``: Plugin description in a text form. - -.. code-block:: xml - - - - This is an example plugin which puts repeating costs gradients to costmap - - - -The export of plugin is performed by including ``pluginlib_export_plugin_description_file()`` cmake-function into ``CMakeLists.txt``. This function installs plugin description file into ``share`` directory and sets ament indexes for plugin description XML to be discoverable as a plugin of selected type: - -.. code-block:: text - - pluginlib_export_plugin_description_file(nav2_costmap_2d gradient_layer.xml) - -Plugin description file is also should be added to ``package.xml``. ``costmap_2d`` is the package of the interface definition, for our case ``Layer``, and requires a path to the xml file: - -.. code-block:: text - - - - ... - - -After everything is done put the plugin package into ``src`` directory of a certain ROS2-workspace, build the plugin package (``colcon build --packages-select nav2_gradient_costmap_plugin --symlink-install``) and source ``setup.bash`` file when it necessary. - -Now the plugin is ready to use. - -3- Enable the plugin in Costmap2D ---------------------------------- - -At the next step it is required to tell Costmap2D about new plugin. For that the plugin should be added to ``plugin_names`` and ``plugin_types`` lists in ``nav2_params.yaml`` optionally for ``local_costmap``/``global_costmap`` in order to be enabled in run-time for Controller/Planner Server. ``plugin_names`` list contains the names of plugin objects. These names could be anything you want. ``plugin_types`` contains types of listed in ``plugin_names`` objects. These types should correspond to ``name`` field of plugin class specified in plugin description XML-file. - -For example: - -.. code-block:: diff - - --- a/nav2_bringup/bringup/params/nav2_params.yaml - +++ b/nav2_bringup/bringup/params/nav2_params.yaml - @@ -124,8 +124,8 @@ local_costmap: - width: 3 - height: 3 - resolution: 0.05 - - plugin_names: ["obstacle_layer", "voxel_layer", "inflation_layer"] - - plugin_types: ["nav2_costmap_2d::ObstacleLayer", "nav2_costmap_2d::VoxelLayer", "nav2_costmap_2d::InflationLayer"] - + plugin_names: ["obstacle_layer", "voxel_layer", "gradient_layer"] - + plugin_types: ["nav2_costmap_2d::ObstacleLayer", "nav2_costmap_2d::VoxelLayer", "nav2_gradient_costmap_plugin/GradientLayer"] - robot_radius: 0.22 - inflation_layer: - cost_scaling_factor: 3.0 - @@ -171,8 +171,8 @@ global_costmap: - robot_base_frame: base_link - global_frame: map - use_sim_time: True - - plugin_names: ["static_layer", "obstacle_layer", "voxel_layer", "inflation_layer"] - - plugin_types: ["nav2_costmap_2d::StaticLayer", "nav2_costmap_2d::ObstacleLayer", "nav2_costmap_2d::VoxelLayer", "nav2_costmap_2d::InflationLayer"] - + plugin_names: ["static_layer", "obstacle_layer", "voxel_layer", "gradient_layer"] - + plugin_types: ["nav2_costmap_2d::StaticLayer", "nav2_costmap_2d::ObstacleLayer", "nav2_costmap_2d::VoxelLayer", "nav2_gradient_costmap_plugin/GradientLayer"] - robot_radius: 0.22 - resolution: 0.05 - obstacle_layer: - -YAML-file may also contain the list of parameters (if any) for each plugin, identified by plugins object name. - -NOTE: there could be many simultaneously loaded plugin objects of one type. For this, ``plugin_names`` list should contain different plugins names whether the ``plugin_types`` will remain the same types. For example: - -.. code-block:: text - - plugin_names: ["obstacle_layer", "gradient_layer_1", "gradient_layer_2"] - plugin_types: ["nav2_costmap_2d::ObstacleLayer", "nav2_gradient_costmap_plugin/GradientLayer", "nav2_gradient_costmap_plugin/GradientLayer"] - -In this case each plugin object will be handled by its own parameters tree in a YAML-file, like: - -.. code-block:: text - - gradient_layer_1: - enabled: True - ... - gradient_layer_2: - enabled: False - ... - -4- Run GradientLayer plugin ---------------------------- - -Run Turtlebot3 simulation with enabled navigation2. Detailed instructuction how to make it are written at :ref:`getting_started`. Below is shortcut command for that: - -.. code-block:: bash - - $ ros2 launch nav2_bringup tb3_simulation_launch.py - -Then goto RViz and click on the "2D Pose Estimate" button at the top and point the location on map as it was described in :ref:`getting_started`. Robot will be localized on map and the result should be as presented at picture below. There is could be seen the gradient costmap. There are also 2 noticeable things: dynamically updated by ``GradientLayer::updateCosts()`` costmap within its bounds and global path curved by gradient: - -.. image:: images/Writing_new_Costmap2D_plugin/gradient_layer_run.png - :width: 700px - :align: center - :alt: Image of gradient costmap used diff --git a/sphinx_doc/tutorials/docs/writing_new_nav2planner_plugin.rst b/sphinx_doc/tutorials/docs/writing_new_nav2planner_plugin.rst deleted file mode 100644 index dd9cee07270..00000000000 --- a/sphinx_doc/tutorials/docs/writing_new_nav2planner_plugin.rst +++ /dev/null @@ -1,227 +0,0 @@ -.. _writing_new_nav2planner_plugin: - -Writing a New Planner Plugin -**************************** - -- `Overview`_ -- `Requirements`_ -- `Tutorial Steps`_ - -.. image:: images/Writing_new_nav2planner_plugin/nav2_straightline_gif.gif - :width: 700px - :align: center - :alt: Animated gif with gradient demo - -Overview -======== - -This tutorial shows how to create you own planner plugin. - -Requirements -============ - -- ROS2 (binary or build-from-source) -- Navigation2 (Including dependencies) -- Gazebo -- Turtlebot3 - -Tutorial Steps -============== - -1- Creating a new Planner Plugin --------------------------------- - -We will create a simple straight line planner. -The annotated code in this tutorial can be found in `navigation_tutorials `_ repository as the ``nav2_straightline_planner`` -This package can be a considered as a reference for writing planner plugin. - -Our example plugin inherits from the base class ``nav2_core::GlobalPlanner``. The base class provides 5 pure virtual methods to implement a planner plugin. The plugin will be used by the planner server to compute trajectories. -Lets learn more about the methods needed to write a planner plugin. - -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| **Virtual method** | **Method description** | **Requires override?** | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| configure() | Method is called at when planner server enters on_configure state. Ideally | Yes | -| | this methods should perform declarations of ROS parameters and | | -| | initialization of planner's member variables. This method takes 4 input | | -| | params: shared pointer to parent node, planner name, tf buffer pointer and | | -| | shared pointer to costmap. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| activate() | Method is called when planner server enters on_activate state. Ideally this| Yes | -| | method should implement operations which are neccessary before planner goes| | -| | to an active state. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| deactivate() | Method is called when planner server enters on_deactivate state. Ideally | Yes | -| | this method should implement operations which are neccessary before planner| | -| | goes to an inactive state. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| cleanup() | Method is called when planner server goes to on_cleanup state. Ideally this| Yes | -| | method should clean up resoures which are created for the planner. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ -| createPlan() | Method is called when planner server demands a global plan for specified | Yes | -| | start and goal pose. This method returns `nav_msgs::msg::Path` carrying | | -| | global plan. This method takes 2 input parmas: start pose and goal pose. | | -+----------------------+----------------------------------------------------------------------------+-------------------------+ - -For this tutorial, we will be using methods ``StraightLine::configure()`` and ``StraightLine::createPlan()`` to create straight line planner. - -In planners, ``configure()`` method must set member variables from ROS parameters and any initialization required, - -.. code-block:: c++ - - node_ = parent; - tf_ = tf; - name_ = name; - costmap_ = costmap_ros->getCostmap(); - global_frame_ = costmap_ros->getGlobalFrameID(); - - // Parameter initialization - nav2_util::declare_parameter_if_not_declared(node_, name_ + ".interpolation_resolution", rclcpp::ParameterValue(0.1)); - node_->get_parameter(name_ + ".interpolation_resolution", interpolation_resolution_); - -Here, ``name_ + ".interpolation_resolution"`` is fetching the ROS parameters ``interpolation_resolution`` which is specific to our planner. Navigation2 allows loading of multiple plugins and to keep things organized each plugin is mapped to some ID/name. Now if we want to retrieve the parameters for that specific plugin, we use ``.`` as done in the above snippet. For example, our example planner is mapped to the name "GridBased" and to retrieve the ``interpolation_resolution`` parameter which is specific to "GridBased", we used ``Gridbased.interpolation_resolution``. In other words, ``GridBased`` is used as a namespace for plugin-specific parameters. We will see more on this when we discuss the parameters file (or params file). - -In ``createPlan()`` method, we need to create a path from the given start to goal poses. The ``StraightLine::createPlan()`` is called using start pose and goal pose to solve the global path planning problem. Upon succeeding, it converts the path to the ``nav_msgs::msg::Path`` and returns to the planner server. Below annotation shows the implementation of this method. - -.. code-block:: c++ - - nav_msgs::msg::Path global_path; - - // Checking if the goal and start state is in the global frame - if (start.header.frame_id != global_frame_) { - RCLCPP_ERROR( - node_->get_logger(), "Planner will only except start position from %s frame", - global_frame_.c_str()); - return global_path; - } - - if (goal.header.frame_id != global_frame_) { - RCLCPP_INFO( - node_->get_logger(), "Planner will only except goal position from %s frame", - global_frame_.c_str()); - return global_path; - } - - global_path.poses.clear(); - global_path.header.stamp = node_->now(); - global_path.header.frame_id = global_frame_; - // calculating the number of loops for current value of interpolation_resolution_ - int total_number_of_loop = std::hypot( - goal.pose.position.x - start.pose.position.x, - goal.pose.position.y - start.pose.position.y) / - interpolation_resolution_; - double x_increment = (goal.pose.position.x - start.pose.position.x) / total_number_of_loop; - double y_increment = (goal.pose.position.y - start.pose.position.y) / total_number_of_loop; - - for (int i = 0; i < total_number_of_loop; ++i) { - geometry_msgs::msg::PoseStamped pose; - pose.pose.position.x = start.pose.position.x + x_increment * i; - pose.pose.position.y = start.pose.position.y + y_increment * i; - pose.pose.position.z = 0.0; - pose.pose.orientation.x = 0.0; - pose.pose.orientation.y = 0.0; - pose.pose.orientation.z = 0.0; - pose.pose.orientation.w = 1.0; - pose.header.stamp = node_->now(); - pose.header.frame_id = global_frame_; - global_path.poses.push_back(pose); - } - - global_path.poses.push_back(goal); - - return global_path; - -The remaining methods are not used but its mandatory to override them. As per the rules, we did override all but left them blank. - -2- Exporting the planner plugin -------------------------------- - -Now that we have created our custom planner, we need to export our planner plugin so that it would be visible to the planner server. Plugins are loaded at runtime and if they are not visible, then our planner server won't be able to load it. In ROS2, exporting and loading plugins is handled by ``pluginlib``. - -Coming to our tutorial, class ``nav2_straightline_planner::StraightLine`` is loaded dynamically as ``nav2_core::GlobalPlanner`` which is our base class. - -1. To export the planner, we need to provide two lines - -.. code-block:: c++ - - #include "pluginlib/class_list_macros.hpp" - PLUGINLIB_EXPORT_CLASS(nav2_straightline_planner::StraightLine, nav2_core::GlobalPlanner) - -Note that it requires pluginlib to export out plugin's class. Pluginlib would provide as macro ``PLUGINLIB_EXPORT_CLASS`` which does all the work of exporting. - -It is good practice to place these lines at the end of the file but technically, you can also write at the top. - -2. Next step would be to create plugin's description file in the root directory of the package. For example, ``global_planner_plugin.xml`` file in our tutorial package. This file contains following information - - - ``library path``: Plugin's library name and it's location. - - ``class name``: Name of the class. - - ``class type``: Type of class. - - ``base class``: Name of the base class. - - ``description``: Description of the plugin. - -.. code-block:: xml - - - - This is an example plugin which produces straight path. - - - -3. Next step would be to export plugin using ``CMakeLists.txt`` by using cmake function ``pluginlib_export_plugin_description_file()``. This function installs plugin description file to ``share`` directory and sets ament indexes to make it discoverable. - -.. code-block:: text - - pluginlib_export_plugin_description_file(nav2_core global_planner_plugin.xml) - -4. Plugin description file should also be added to ``package.xml`` - -.. code-block:: xml - - - ament_cmake - - - -5. Compile and it should be registered. Next, we'll use this plugin. - -3- Pass the plugin name through params file -------------------------------------------- - -To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below - -replace following params - -.. code-block:: text - - planner_server: - ros__parameters: - planner_plugin_types: ["nav2_navfn_planner/NavfnPlanner"] - planner_plugin_ids: ["GridBased"] - use_sim_time: True - GridBased.tolerance: 2.0 - GridBased.use_astar: false - GridBased.allow_unknown: true - -with - -.. code-block:: text - - planner_server: - ros__parameters: - planner_plugin_types: ["nav2_straightline_planner/StraightLine"] - planner_plugin_ids: ["GridBased"] - use_sim_time: True - GridBased.interpolation_resolution: 0.1 - -In the above snippet, you can observe the mapping of our ``nav2_straightline_planner/StraightLine`` planner to its id ``GridBased``. To pass plugin-specific parameters we have used ``.``. - -4- Run StraightLine plugin ---------------------------- - -Run Turtlebot3 simulation with enabled navigation2. Detailed instruction how to make it are written at :ref:`getting_started`. Below is shortcut command for that: - -.. code-block:: bash - - $ ros2 launch nav2_bringup tb3_simulation_launch.py params_file:=/path/to/your_params_file.yaml - -Then goto RViz and click on the "2D Pose Estimate" button at the top and point the location on map as it was described in :ref:`getting_started`. Robot will localize on the map and then click on "Navigation2 goal" and click on the pose where you want your planner to consider a goal pose. After that planner will plan the path and robot will start moving towards the goal. diff --git a/sphinx_doc/tutorials/index.rst b/sphinx_doc/tutorials/index.rst deleted file mode 100644 index 3c5777d474f..00000000000 --- a/sphinx_doc/tutorials/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _tutorials: - -Tutorials -######### - -Navigation2 Tutorials - -.. toctree:: - :maxdepth: 1 - - docs/navigation2_on_real_turtlebot3.rst - docs/navigation2_with_slam.rst - docs/navigation2_with_stvl.rst - docs/writing_new_costmap2d_plugin.rst - docs/writing_new_nav2planner_plugin.rst