diff --git a/.circleci/config.yml b/.circleci/config.yml index fb1d1ef6e0..549f3d3945 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -6,51 +6,32 @@ references: path: . setup_doc_dependencies: &setup_doc_dependencies run: - name: Install documentation dependencies + name: Install Doc Dependencies command: | export DEBIAN_FRONTEND=noninteractive apt update apt install -y \ + doxygen \ git \ + graphviz \ + make \ + openjdk-8-jre \ openssh-server \ python3-pip \ - python3-venv - python3 -m venv /nav2_docs/venv - . /nav2_docs/venv/bin/activate + ttf-dejavu pip3 install -r requirements.txt - build_docs: &build_docs + make_docs: &make_docs run: - name: Build documentation command: | - . /nav2_docs/venv/bin/activate - mkdocs build - store_built_docs: &store_built_docs + make html + store_docs: &store_docs store_artifacts: - path: ./site - destination: build_site + path: _build/html + destination: html publish_docs: &publish_docs run: - name: Deploy documentation command: | - # Set up git configuration - git config user.name ci - git config user.email ci@noreply.com - - . /nav2_docs/venv/bin/activate - - TITLE=${CIRCLE_BRANCH^} - mike deploy $CIRCLE_BRANCH --title=$TITLE --push --allow-empty \ - --message "[skip ci] Deployed $CIRCLE_SHA1 to $CIRCLE_BRANCH" - - # Set default version only once - if ! git cat-file -e origin/gh-pages:index.html; then - mike set-default rolling --push - echo "The default version is set to Rolling" - fi - store_published_docs: &store_published_docs - store_artifacts: - path: ./site - destination: publish_site + make publish install_deployment_key: &install_deployment_key add_ssh_keys: fingerprints: @@ -61,21 +42,20 @@ commands: description: "Install documentation dependencies" steps: - *setup_doc_dependencies - build_and_store_docs: - description: "Build and store docs" + build_docs: + description: "Build docs" steps: - - *build_docs - - *store_built_docs - publish_and_store_docs: - description: "Commit newly built docs to gh-pages branch and store the build result" + - *make_docs + - *store_docs + publish_docs_to_gh_pages_branch: + description: "Commit newly built docs to gh-pages branch" steps: - *publish_docs - - *store_published_docs executors: docs_exec: docker: - - image: ubuntu:noble + - image: ubuntu:focal working_directory: /nav2_docs jobs: @@ -84,30 +64,29 @@ jobs: steps: - *on_checkout - install_doc_dependencies - - build_and_store_docs + - build_docs + - persist_to_workspace: + root: . + paths: + - _build docs_publish: executor: docs_exec steps: - *on_checkout - install_doc_dependencies - *install_deployment_key - - publish_and_store_docs + - attach_workspace: + at: . + - publish_docs_to_gh_pages_branch workflows: - build_docs: - jobs: - - docs_build: - filters: - branches: - ignore: - - rolling - publish_docs: + version: 2 + build_and_publish_docs: jobs: + - docs_build - docs_publish: - # 'serial-group' prevents gh-pages push conflicts when multiple branches deploy simultaneously. - # Serial group ensures only one docs_publish job runs at a time across the org. - serial-group: << pipeline.project.slug >>/gh-pages-deploy + requires: + - docs_build filters: branches: - only: - - rolling + only: master diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 22b9334947..d80daf3415 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -12,6 +12,7 @@ "extensions": [ "eamodio.gitlens", "esbenp.prettier-vscode", + "GitHub.copilot", "streetsidesoftware.code-spell-checker" ] } diff --git a/.dockerignore b/.dockerignore index 3da882461e..111b0017b7 100644 --- a/.dockerignore +++ b/.dockerignore @@ -10,4 +10,4 @@ .vscode/ **.Dockerfile **Dockerfile -site +_build/ diff --git a/.github/mergify.yml b/.github/mergify.yml deleted file mode 100644 index 56c49aa7da..0000000000 --- a/.github/mergify.yml +++ /dev/null @@ -1,37 +0,0 @@ -merge_queue: - queue_controls_comment: false - -pull_request_rules: - - name: backport to jazzy at reviewers discretion - conditions: - - base=rolling - - "label=backport-jazzy" - actions: - backport: - branches: - - jazzy - - - name: backport to lyrical at reviewers discretion - conditions: - - base=rolling - - "label=backport-lyrical" - actions: - backport: - branches: - - lyrical - - - name: ask to resolve conflict - conditions: - - conflict - - author!=mergify - actions: - comment: - message: This pull request is in conflict. Could you fix it @{{author}}? - - - name: circleci build failures - conditions: - - "check-failure=ci/circleci: docs_build" - actions: - comment: - message: | - @{{author}}, your PR has failed to build. Please check CI outputs and resolve issues. diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml new file mode 100644 index 0000000000..65669afcc6 --- /dev/null +++ b/.github/workflows/claude.yml @@ -0,0 +1,53 @@ +name: Claude PR Assistant + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude-code-action: + if: | + ( + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) + ) && ( + github.actor == 'SteveMacenski' || + github.actor == 'tonynajjar' || + github.actor == 'ruffsl' || + github.actor == 'doisyg' || + github.actor == 'padhupradheep' + ) + + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v7 + with: + fetch-depth: 1 + + - name: Run Claude PR Action + uses: grll/claude-code-action@beta + with: + use_oauth: true + claude_access_token: ${{ secrets.CLAUDE_ACCESS_TOKEN }} + claude_refresh_token: ${{ secrets.CLAUDE_REFRESH_TOKEN }} + claude_expires_at: ${{ secrets.CLAUDE_EXPIRES_AT }} + secrets_admin_pat: ${{ secrets.SECRETS_ADMIN_PAT }} + allowed_tools: | + Bash + timeout_minutes: "60" + model: "claude-sonnet-4-20250514" + # direct_prompt: provide prompt information, probably more useful if this job is split into many. Reviewer, implementer, Q&A answerer, etc so that each have their own context diff --git a/.github/workflows/claude_oath.yml b/.github/workflows/claude_oath.yml new file mode 100644 index 0000000000..750676c947 --- /dev/null +++ b/.github/workflows/claude_oath.yml @@ -0,0 +1,21 @@ +name: Claude OAuth + +on: + workflow_dispatch: + inputs: + code: + description: 'Authorization code (leave empty for step 1)' + required: false + +permissions: + actions: write # Required for cache management + contents: read # Required for basic repository access + +jobs: + auth: + runs-on: ubuntu-latest + steps: + - uses: grll/claude-code-login@v1 + with: + code: ${{ inputs.code }} + secrets_admin_pat: ${{ secrets.SECRETS_ADMIN_PAT }} diff --git a/.github/workflows/precommit.yaml b/.github/workflows/precommit.yaml index c572f4388d..07313072e4 100644 --- a/.github/workflows/precommit.yaml +++ b/.github/workflows/precommit.yaml @@ -4,8 +4,7 @@ name: pre-commit on: pull_request: push: - branches: - - rolling + branches: [main] jobs: pre-commit: diff --git a/.gitignore b/.gitignore index 9a01a1bca7..5936c36229 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ -venv -site -__pycache__ - -macros/cache/* -!macros/cache/README.md +_build +lib/ +bin/ +pyvenv.cfg +.DS_Store +venv/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 27b881831b..dcbbb5a891 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -16,14 +16,14 @@ repos: # Spellcheck in comments and docs # skipping of *.svg files is not working... - repo: https://github.com/codespell-project/codespell - rev: v2.4.2 + rev: v2.3.0 hooks: - id: codespell args: ['--write-changes', '--ignore-words=.codespell_words'] - exclude: \.(svg|pyc|drawio|dcf|eds)$ + exclude: CHANGELOG\.rst|\.(svg|pyc|drawio|dcf|eds)$ - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v6.0.0 + rev: v5.0.0 hooks: - id: end-of-file-fixer - id: mixed-line-ending diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 3312e0d2c7..d654a782f6 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -4,44 +4,32 @@ "version": "2.0.0", "tasks": [ { - "label": "Create venv", - "type": "shell", - "command": "python3", - "args": ["-m", "venv", "venv"], - "problemMatcher": [] - }, - { - "label": "Install dependencies", - "type": "shell", - "command": "${workspaceFolder}/venv/bin/pip", - "args": ["install", "-r", "requirements.txt"], - "dependsOn": ["Create venv"], - "problemMatcher": [] - }, - { - "label": "Build Nav2 Docs", + "label": "Build", + "icon": { + "id": "gear" + }, "type": "shell", - "command": "${workspaceFolder}/venv/bin/mkdocs", - "args": ["build"], - "dependsOn": ["Install dependencies"], + "command": "make html", + "isBackground": false, "problemMatcher": [], - "presentation": { - "reveal": "always", - "panel": "new" - } + "group": { + "kind": "build", + "isDefault": true + } }, { - "label": "Start Nav2 Docs live preview server", + "label": "Autobuild", + "icon": { + "id": "debug-start" + }, "type": "shell", - "command": "${workspaceFolder}/venv/bin/mkdocs", - "args": ["serve"], - "dependsOn": ["Install dependencies"], + "command": "make autobuild", + "isBackground": true, "problemMatcher": [], - "presentation": { - "reveal": "always", - "panel": "new" - }, - "isBackground": true - }, + "group": { + "kind": "build", + "isDefault": false + } + } ] } diff --git a/2021summerOfCode/Summer_2021_Student_Program.rst b/2021summerOfCode/Summer_2021_Student_Program.rst new file mode 100644 index 0000000000..7e90bad695 --- /dev/null +++ b/2021summerOfCode/Summer_2021_Student_Program.rst @@ -0,0 +1,36 @@ +:orphan: + +.. _summer_2021_student_program: + + +Projects for 2021 Summer Student Program +######################################## + +The `Summer 2021 Student Program `_ is upon us! +See below for the list of project proposals for students to review and apply for. +This is by no means the only list of potential projects, please check our issue tracker or propose another if there's something you think you're well suited for that would be useful for Nav2. + +If you have any questions, wish to ask questions, or generally reach out, you are encouraged to do so! +We have a community Slack at `navigation2.slack.com `_. +If you are unable to access it due to not being able to sign up, please send an email to the mentor in the details below and they can manually add you. + +Additionally, we have ROS community Discourse. +If you post on `this discourse page `_ regarding Nav2, a maintainer will respond. +We have the sub-topic Navigation Stack that may be used `here `_. +It is preferred you post in this sub-topic. + +For general ROS questions, please use `ROS Answers `_. + +Have fun and we look forward to working with you this summer! + +.. toctree:: + :maxdepth: 1 + + projects/dynamic.rst + projects/testing.rst + projects/assisted_teleop.rst + projects/multithreading.rst + projects/safety_node.rst + projects/semantics.rst + projects/spinners.rst + projects/twist_n_config.rst diff --git a/2021summerOfCode/projects/assisted_teleop.rst b/2021summerOfCode/projects/assisted_teleop.rst new file mode 100644 index 0000000000..1d034e512d --- /dev/null +++ b/2021summerOfCode/projects/assisted_teleop.rst @@ -0,0 +1,43 @@ + +.. _assisted_teleop: + +3. Assisted Teleop +================== + +**Task description** + +In mobile robot and autonomous vehicle navigation, there are situations where a human driver is required to intervene to get the vehicle out of a sticky situation. This can be both as a backup in case of autonomy failure as well as the primary function of the robot (e.g. telepresence robots). + +This project's aim is to create an assisted teleop feature in Nav2 by means of a new behavior tree configuration file (the file that defines the flow of information for the navigation task) and potentially new plugins. This feature should make sure to use the local costmap and/or sensor data in order to avoid obstacles and take position and/or velocity commands to attempt to follow. + +An example application of this is a telepresence robot, where a human driver is driving the robot through a space to visit in an office building or hospital. Another example would be an autonomous delivery robot stuck requiring a human driver to navigate it back into an open space for the robot to continue its task. + +This will be an excellent chance to make a substantial new feature in the Nav2 system to be used by hundreds of robots in the future. This project could also be a good candidate for a ROSCon talk in future events. + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Integrations of an assisted teleop feature in Nav2 as either a set of plugins and/or a behavior tree configuration +- Robot can successfully navigate a space by a user teleop without collision +- If time allots, work on tuning / adding new critics to the DWB local planner to improve safety of its performance for users out of the box + +**Skills required** + +- C++, XML, ROS +- Mobile robot navigation experience +- Recommended: Gazebo simulation, ROS navigation, Behavior trees + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/create_configuration_assistant.rst b/2021summerOfCode/projects/create_configuration_assistant.rst new file mode 100644 index 0000000000..3f019d7445 --- /dev/null +++ b/2021summerOfCode/projects/create_configuration_assistant.rst @@ -0,0 +1,54 @@ +:orphan: + +.. _create_moveit_analog: + +1. Create a Configuration Assistant (Analog to MoveIt) +====================================================== + +**Task description** + +`Moveit `_ has long has a QT `configuration assistant `_. This setup assistant helps the user configure their UDRF and needs to setup MoveIt configuration files. + +A configuration assistant could be extremely beneficial to Navigation2 users as a way to minimize friction. We should provide a gui tool to cover the following configurations: + +- the broad strokes with the costmap, with a visualizer to show the user what it will look like +- Select configurable costmap layers +- Select recovery behavior parameters +- URDF, footprint, and frame selection to make sure the options comply with standards, planner, and controller +- Set minimum and maximum speed and other kinematic parameters +- Select from a dropdown of possible planners and controllers +- Helpful notes throughout the prompts to aid in selecting appropriate parameters +- Selecting at behavior tree +- @steve please add more specific options + +After the items are configured, there should be a preview to see how the parameters effect the robot. + +**Project difficulty: High** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Contact information for the cooperating mentor (optional): juzhenatpku@gmail.com** + +**Project output requirements** + +- A QT based GUI configuration assistant that support the parameters listed above +- A preview panel to display the parameters' effection on the robot + +**Skills required** + +- C++, Python3, QT framework +- JSON/XML parsing +- 3D programming (maybe needed in the preview) +- Recommended: Gazebo simulation, ROS, and Navigation experience + +**List of relevant open source software repositories and refs** + +- `QT `_ +- `Gazebo Simulator `_ +- `Original github issue page `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/create_plugins.rst b/2021summerOfCode/projects/create_plugins.rst new file mode 100644 index 0000000000..9f82f921c3 --- /dev/null +++ b/2021summerOfCode/projects/create_plugins.rst @@ -0,0 +1,48 @@ +:orphan: + +.. _create_plugins: + + + +2. Create New Planner and Controller Plugins +============================================ + +**Task description** + +The ROS 2 Navigation Stack has a number of plugin interfaces to help users create or select specific plugins for planning, control, and behaviors for their applications. Two specific areas that the Nav2 stack could use more algorithm plugins for is for path planning (referred to as a planner plugin) and local trajectory generation (referred to as controller plugins). A simple tutorial for creating a `planner plugin can be found here. `_ Currently, we have one planner, NavFn which implements an A* and Dijkstra's planner. It also has two controllers, DWB and TEB which implement a DWA and timed elastic-band optimization techniques. There is also a Hybrid-A* and OMPL planner in development. + +Your task will be to create a high-quality implementation of one of the following algorithms for the Nav2 plugin interfaces. Alternative algorithms may also be considered upon approval, please ask @steve in the application phase. Please select only one to discuss. + +- Planner Plugin Options: D* or variant, Vornoi planner, Navigation graph route planner, State Lattice planner, kinodynamic planner, and any planning method given a set of dynamic and static obstacles. +- Controller Plugin Options: CiLQR, iLQR, MPC, Splines, path following or dynamic obstacle following controllers. +- Additional options: helping in completing the OMPL or Hybrid-A* planner. + +**Project difficulty: High** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** + +- A functional planner or controller plugin for the Nav2 stack +- Plugin should be optimized for run-time performance with 50% or greater test coverage + +**Skills required** + +- C++ +- Path planning or motion planning +- Algorithm optimization +- ROS / Pluginlib +- Recommended: Gazebo simulation and Navigation experience + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github issue page `_ +- `Nav2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/dynamic.rst b/2021summerOfCode/projects/dynamic.rst new file mode 100644 index 0000000000..236d2bbda3 --- /dev/null +++ b/2021summerOfCode/projects/dynamic.rst @@ -0,0 +1,47 @@ + +.. _dynamic: + + +1. Navigation Dynamic Obstacle Integration +========================================== + +**Task description** + +The Navigation Stack has long provided robust navigation in a wide range of environments. Controllers have been developed to operate effectively in the presence of dynamic obstacles without explicitly modeling the characteristics of dynamic obstacles. However, as the field has progressed and we see more and more robots using ROS deployed in human-filled spaces, more consideration must be taken with respect to dynamic obstacles such as people, carts, animals, and vehicles. + +Your task will be to create integrations with existing machine learning tools that create dynamic obstacle information (ComplexYolo, Yolo3D, etc) and tie them into the navigation stack for use. It is not in the scope for you to retrain or otherwise become an expert in 3D machine learning, but some basic knowledge will be helpful. We already have a starting point in the project links below that needs to be driven to completion. This includes completing the on-going work to integrate yolact edge into this work to replace detectron2 and benchmark these capabilities on GPUs to verify sufficient run-time performance, as well as other tangental feature development. + +This task will involve identifying a few techniques that produce position and velocity information about dynamic obstacles that can run on a mobile robot (using high-power Intel CPU, Nvidia Jetson SoC, external GPUs, etc) and get them running with ROS and Navigation. Next, you will help create a new costmap layer to use this information to mark the dynamic obstacle in the costmap to ensure a robot does not collide with a future trajectory of an obstacle. + +If time permits, you may also work to also integrate this dynamic information into a path planner and/or controller to help in direct motion consideration. This will likely be in collaboration with another community member. + +**Project difficulty: High** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Integrations of 1 method of dynamic obstacle detection in ROS 2, using machine learning +- Test these capabilities on real data or a live robot to demonstrate functionality +- 85% test coverage or higher + +**Skills required** + +- C++, Python, ROS +- Mobile robot navigation experience +- Geometry and statistics +- Recommended: Gazebo simulation, machine learning, ROS navigation + +**List of relevant open source software repositories and refs** + +- `Starting project `_ +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Navigation2 `_ +- `Some related works `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/grid_maps.rst b/2021summerOfCode/projects/grid_maps.rst new file mode 100644 index 0000000000..489716c729 --- /dev/null +++ b/2021summerOfCode/projects/grid_maps.rst @@ -0,0 +1,46 @@ +:orphan: + +.. _grid_maps: + + + + +3. Port Grid Maps to ROS 2 and Environmental Model +================================================== + +**Task description** +Grid Maps was created by ETH Zurich and later transferred to ANYbotics. It is a universal grid map library for mobile robotic mapping that can be used as the basis of environmental models and various forms of grid maps available in ROS 1. This library is one of the top downloaded ROS packages. Your task will be to work with the community and the mentor to port grid_maps metapackage from ROS 1 to ROS 2 and help develop the next generation environment model in ROS 2 to replace costmap_2d. + +This will involve porting code from ROS 1 to ROS 2, analyzing uses of the environmental model to define an abstract interface to allow replacement of costmap_2d with grid_map, and building up the basic grid-operations for costmaps. It is not expected to complete the full new model with sensor processing over the course of the summer. If completed early, you may be able to help design a gradient model to complement your implemented costmap model using grid_maps. This will allow robots to select a gradient or a costmap model on startup. + +**Project difficulty: High** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** + +- Grid Maps ported to ROS 2 and merged into the main ROS 2 branch +- Defined plugin interfaces to replace costmap 2D with grid maps +- Implementing low-level operations on top of grid_maps to replace the base costmap_2d object. +- You will not be expected to reimplement the full sensor processing mechanics of costmap_2d. + +**Skills required** + +- C++ and Git +- ROS recommended ROS 2, but you can pick it up before starting +- Coordinate transformations and basic geometry +- Recommended: Gazebo simulation and Navigation experience + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Original github issue 1 `_ +- `Original github issue 2 `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/localization.rst b/2021summerOfCode/projects/localization.rst new file mode 100644 index 0000000000..3b0a836df7 --- /dev/null +++ b/2021summerOfCode/projects/localization.rst @@ -0,0 +1,50 @@ +:orphan: + +.. _localization: + + +6. 2D/3D Localization Improvements +================================== + +**Task description** + +The Navigation2 stack uses AMCL as its primary localization engine. Over the last 10 years, essentially no updates to AMCL has been made. This is due to the code base for this implementation of an Adaptive Monte Carlo Localizer is written in embedded C, not well structured, and very sensitive to changes. A-MCL implementations have been a hallmark of localization for over a decade but this particular implementation should be deprecated. + +Your target involves designing and creating a new localization engine for the Nav2 stack. The requirements of this are: +- Support 2D laser scanners +- Support 3D laser scanners, where 2D case could potentially be a simplified case +- Accurately track the localization of a robot in a given occupancy grid + +The reason that specific method is left open-ended is to allow for creativity, novelty, or reimplementation of a what you feel is best. We have, however, analyzed other MCL variants as being good options. This may include reimplementing an A-MCL that is designed to be modified with modular components and support sampling from a 3D lidar. Another option is a NDT-MCL using NDT 2D/3D scan matching. Other options may be proposed and discussed with mentors during the application phase. The task involves 3D as well since there is no standard 3D localizer in ROS 2 yet and more and more robust 3D SLAM libraries have emerged over the last 2 years. + +An optional but recommended feature of this work would be to also accept the inputs from multiple laser scanners. However it is not strictly required. + +**Project difficulty: High** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- 2D and 3D localization system based on laser scanners +- 65% or higher test coverage +- Designed with modular components that can be reliably modified over time + + +**Skills required** + +- C/C++ +- Localization, particle filter, or SLAM techniques +- Ability to read and implement academic works +- Recommended: Gazebo simulation and Navigation experience + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Original Github Issue `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/multithreading.rst b/2021summerOfCode/projects/multithreading.rst new file mode 100644 index 0000000000..8cc7ff807f --- /dev/null +++ b/2021summerOfCode/projects/multithreading.rst @@ -0,0 +1,51 @@ + +.. _multhrreading: + +4. Navigation MultiThreading +============================ + +**Task description** + +The aim of this project is the significantly improve the run-time performance of Nav2 making sure to leverage the full capabilities of multi-processor core CPUs. We seek to identify areas in the Nav2 stack that could leverage multi-threading or parallel processing to speed up computations and improve overall user performance on a broad range of compute platforms. + +Some examples include: +- AMCL particle cloud updates +- Costmap layer updates +- Costmap sensor data population +- Controller critic evaluation +- Collision checking +- Voxel grid ray casting +- and more. + +We are seeking a student interested in learning about multi-threading and parallel processing, ideally with some exposure to these concepts and libraries already, to analyze potential areas for parallel computing. Then, select the top candidates and implement them with parallel processing and benchmark the improvements to the Nav2 stack they provide. + +This will be an excellent chance to apply (or obtain) C++ parallel computing skills while also learning a great deal about how to build mobile robot navigation systems -- both very valuable skillsets. + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Analysis of potential areas in the Nav2 stack that can benefit from parallel processing +- Integrations of 3-5 areas in the Nav2 stack that non-trivially improves run-time performance of the stack using multithreading +- Benchmark performance improvements + +**Skills required** + +- C++, ROS +- Mobile robot navigation experience +- Working knowledge (or ability to quickly obtain) on one or more of: TBB, OpenMP, OpenCL, Cuda, and similar +- Recommended: Gazebo simulation, ROS navigation + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/navigation_rebranding.rst b/2021summerOfCode/projects/navigation_rebranding.rst new file mode 100644 index 0000000000..e2f41368da --- /dev/null +++ b/2021summerOfCode/projects/navigation_rebranding.rst @@ -0,0 +1,40 @@ +:orphan: + +.. _rebranding: + + +5. Navigation Branding and Website +================================== + +**Task description** + +Navigation2 has made significant strides to be the best navigation system in the world. Over time, the original navigation stack in ROS has gained a reputation, fair or unfair, of being relatively limited in the types of tasks it can accomplish that are no longer true in ROS 2 Navigation2. + +As such, we would like to initiate a re-branding effort to help differentiate it from its foundings. `MoveIt `_ has a high-quality landing page with consistent graphics, color schemes, logos, and a catchy name. Your task will be to create a logo, color scheme, and work with maintainers to develop a new name to use in creating a new website for Navigation2. The `existing website `_ is a Read The Docs design with just the technical tutorials and details. We would like the new Navigation2 website to be analog to the MoveIt website and allow for future expansions such as a blog and pages highlighting demos and robots using the framework. + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Work with maintainers to come up with a new name, logo, and color scheme +- Develop a new landing package using these elements and developed graphics +- Migrate the existing website to the new one +- Add a blog feature and document the structure and editing process for future developers + +**Skills required** + +- Design and graphics packages +- Web technologies +- Creative thinking + +**List of relevant open source software repositories and refs** + +- `Github issue `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/safety_node.rst b/2021summerOfCode/projects/safety_node.rst new file mode 100644 index 0000000000..d41125b82e --- /dev/null +++ b/2021summerOfCode/projects/safety_node.rst @@ -0,0 +1,48 @@ + +.. _safety_node: + +5. Navigation Safety Node +========================= + +**Task description** + +The aim of this project is to create a safety watchdog node to ensure the robot is acting properly and not about to collide with an obstacle. Typical safety-rated lidars will contain "safety zones" whereas if any sensor points are located in a box around the lidar, then the lidar will send a signal to the robot to stop due to a potential collision. However, less and less people are using safety-rated lidars as consumer available lidars are dropping in cost and 3D lidars are seeing more use in mobile robotics. + +Your project will be to re-create this logic at the Navigation level. While this wouldn't be "safety certified", this is a significant functional improvement on safety that could potentially safe real people from real injuries in the real-world. The project will be to create a node that sits below the navigation stack but above the robot controller to do the following: + +- Take in the current command velocity from navigation and the most recent laser or RGBD scan +- Projecting the velocity forward in time ``N`` seconds, check if that velocity will result in a collision with any sensor measurements +- If not, allow the velocity command through to the base +- If it does collide, scale back the velocity such that the robot will always be at minimum ``N`` seconds from a collision +- Optionally if a flag is set, if ``M`` or more points are in defined bounding boxes around the robot, send only ``0`` commands to enact an emergency stop. + +This will be an excellent chance to make mobile robots and Nav2 users significantly safer and run at higher speeds in their production or research environments. It goes a long way for functional safety for those not using safety-rated lidars which contain similar features. + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Creation of a ROS 2 node that will prevent robot collision based on lidar and/or RGBD data +- Node should be able to run at lidar data speed (40hz+) and adjust velocity commands accordingly +- If time allots, work on tuning / adding new critics to the DWB local planner to improve safety of its performance for users out of the box + +**Skills required** + +- C++, ROS +- Mobile robot navigation experience +- Geometry and statistics +- Recommended: Gazebo simulation, ROS navigation + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/semantics.rst b/2021summerOfCode/projects/semantics.rst new file mode 100644 index 0000000000..5f6d29a463 --- /dev/null +++ b/2021summerOfCode/projects/semantics.rst @@ -0,0 +1,42 @@ + +.. _semantics: + +6. Semantic Integration +======================= + +**Task description** + +This project is to create a semantics library and integrate it into the Nav2 system. The major aim is to enable a generic semantic representation format that navigation (and potentially other ROS projects) may use for representing their environment, objects within it, or points of interest. + +After creating the generic representation, your project will be to create demonstrations within Nav2 using this capability including a route planning server to replace the planner server in situations where you have a pre-defined set of potential locales (non-free space planning) and another demonstration of your choice. + +**Project difficulty: Hard** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Generic semantics standard added to Nav2 documentation +- Generic semantics ROS 2 library that implements the standard and makes it easy for applications to get, retrieve, or analyze semantic data for custom purposes +- A route server to enable navigation-graph and/or route following capabilities +- 1 more demonstration using the semantics library of your choice (could be costmap layer with different rules in different rooms or with different objects, a multi-story building demo using semantic info to allow a robot to plan and execute multi-story trajectories, etc) + +**Skills required** + +- C++, Python, ROS 2 +- Mobile robot navigation or manipulation experience +- Perception, semantic information motivation, or similar. +- Recommended: Gazebo simulation, ROS navigation + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Github ticket2 `_ +- `Navigation2 `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/spinners.rst b/2021summerOfCode/projects/spinners.rst new file mode 100644 index 0000000000..6ae9206423 --- /dev/null +++ b/2021summerOfCode/projects/spinners.rst @@ -0,0 +1,46 @@ + +.. _spinners: + + +7. Reduce ROS 2 Nodes and Determinism +===================================== + +**Task description** + +This project is admittedly abstract to explain to someone unfamiliar with the inner-details of ROS 2 and its layers. If you're interested in working on this, you will become one of the few that truly understand the inner workings of it and be a very marketable skill. We do not expect anyone applying for this project to have that knowledge beforehand and we will help you learn the necessary items. + +ROS 2 architecturally was changed before Foxy in order to ensure that any single process containing multiple ROS 2 node objects will share the same DDS participant on the network. This is important due to the overhead that each additional DDS participant has on the system. + +In order for nav2 to leverage this the best, we need to adjust our usage of ROS 2 nodes and executors to further minimize the number of node objects in existence. In the early days of ROS 2 when Nav2 was being built, we were required to have many nodes in a single server in order to handle action requests and other callbacks. Now, we can make use of multi-threaded spinners, callback groups, and individual executors for specific tasks. + +This project will involve identifying all of the Node objects in the stack (control+F makes this easy) and work with mentors to ensure by the end of the summer each server contains only a single node. Additionally, the behavior tree plugins should be updated to leverage callback groups to ensure that any single BT node spinning to check if any new messages are on its callback will **only** trigger its own callback by the same mechanisms. + +More details about this project can be supplied if interested, but the tickets linked below also provide more context. Trust me to say this is a very achievable goal over the course of the summer and will also let you look under the hood of both Nav2 and rclcpp, giving you valuable insight future in your career (and put you in the top 10% of ROS 2 developers that know it to this degree). + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Remove excess ROS 2 nodes from stack and replace with executors and multi-threaded executors +- Replace Behavior Tree node spinners with local executors to ensure deterministic execution & processing only callback groups of the current BT node +- If time allots, create a single ``main()`` function Nav2 executable composing all Nav2 processes and benchmarking improvements in performance + +**Skills required** + +- C++, ROS + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Github ticket2 `_ +- `Navigation2 `_ +- `Some related works `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/testing.rst b/2021summerOfCode/projects/testing.rst new file mode 100644 index 0000000000..bb42917b03 --- /dev/null +++ b/2021summerOfCode/projects/testing.rst @@ -0,0 +1,39 @@ +.. _testing: + + + +2. Advanced Navigation Testing Framework +======================================== + +**Task description** + +The ROS 2 Navigation Stack has had a focus on testing and reliability as a characteristic change from ROS 1 to ROS 2. We currently have a test coverage rate of 85% and do full system simulations in Continuous Integration (CI) to test the entire navigation system with a real robot completing real navigation tasks. Your task will be to increase the testing coverage rate to 90% (or +5% from your starting) and improve on the existing system tests to represent a more realistic environment. You will then work to make sure of that environment to actively block the robot from completing its task to simulate worst-case conditions. + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** + +- Test line coverage of 90% or higher on the repository as reported by codecov (currently 85%) +- An improved simulation environment for a more realistic mobile robotics application +- Updated system tests to take advantage of that environment to fault or un-ideal cases of the stack + +**Skills required** + +- C++, Python3, gtest +- Gazebo, recommended experience with Gazebo plugins +- Recommended: Navigation experience + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Navigation2 `_ +- `Navigation2 Repo System Tests `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/2021summerOfCode/projects/twist_n_config.rst b/2021summerOfCode/projects/twist_n_config.rst new file mode 100644 index 0000000000..106cd60781 --- /dev/null +++ b/2021summerOfCode/projects/twist_n_config.rst @@ -0,0 +1,51 @@ + +.. _twist: + + +8. Convert Twist to TwistStamped in Ecosystem and Run-Time Configuration +======================================================================== + +**Task description** + +This project is comprised of 2 smaller projects that can be easily worked on in parallel. + +Subproject A: Convert Twist to TwistStamped in Ecosystem + +The aim of this project is to identify places in the ROS 2 ecosystem that make use of ``Twist`` in the context of ``cmd_vel`` coming out of Navigation. This includes things like Nav2, ROS 2 Control, Gazebo ROS Plugins, Yuk's Velocity Filter, major robot drivers, etc. A set of previously identified places is shown in the ticket linked below. + +Once you've created a list of places in the ecosystem where it is used, your project will be to submit PRs on their ROS 2 branches to change the interface to make use of a ``TwistStamped`` instead of a ``Twist``. + + +Subproject B: Run-time Reconfiguration of Parameters + +In the meantime while you're waiting for PRs to be merged or blocked by reviews on converting all of the ecosystems ``cmd_vel`` use of ``Twist`` to ``TwistStamped``, your project will be to enable run-time reconfiguration of the major parameters in Nav2. In ROS 2 this is done via the parameter change event callbacks. See tickets below for a list of plugins or servers needing dynamically reconfigurable parameter support added. + + +**Project difficulty: Medium** + +**Project community mentor: Steve Macenski** `@SteveMacenski `_ + +**Mentor contact details: [See link above, link in GitHub profile description]** + +**Project output requirements** +- Convert all the major ecosystem projects into TwistStamped +- Enable run-time reconfiguration of the remaining plugins and servers in Nav2 missing +- Ensure that reconfiguration is thread-safe by using locks, atomic variables, or callback groups + +**Skills required** + +- C++, Python3 +- ROS 2 + +**List of relevant open source software repositories and refs** + +- `ROS `_ +- `Gazebo Simulator `_ +- `Github ticket `_ +- `Github ticket2 `_ +- `Navigation2 `_ +- `Some related works `_ + +**Licensing** +- All contributions will be under the Apache 2.0 license. +- No other CLA's are required. diff --git a/Dockerfile b/Dockerfile index dd412c8a6c..44e09f840e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,14 +4,14 @@ # $ docker build -f Dockerfile --build-arg user=$(id -un) --build-arg uid=$(id -u) -t nav2_docs . # # To use the image to build the docs: -# $ docker run --rm -v .:/docs nav2_docs mkdocs build +# $ docker run --rm -v $(pwd):/docs nav2_docs make html # # To run autobuild (watches for changes and rebuilds automatically): -# $ docker run --init --rm -it -v .:/docs -p 127.0.0.1:8000:8000 nav2_docs mkdocs serve --dev-addr 0.0.0.0:8000 +# $ docker run --init --rm -it -v $(pwd):/docs -p 8000:8000 nav2_docs make autobuild # Then browse to http://127.0.0.1:8000 # Use Ctrl+C to stop (--init flag enables proper signal handling) # -# The built documentation will be in site/ +# The built documentation will be in _build/html/ FROM ubuntu:noble @@ -26,9 +26,14 @@ RUN if id -u $uid ; then userdel `id -un $uid` ; fi RUN apt-get update && \ apt-get install --no-install-recommends -y \ + doxygen \ git \ + graphviz \ + make \ + openjdk-8-jre \ openssh-server \ - python3-pip && \ + python3-pip \ + fonts-dejavu && \ rm -rf /var/lib/apt/lists/* RUN useradd -u $uid -m $user diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000..8c94c249da --- /dev/null +++ b/Makefile @@ -0,0 +1,70 @@ +# Minimal makefile for Sphinx documentation +# + +ifeq ($(VERBOSE),1) + Q = +else + Q = @ +endif + +# You can set these variables from the command line. +SPHINXOPTS ?= +SPHINXBUILD = sphinx-build +SPHINXPROJ = "Nav2 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) + +# Autobuild the docs on changes + +autobuild: + sphinx-autobuild --host 0.0.0.0 --port 8000 -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) + +# 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:open-navigation/docs.nav2.org.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 + cp scripts/CNAME $(PUBLISHDIR)/CNAME + 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) -W $(O) diff --git a/README.md b/README.md index f26e76757d..82dba5eb04 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,36 @@ # docs.nav2.org +https://docs.nav2.org/ -[![CircleCI](https://img.shields.io/badge/-circleci-1b273a?style=for-the-badge&logo=circleci&logoColor=white)](https://app.circleci.com/pipelines/github/ros-navigation/docs.nav2.org) +This folder holds the source and configuration files used to generate the +[Navigation2 documentation](https://docs.nav2.org) web site. - -## Installation +### Native Installation -### Virtual Environment +Dependencies for Build: + +``` bash +sudo apt install python3-pip +pip3 install -r requirements.txt +``` + +### Installation in a Virtual Environment Install `pip` and `venv` if not already installed: -``` shell + +``` bash sudo apt install python3-pip python3-venv ``` -Create a virtual environment and activate it: -```shell -python3 -m venv venv && -source venv/bin/activate -``` +Create a virtual environment and install the dependencies: -Install all required dependencies: -```shell +``` bash +python3 -m venv venv +source venv/bin/activate pip3 install -r requirements.txt ``` -### Docker Container +### Using Docker Build the Docker image (from this directory): @@ -35,13 +41,13 @@ docker build -f Dockerfile --build-arg user=$(id -un) --build-arg uid=$(id -u) - To build the documentation: ```bash -docker run --rm -v .:/docs nav2_docs mkdocs build +docker run --rm -v $(pwd):/docs nav2_docs make html ``` To run autobuild (watches for changes and rebuilds automatically): ```bash -docker run --init --rm -it -v .:/docs -p 127.0.0.1:8000:8000 nav2_docs mkdocs serve --dev-addr 0.0.0.0:8000 +docker run --init --rm -it -v $(pwd):/docs -p 8000:8000 nav2_docs make autobuild ``` Then browse to http://127.0.0.1:8000. Use Ctrl+C to stop (the `--init` flag enables proper signal handling). @@ -52,99 +58,28 @@ If you're using Visual Studio Code, you can use the dev container for an easy se 1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) 2. Open this folder in VS Code -3. When prompted, click "Reopen in Container" (or use Command Palette: `Dev Containers: Reopen in Container`) +3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container") 4. Once the container is built and running, use the integrated terminal to build the docs -The dev container automatically sets up all dependencies. You can then use the build commands described below. - -## Build - -### Single distribution - -Use the following command from the required distribution branch to build the documentation: -```shell -mkdocs build -``` - -The build result can be found in the `site` directory, and the entry point in `site/index.html` file. -[Other options][mkdocs-build-url] for the build command. - -Instead of the usual build process, MkDocs provides a live preview server that can be started with: -```shell -mkdocs serve -``` - -It allows to preview new changes during documentation update. The server will automatically rebuild the entire documentation after each file saving and display result at http://127.0.0.1:8000/. See [more options][mkdocs-serve-url] for the command. - -> [!WARNING] -> The command `mkdocs serve` will display documentation for only one distribution without the ability to switch between them. \ -> To preview multiple distributions, follow the instructions below. +The dev container automatically sets up all dependencies. You can then use the build tasks or run commands directly: +- Build once: `make html` or use the "Build" task (Ctrl+Shift+B) +- Auto-rebuild: `make autobuild` or use the "Autobuild" task +### Build the Docs -### Multiple distributions +Build the docs locally with `make html` and you'll find the built docs entry point in `_build/html/index.html`. -The current documentation relies on the [mike][mike-url] utility to support multiple versions. -To build the documentation, execute the following command from the corresponding `` branch for each version that needs to be displayed: -```shell -mike deploy -``` - -After execution, a new directory with the selected `` name will be created on the local `gh-pages` branch. This directory will also contain the build result with the corresponding entry point `/index.html`. -In addition, it creates the same `site` directory as before using `mkdocs build` in the current branch. - -You can set the `--title` option to change the version name displayed on the website. See [more options][mike-build-url] for this command. - -Example for two branches: -- Execute from `rolling` branch: - ```shell - mike deploy rolling --title=Rolling - ``` - -- Execute from `jazzy` branch: - ```shell - mike deploy jazzy --title=Jazzy - ``` +To automate the build process, you can use a [sphinx-autobuild](https://github.com/sphinx-doc/sphinx-autobuild) package. \ +Run this command from the virtual environment to build the documentation and start a server: -Before viewing, you need to set the default version: -```shell -mike set-default -``` - -Similar to `mkdocs serve`, mike provides a server that can be started with: -```shell -mike serve +```bash +sphinx-autobuild . ./_build/html ``` +For more options for the command, see the documentation linked above. -The documentation will be available at the same address http://127.0.0.1:8000/, and each version at the corresponding address `http://127.0.0.1:8000//`. \ -See [more options][mike-serve-url] for this command. - -> [!NOTE] -> This server does not provide a live preview after changes are made locally. \ -> To display the new changes, use the `mike deploy` command for the corresponding branch, as was shown before. +Now you can access the page using the local address: http://127.0.0.1:8000. \ +After saving any changes, the documentation will be automatically rebuilt and displayed. -This command is useful for local testing and viewing differences between versions without the need to use a real web server. -If you need to make changes for only one version, it will be more convenient to use `mkdocs serve` for this purpose, due to its live preview ability. - -After completing all changes, use these commands to exit the working environment: - -- If using the virtual environment (venv): - - ```shell - deactivate - ``` - -- If using the VS Code Dev Container: - - Select in the Command Palette: `Dev Containers: Reopen Folder Locally` - -## License - -This project is licensed under the terms of the [Apache-2.0](./LICENSE) license. \ Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses. - -[mkdocs-build-url]: https://www.mkdocs.org/user-guide/cli/#mkdocs-build -[mkdocs-serve-url]: https://www.mkdocs.org/user-guide/cli/#mkdocs-serve -[mike-url]: https://github.com/jimporter/mike -[mike-build-url]: https://github.com/jimporter/mike#building-your-docs -[mike-serve-url]: https://github.com/jimporter/mike#viewing-your-docs +Want a local PDF version? Follow the [instructions here](https://gist.github.com/alfredodeza/7fb5c667addb1c6963b9). diff --git a/_themes/otc_tcs_sphinx_theme/.gitignore b/_themes/otc_tcs_sphinx_theme/.gitignore new file mode 100644 index 0000000000..6c014f9811 --- /dev/null +++ b/_themes/otc_tcs_sphinx_theme/.gitignore @@ -0,0 +1,2 @@ +__pycache__ +_build diff --git a/_themes/otc_tcs_sphinx_theme/layout.html b/_themes/otc_tcs_sphinx_theme/layout.html new file mode 100644 index 0000000000..06bc2d6c48 --- /dev/null +++ b/_themes/otc_tcs_sphinx_theme/layout.html @@ -0,0 +1,34 @@ +{% extends "sphinx_rtd_theme/layout.html" %} + +{% block extrahead %} + + + +{% endblock %} + +{% block content %} + + + Edit + + +{{ super() }} + +{% endblock %} + +{% block footer %} + + + + + + +{% endblock %} diff --git a/_themes/otc_tcs_sphinx_theme/readme.rst b/_themes/otc_tcs_sphinx_theme/readme.rst new file mode 100644 index 0000000000..7f5f284f28 --- /dev/null +++ b/_themes/otc_tcs_sphinx_theme/readme.rst @@ -0,0 +1,23 @@ +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/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css new file mode 100644 index 0000000000..07df4e7264 --- /dev/null +++ b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css @@ -0,0 +1,217 @@ +/* -- 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; +} + +/* Mobile-responsive styles for distribution table */ +@media screen and (max-width: 768px) { + /* Stack table cells vertically on mobile */ + table.distribution-table, + table.distribution-table tbody, + table.distribution-table tr, + table.distribution-table td { + display: block !important; + width: 100% !important; + } + + /* Remove table cell borders and padding adjustments */ + table.distribution-table td { + border: none !important; + padding: 20px 0 !important; + text-align: center !important; + } + + /* Add separator between distribution items */ + table.distribution-table td:not(:last-child) { + border-bottom: 2px solid #e1e4e8 !important; + margin-bottom: 20px !important; + padding-bottom: 30px !important; + } + + /* Ensure images scale properly on mobile while maintaining aspect ratio */ + table.distribution-table img { + max-width: 250px !important; + max-height: 250px !important; + width: auto !important; + height: auto !important; + object-fit: contain !important; + } + + /* Adjust text sizing for mobile */ + table.distribution-table span[style*="font-size: 20px"] { + font-size: 18px !important; + } + + table.distribution-table span[style*="font-size: 15px"] { + font-size: 14px !important; + padding: 10px 20px !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; +} diff --git a/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js new file mode 100644 index 0000000000..6317390701 --- /dev/null +++ b/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js @@ -0,0 +1,50 @@ +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; + } + } +} diff --git a/_themes/otc_tcs_sphinx_theme/theme.conf b/_themes/otc_tcs_sphinx_theme/theme.conf new file mode 100644 index 0000000000..fc97c5522d --- /dev/null +++ b/_themes/otc_tcs_sphinx_theme/theme.conf @@ -0,0 +1,2 @@ +[theme] +inherit = sphinx_rtd_theme diff --git a/docs/robots_using/assets/ACFR.png b/about/images/ACFR.png similarity index 100% rename from docs/robots_using/assets/ACFR.png rename to about/images/ACFR.png diff --git a/docs/robots_using/assets/angsa.png b/about/images/angsa.png similarity index 100% rename from docs/robots_using/assets/angsa.png rename to about/images/angsa.png diff --git a/docs/robots_using/assets/barnowl.png b/about/images/barnowl.png similarity index 100% rename from docs/robots_using/assets/barnowl.png rename to about/images/barnowl.png diff --git a/docs/robots_using/assets/birdseye.png b/about/images/birdseye.png similarity index 100% rename from docs/robots_using/assets/birdseye.png rename to about/images/birdseye.png diff --git a/docs/robots_using/assets/botronics.png b/about/images/botronics.png similarity index 100% rename from docs/robots_using/assets/botronics.png rename to about/images/botronics.png diff --git a/docs/robots_using/assets/brisa.png b/about/images/brisa.png similarity index 100% rename from docs/robots_using/assets/brisa.png rename to about/images/brisa.png diff --git a/docs/robots_using/assets/datavision.png b/about/images/datavision.png similarity index 100% rename from docs/robots_using/assets/datavision.png rename to about/images/datavision.png diff --git a/docs/robots_using/assets/dexory.png b/about/images/dexory.png similarity index 100% rename from docs/robots_using/assets/dexory.png rename to about/images/dexory.png diff --git a/docs/robots_using/assets/elroy.png b/about/images/elroy.png similarity index 100% rename from docs/robots_using/assets/elroy.png rename to about/images/elroy.png diff --git a/docs/robots_using/assets/firefly.png b/about/images/firefly.png similarity index 100% rename from docs/robots_using/assets/firefly.png rename to about/images/firefly.png diff --git a/docs/robots_using/assets/g1.png b/about/images/g1.png similarity index 100% rename from docs/robots_using/assets/g1.png rename to about/images/g1.png diff --git a/docs/robots_using/assets/go2.png b/about/images/go2.png similarity index 100% rename from docs/robots_using/assets/go2.png rename to about/images/go2.png diff --git a/docs/robots_using/assets/karelics.png b/about/images/karelics.png similarity index 100% rename from docs/robots_using/assets/karelics.png rename to about/images/karelics.png diff --git a/docs/robots_using/assets/karelics2.png b/about/images/karelics2.png similarity index 100% rename from docs/robots_using/assets/karelics2.png rename to about/images/karelics2.png diff --git a/docs/robots_using/assets/kiwibot.png b/about/images/kiwibot.png similarity index 100% rename from docs/robots_using/assets/kiwibot.png rename to about/images/kiwibot.png diff --git a/docs/robots_using/assets/move_base_compare_2.png b/about/images/move_base_compare_2.png similarity index 100% rename from docs/robots_using/assets/move_base_compare_2.png rename to about/images/move_base_compare_2.png diff --git a/docs/robots_using/assets/mpo_700.png b/about/images/mpo_700.png similarity index 100% rename from docs/robots_using/assets/mpo_700.png rename to about/images/mpo_700.png diff --git a/docs/robots_using/assets/novacarter.png b/about/images/novacarter.png similarity index 100% rename from docs/robots_using/assets/novacarter.png rename to about/images/novacarter.png diff --git a/docs/robots_using/assets/pixel.png b/about/images/pixel.png similarity index 100% rename from docs/robots_using/assets/pixel.png rename to about/images/pixel.png diff --git a/docs/robots_using/assets/polymath.png b/about/images/polymath.png similarity index 100% rename from docs/robots_using/assets/polymath.png rename to about/images/polymath.png diff --git a/docs/robots_using/assets/polymath_boat.png b/about/images/polymath_boat.png similarity index 100% rename from docs/robots_using/assets/polymath_boat.png rename to about/images/polymath_boat.png diff --git a/docs/robots_using/assets/rb1.png b/about/images/rb1.png similarity index 100% rename from docs/robots_using/assets/rb1.png rename to about/images/rb1.png diff --git a/docs/robots_using/assets/rosbot_xl.png b/about/images/rosbot_xl.png similarity index 100% rename from docs/robots_using/assets/rosbot_xl.png rename to about/images/rosbot_xl.png diff --git a/docs/robots_using/assets/rover.png b/about/images/rover.png similarity index 100% rename from docs/robots_using/assets/rover.png rename to about/images/rover.png diff --git a/docs/robots_using/assets/saxion.jpeg b/about/images/saxion.jpeg similarity index 100% rename from docs/robots_using/assets/saxion.jpeg rename to about/images/saxion.jpeg diff --git a/docs/robots_using/assets/seasony.png b/about/images/seasony.png similarity index 100% rename from docs/robots_using/assets/seasony.png rename to about/images/seasony.png diff --git a/docs/robots_using/assets/soon.png b/about/images/soon.png similarity index 100% rename from docs/robots_using/assets/soon.png rename to about/images/soon.png diff --git a/docs/robots_using/assets/tailos.png b/about/images/tailos.png similarity index 100% rename from docs/robots_using/assets/tailos.png rename to about/images/tailos.png diff --git a/docs/robots_using/assets/tb2.png b/about/images/tb2.png similarity index 100% rename from docs/robots_using/assets/tb2.png rename to about/images/tb2.png diff --git a/docs/robots_using/assets/tb3.png b/about/images/tb3.png similarity index 100% rename from docs/robots_using/assets/tb3.png rename to about/images/tb3.png diff --git a/docs/robots_using/assets/tb4.png b/about/images/tb4.png similarity index 100% rename from docs/robots_using/assets/tb4.png rename to about/images/tb4.png diff --git a/docs/robots_using/assets/tiago.png b/about/images/tiago.png similarity index 100% rename from docs/robots_using/assets/tiago.png rename to about/images/tiago.png diff --git a/docs/robots_using/assets/torch.png b/about/images/torch.png similarity index 100% rename from docs/robots_using/assets/torch.png rename to about/images/torch.png diff --git a/docs/robots_using/assets/tri.png b/about/images/tri.png similarity index 100% rename from docs/robots_using/assets/tri.png rename to about/images/tri.png diff --git a/docs/robots_using/assets/ubr1.png b/about/images/ubr1.png similarity index 100% rename from docs/robots_using/assets/ubr1.png rename to about/images/ubr1.png diff --git a/docs/robots_using/assets/walking.png b/about/images/walking.png similarity index 100% rename from docs/robots_using/assets/walking.png rename to about/images/walking.png diff --git a/docs/robots_using/assets/waratah.png b/about/images/waratah.png similarity index 100% rename from docs/robots_using/assets/waratah.png rename to about/images/waratah.png diff --git a/docs/robots_using/assets/wyca.png b/about/images/wyca.png similarity index 100% rename from docs/robots_using/assets/wyca.png rename to about/images/wyca.png diff --git a/docs/robots_using/assets/yunji.png b/about/images/yunji.png similarity index 100% rename from docs/robots_using/assets/yunji.png rename to about/images/yunji.png diff --git a/about/index.rst b/about/index.rst new file mode 100644 index 0000000000..a0c0a9042d --- /dev/null +++ b/about/index.rst @@ -0,0 +1,81 @@ +.. _about: + +About and Contact +################# + +.. toctree:: + :hidden: + + related_projects.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 ROS 2 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. +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 | Open Navigation | SteveMacenski_ | Project Lead | ++-------------------+-------------------+-------------------+------------------+ +| Ruffin White | UC San Diego | ruffsl_ | CI Wizard | ++-------------------+-------------------+-------------------+------------------+ +| Joshua Wallace | Locus Robotics | JoshuaWallace_ | Main Contributor | ++-------------------+-------------------+-------------------+------------------+ + +.. _SteveMacenski: https://github.com/SteveMacenski +.. _ruffsl: https://github.com/ruffsl +.. _JoshuaWallace: https://github.com/jwallace42 + +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 | ++-------------------+-------------------+---------------------+---------------------+ +| Carl Delsey | Intel Corporation | crdelsey_ | Maintainer | ++-------------------+-------------------+---------------------+---------------------+ +| Alexey Merzlyakov | Samsung Research | AlexeyMerzlyakov_ | Maintainer | ++-------------------+-------------------+---------------------+---------------------+ + +.. _mkhansen: https://github.com/mkhansen-intel +.. _bpwilcox: https://github.com/bpwilcox +.. _crdelsey: https://github.com/crdelsey +.. _AlexeyMerzlyakov: https://github.com/AlexeyMerzlyakov + +Contact +******* + +If you are interested in contacting someone about Navigation, ROS 2, or related projects, please email the project leader or email info@opennav.org. +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. + +Check out the Navigation 2 Slack_ community. + +.. _Slack: https://join.slack.com/t/navigation2/shared_invite/zt-uj428p0x-jKx8U7OzK1IOWp5TnDS2rA diff --git a/about/related_projects.rst b/about/related_projects.rst new file mode 100644 index 0000000000..32b09d8472 --- /dev/null +++ b/about/related_projects.rst @@ -0,0 +1,35 @@ +.. _related_projects: + +Related Projects +################ + +This is a community maintained list of related repositories and projects to Navigation2. + ++--------------------------------+------------------------+----------------------------------+ +| Name | Maintainer | Description | ++================================+========================+==================================+ +| `Navigation2`_ | Steve Macenski | Main ROS 2 Navigation Stack | ++--------------------------------+------------------------+----------------------------------+ +| `docs.nav2.org`_ | Steve Macenski | Official documentation website | +| | | source code | ++--------------------------------+------------------------+----------------------------------+ +| `navigation2_tutorials`_ | Steve Macenski | Source code and examples used | +| | | in the documentation tutorials | ++--------------------------------+------------------------+----------------------------------+ +| `navigation2_dynamic`_ | Steve Macenski | Tools, algorithms, and | +| | | capabilities for working with | +| | | dynamic obstacles in ROS 2 | ++--------------------------------+------------------------+----------------------------------+ +| `robot_localization`_ | Tom Moore | State estimation software for | +| | | ROS 2 used for odometry fusion | +| | | and GPS transformations | ++--------------------------------+------------------------+----------------------------------+ +| `slam_toolbox`_ | Steve Macenski | Default 2D SLAM library | ++--------------------------------+------------------------+----------------------------------+ + +.. _Navigation2: https://github.com/ros-navigation/navigation2 +.. _docs.nav2.org: https://github.com/ros-navigation/docs.nav2.org +.. _navigation2_tutorials: https://github.com/ros-navigation/navigation2_tutorials +.. _navigation2_dynamic: https://github.com/ros-navigation/navigation2_dynamic +.. _robot_localization: https://github.com/cra-ros-pkg/robot_localization +.. _slam_toolbox: https://github.com/SteveMacenski/slam_toolbox diff --git a/about/robots.rst b/about/robots.rst new file mode 100644 index 0000000000..c8b919a5ad --- /dev/null +++ b/about/robots.rst @@ -0,0 +1,273 @@ +.. _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. + +.. + To add robot to the table, the dimensions MUST be either 512x340 or 340x512 + ++------------------------+------------------------+------------------------+ +| |dex| + |poly| + |nova| | ++------------------------+------------------------+------------------------+ +| |ang| + |fire| + |kiwi| | ++------------------------+------------------------+------------------------+ +| |rosie| + |karl| + |ses| | ++------------------------+------------------------+------------------------+ +| |G1| + |Go2| + |barnowl| | ++------------------------+------------------------+------------------------+ +| |pxl| + |brisa| + |tri| | ++------------------------+------------------------+------------------------+ +| |wyca| + |elroy| + |birds| | ++------------------------+------------------------+------------------------+ +| |ubr1| + |Tiago| + |tb2| | ++------------------------+------------------------+------------------------+ +| |mpo_700| + |data| + |RB1| | ++------------------------+------------------------+------------------------+ +| |yunji| + |pm_boat| + |kar2| | ++------------------------+------------------------+------------------------+ +| |torch| + |ACFR| + |rover| | ++------------------------+------------------------+------------------------+ +| |tb4| + |tb3| + |rosbot_xl| | ++------------------------+------------------------+------------------------+ +| |saxion| + |botr| + |soon| | ++------------------------+------------------------+------------------------+ + +Research Robots +================ + ++------------------------+------------------------+------------------------+ +| |waratah| + |walking| + |soon| | ++------------------------+------------------------+------------------------+ + +.. |walking| image:: images/walking.png + :width: 100% + :align: middle + :alt: walking + :target: https://www.aztrobotics.com/walking-y2.html + +.. |saxion| image:: images/saxion.jpeg + :width: 100% + :align: middle + :alt: Saxion Robotics + :target: https://www.saxion.nl/ + +.. |G1| image:: images/g1.png + :width: 100% + :align: middle + :alt: Unitree G1 Humanoid + :target: https://www.unitree.com/ + +.. |Go2| image:: images/go2.png + :width: 100% + :align: middle + :alt: Unitree Go2 Quadruped + :target: https://www.unitree.com/ + +.. |barnowl| image:: images/barnowl.png + :width: 100% + :align: middle + :alt: Barn Owl + :target: https://barnowlag.com/ + +.. |botr| image:: images/botronics.png + :width: 100% + :align: middle + :alt: Botronics + :target: https://botronics.be/ + +.. |ACFR| image:: images/ACFR.png + :width: 100% + :align: middle + :alt: Australian Centre for Robotics + :target: https://robotics.sydney.edu.au/ + +.. |torch| image:: images/torch.png + :width: 100% + :align: middle + :alt: Torch Technologies + :target: https://torchtechnologies.com/ + +.. |pm_boat| image:: images/polymath_boat.png + :width: 100% + :align: middle + :alt: Polymath Robotics + :target: https://www.polymathrobotics.com/ + +.. |nova| image:: images/novacarter.png + :width: 100% + :align: middle + :alt: Nvidia Segway Nova Carter + :target: https://robotics.segway.com/nova-carter/ + +.. |kiwi| image:: images/kiwibot.png + :width: 100% + :align: middle + :alt: Kiwibot + :target: https://www.kiwibot.com/ + +.. |fire| image:: images/firefly.png + :width: 100% + :align: middle + :alt: Firefly Automatix + :target: https://fireflyautomatix.com/m220/ + +.. |karl| image:: images/karelics2.png + :width: 100% + :align: middle + :alt: Karelics + :target: https://karelics.fi/ + +.. |kar2| image:: images/karelics.png + :width: 100% + :align: middle + :alt: Karelics + :target: https://karelics.fi/ + +.. |data| image:: images/datavision.png + :width: 100% + :align: middle + :alt: Datavision Software + :target: https://rex.software + +.. |poly| image:: images/polymath.png + :width: 100% + :align: middle + :alt: Polymath Robotics + :target: https://www.polymathrobotics.com/ + +.. |birds| image:: images/birdseye.png + :width: 100% + :align: middle + :alt: Birds Eye + :target: https://www.birdseyerobotics.com/ + +.. |wyca| image:: images/wyca.png + :width: 100% + :align: middle + :alt: Wyca Robotics + :target: https://www.wyca-robotics.fr/ + +.. |dex| image:: images/dexory.png + :width: 100% + :align: middle + :alt: Dexory + :target: https://www.dexory.com/ + +.. |tri| image:: images/tri.png + :width: 100% + :align: middle + :alt: Olympics2020 + :target: https://www.tri.global/news/toyota-introduces-tris-t-tr1-a-virtual-mobility-2019-7-22/ + +.. |elroy| image:: images/elroy.png + :width: 100% + :align: middle + :alt: ElroyAir + :target: https://elroyair.com/ + +.. |ang| image:: images/angsa.png + :width: 100% + :align: middle + :alt: Angsa + :target: https://angsa-robotics.com/en-de/roboter/ + +.. |ses| image:: images/seasony.png + :width: 100% + :align: middle + :alt: Seasony + :target: https://www.seasony.io/ + +.. |pxl| image:: images/pixel.png + :width: 100% + :align: middle + :alt: Pixel + :target: https://pixel-robotics.eu/ + +.. |brisa| image:: images/brisa.png + :width: 100% + :align: middle + :alt: Brisa + :target: https://www.brisa.tech/ + +.. |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 + +.. |tb4| image:: images/tb4.png + :width: 100% + :align: middle + :alt: Turtlebot4 + :target: https://clearpathrobotics.com/turtlebot-4/ + +.. |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 + :width: 100% + :alt: Tiago Robot + :target: https://github.com/IntelligentRoboticsLabs/marathon_ros2 + +.. |ubr1| image:: images/ubr1.png + :align: middle + :width: 100% + :alt: UBR-1 + :target: https://www.robotandchisel.com/2020/09/01/navigation2 + +.. |mpo_700| image:: images/mpo_700.png + :width: 100% + :align: middle + :alt: Neobotix MPO-700 + :target: https://github.com/neobotix/neo_mpo_700-2 + +.. |soon| image:: images/soon.png + :width: 100% + :align: middle + :alt: Coming Soon + :target: https://www.youtube.com/watch?v=oHg5SJYRHA0 + +.. |rosie| image:: images/tailos.png + :width: 100% + :align: middle + :alt: Rosie + :target: https://tailos.com/ + +.. |rosbot_xl| image:: images/rosbot_xl.png + :width: 100% + :align: middle + :alt: Husarion ROSbot XL + :target: https://github.com/husarion/rosbot-xl-autonomy + +.. |waratah| image:: images/waratah.png + :width: 100% + :align: middle + :alt: Waratah from Monash Nova Rocer + :target: https://www.novarover.space/ diff --git a/about/roscon.rst b/about/roscon.rst new file mode 100644 index 0000000000..f303fe24d2 --- /dev/null +++ b/about/roscon.rst @@ -0,0 +1,29 @@ +.. _roscon: + +ROSCon Talks +############ + +Below is a list of ROSCon talks that have been given by the Nav2 team and the community which describe important features, tuning and configuration advice, and how to work with them in your applications. + +Nav2 Developer Talks +-------------------- + +- `ROSCon 2024: On Use of Nav2 Docking `_ +- `ROSCon FR 2023: Nav2 Whys over What's: Navigating the Philosophies Behind the Features `_ +- `ROSCon 2023: On Use of Nav2 MPPI Controller `_ +- `ROSCon 2023: Bidirectional navigation with Nav2 `_ +- `ROSCon 2022: On Use of Nav2 Smac Planners `_ +- `ROSCon JP 2021: The Past, Present, and Future of Navigation `_ +- `ROSCon 2021: Chronicles of Caching and Containerising CI for Nav2 `_ +- `ROSCon 2020: Navigation2: The Next Generation Navigation System `_ +- `ROSCon 2019: On Use of SLAM Toolbox `_ +- `ROSCon 2019: Navigation 2 Overview `_ +- `ROSCon 2018: On Use of the Spatio-Temporal Voxel Layer `_ + +Community's Talks +----------------- + +- `ROSCon ES 2024: Navegación robusta en ROS2 `_ +- `ROSCon 2022: BehaviorTree.CPP 4.0. What is new and roadmap `_ +- `ROSCon 2024: Mobile Robotics Scale-up Leveraging ROS `_ +- `ROSCon 2024: Radar Tracks for Path Planning in the presence of Dynamic Obstacles `_ diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence.png b/behavior_trees/images/control_nonblockingSequence.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence.png rename to behavior_trees/images/control_nonblockingSequence.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_RUNNING_RUNNING_RUNNING.png b/behavior_trees/images/control_nonblockingSequence_RUNNING_RUNNING_RUNNING.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_RUNNING_RUNNING_RUNNING.png rename to behavior_trees/images/control_nonblockingSequence_RUNNING_RUNNING_RUNNING.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_SUCCESS_RUNNING_RUNNING.png b/behavior_trees/images/control_nonblockingSequence_SUCCESS_RUNNING_RUNNING.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_SUCCESS_RUNNING_RUNNING.png rename to behavior_trees/images/control_nonblockingSequence_SUCCESS_RUNNING_RUNNING.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_SUCCESS_RUNNING_SUCCESS.png b/behavior_trees/images/control_nonblockingSequence_SUCCESS_RUNNING_SUCCESS.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_SUCCESS_RUNNING_SUCCESS.png rename to behavior_trees/images/control_nonblockingSequence_SUCCESS_RUNNING_SUCCESS.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_SUCCESS_SUCCESS_SUCCESS.png b/behavior_trees/images/control_nonblockingSequence_SUCCESS_SUCCESS_SUCCESS.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_nonblockingSequence_SUCCESS_SUCCESS_SUCCESS.png rename to behavior_trees/images/control_nonblockingSequence_SUCCESS_SUCCESS_SUCCESS.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence.png b/behavior_trees/images/control_pipelineSequence.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence.png rename to behavior_trees/images/control_pipelineSequence.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_RUNNING_IDLE_IDLE.png b/behavior_trees/images/control_pipelineSequence_RUNNING_IDLE_IDLE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_RUNNING_IDLE_IDLE.png rename to behavior_trees/images/control_pipelineSequence_RUNNING_IDLE_IDLE.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_RUNNING_SUCCESS_RUNNING.png b/behavior_trees/images/control_pipelineSequence_RUNNING_SUCCESS_RUNNING.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_RUNNING_SUCCESS_RUNNING.png rename to behavior_trees/images/control_pipelineSequence_RUNNING_SUCCESS_RUNNING.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_RUNNING_SUCCESS_SUCCESS.png b/behavior_trees/images/control_pipelineSequence_RUNNING_SUCCESS_SUCCESS.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_RUNNING_SUCCESS_SUCCESS.png rename to behavior_trees/images/control_pipelineSequence_RUNNING_SUCCESS_SUCCESS.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_SUCCESS_RUNNING_IDLE.png b/behavior_trees/images/control_pipelineSequence_SUCCESS_RUNNING_IDLE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_pipelineSequence_SUCCESS_RUNNING_IDLE.png rename to behavior_trees/images/control_pipelineSequence_SUCCESS_RUNNING_IDLE.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_recovery_node.png b/behavior_trees/images/control_recovery_node.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_recovery_node.png rename to behavior_trees/images/control_recovery_node.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin.png b/behavior_trees/images/control_round_robin.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin.png rename to behavior_trees/images/control_round_robin.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_FAILURE_RUNNING_IDLE.png b/behavior_trees/images/control_round_robin_FAILURE_RUNNING_IDLE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_FAILURE_RUNNING_IDLE.png rename to behavior_trees/images/control_round_robin_FAILURE_RUNNING_IDLE.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_FAILURE_SUCCESS_IDLE.png b/behavior_trees/images/control_round_robin_FAILURE_SUCCESS_IDLE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_FAILURE_SUCCESS_IDLE.png rename to behavior_trees/images/control_round_robin_FAILURE_SUCCESS_IDLE.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_FAILURE_SUCCESS_RUNNING.png b/behavior_trees/images/control_round_robin_FAILURE_SUCCESS_RUNNING.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_FAILURE_SUCCESS_RUNNING.png rename to behavior_trees/images/control_round_robin_FAILURE_SUCCESS_RUNNING.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_IDLE_IDLE_IDLE.png b/behavior_trees/images/control_round_robin_IDLE_IDLE_IDLE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_IDLE_IDLE_IDLE.png rename to behavior_trees/images/control_round_robin_IDLE_IDLE_IDLE.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_RUNNING_IDLE_FAILURE.png b/behavior_trees/images/control_round_robin_RUNNING_IDLE_FAILURE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_RUNNING_IDLE_FAILURE.png rename to behavior_trees/images/control_round_robin_RUNNING_IDLE_FAILURE.png diff --git a/docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_RUNNING_IDLE_IDLE.png b/behavior_trees/images/control_round_robin_RUNNING_IDLE_IDLE.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/nav2_specific_nodes/assets/control_round_robin_RUNNING_IDLE_IDLE.png rename to behavior_trees/images/control_round_robin_RUNNING_IDLE_IDLE.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/contextual_recoveries.png b/behavior_trees/images/walkthrough/contextual_recoveries.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/contextual_recoveries.png rename to behavior_trees/images/walkthrough/contextual_recoveries.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/navigation_subtree.png b/behavior_trees/images/walkthrough/navigation_subtree.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/navigation_subtree.png rename to behavior_trees/images/walkthrough/navigation_subtree.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/navigation_subtree_bare.png b/behavior_trees/images/walkthrough/navigation_subtree_bare.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/navigation_subtree_bare.png rename to behavior_trees/images/walkthrough/navigation_subtree_bare.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/overall_bt.png b/behavior_trees/images/walkthrough/overall_bt.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/overall_bt.png rename to behavior_trees/images/walkthrough/overall_bt.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/overall_bt_w_breakdown.png b/behavior_trees/images/walkthrough/overall_bt_w_breakdown.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/overall_bt_w_breakdown.png rename to behavior_trees/images/walkthrough/overall_bt_w_breakdown.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/patience_and_recovery.png b/behavior_trees/images/walkthrough/patience_and_recovery.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/patience_and_recovery.png rename to behavior_trees/images/walkthrough/patience_and_recovery.png diff --git a/docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/recovery_subtree.png b/behavior_trees/images/walkthrough/recovery_subtree.png similarity index 100% rename from docs/getting_started/nav2_behavior_trees/detailed_behavior_tree_walkthrough/assets/recovery_subtree.png rename to behavior_trees/images/walkthrough/recovery_subtree.png diff --git a/behavior_trees/index.rst b/behavior_trees/index.rst new file mode 100644 index 0000000000..c8d44022bf --- /dev/null +++ b/behavior_trees/index.rst @@ -0,0 +1,54 @@ +.. _behavior_trees: + +Nav2 Behavior Trees +################### + +.. toctree:: + :maxdepth: 1 + + overview/nav2_specific_nodes.rst + overview/detailed_behavior_tree_walkthrough.rst + trees/nav_to_pose_recovery.rst + trees/nav_through_poses_recovery.rst + trees/nav_to_pose_and_pause_near_goal_obstacle.rst + trees/nav_to_pose_with_consistent_replanning_and_if_path_becomes_invalid.rst + trees/navigate_on_route_graph_w_recovery.rst + trees/follow_point.rst + trees/odometry_calibration.rst + +Nav2 is an incredibly reconfigurable project. It allows users to set many different plugin types, across behavior trees, core algorithms, status checkers, and more! +This section highlights some of the example behavior tree xml files provided by default in the project to do interesting tasks. +It should be noted that these can be modified for your specific application, or used as a guide to building your own application-specific behavior tree. +These are some exemplary examples of how you can reconfigure your navigation behavior significantly by using behavior trees. +Other behavior trees are provided by Nav2 in the ``nav2_bt_navigator`` package, but this section highlights the important ones. + +A **very** basic, but functional, navigator can be seen below. + +.. code-block:: xml + + + + + + + + + + + + +This behavior tree will simply plan a new path to ``goal`` every 1 meter (set by ``DistanceController``) using ``ComputePathToPose``. +If a new path is computed on the ``path`` blackboard variable, ``FollowPath`` will take this ``path`` and follow it using the server's default algorithm. + +This tree contains: + +- No recovery methods +- No retries on failure +- No selected planner or controller algorithms +- No nodes to contextually change settings for optimal performance +- No integration with automatic door, elevator, or other APIs +- No user provided custom BT nodes +- No subtrees for other behaviors like docking, following, etc. +- No use of other types of planners, like complete coverage (where useful) + +All of this, and more, can be set and configured for your customized navigation logic in Nav2. diff --git a/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst b/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst new file mode 100644 index 0000000000..2939fcf447 --- /dev/null +++ b/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst @@ -0,0 +1,325 @@ +.. _detailed_behavior_tree_walkthrough: + +Detailed Behavior Tree Walkthrough +********************************** + +- `Overview`_ +- `Prerequisites`_ +- `Navigate To Pose With Replanning and Recovery`_ +- `Navigation Subtree`_ +- `Recovery Subtree`_ + +Overview +======== + +This document serves as a reference guide to the main behavior tree (BT) used in Nav2. + +There are many example behavior trees provided in ``nav2_bt_navigator/behavior_trees``, +but these sometimes have to be re-configured based on the application of the robot. +The following document will walk through the current main default BT ``navigate_to_pose_w_replanning_and_recovery.xml`` +in great detail. + +Prerequisites +============= + +- Become familiar with the concept of a behavior tree before continuing with this walkthrough + + - Read the short explanation in `navigation concepts <../../concepts/index.html>`_ + + - Read the general tutorial and guide (not Nav2 specific) on the `BehaviorTree CPP V4 `_ website. Specifically, the "Basic Concepts" section on the BehaviorTree CPP V4 website explains the basic generic nodes that will be used that this guide will build upon. + +- Become familiar with the custom `Nav2 specific BT nodes `_ + +Navigate To Pose With Replanning and Recovery +============================================= + +The following section will describe in detail the concept of the main and default BT currently used in Nav2, ``navigate_to_pose_w_replanning_and_recovery.xml``. +This behavior tree replans the global path periodically at 1 Hz and it also has recovery actions. + +| + + .. image:: ../images/walkthrough/overall_bt.png + :align: center + +| + +BTs are primarily defined in XML. The tree shown above is represented in XML as follows. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +This is likely still a bit overwhelming, but this tree can be broken into two smaller subtrees that we can focus on one at a time. +These smaller subtrees are the children of the top-most ``RecoveryNode``. From this point forward the ``NavigateWithReplanning`` subtree will be referred to as the ``Navigation`` subtree, and the ``RecoveryFallback`` subtree will be known as the ``Recovery`` subtree. +This can be represented in the following way: + +| + + .. image:: ../images/walkthrough/overall_bt_w_breakdown.png + :align: center + +| + +The ``Navigation`` subtree mainly involves actual navigation behavior: + +- selecting planners / controllers / goal checkers / path handlers / progress checkers plugins + +- calculating a path + +- following a path + +- contextual recovery behaviors for each of the above primary navigation behaviors + +The ``Recovery`` subtree includes behaviors for system level failures or items that were not easily dealt with internally. + +The overall BT will (hopefully) spend most of its time in the ``Navigation`` subtree. If either of the two main behaviors in the ``Navigation`` subtree fail +(path calculation or path following), contextual recoveries will be attempted. + +If the contextual recoveries were still not enough, the ``Navigation`` subtree will return ``FAILURE``. +The system will move on to the ``Recovery`` subtree to attempt to clear any system level navigation failures. + +This happens until the ``number_of_retries`` for the parent ``RecoveryNode`` is exceeded (which by default is 6). + +.. code-block:: xml + + + +Navigation Subtree +====================== + +Now that we have gone over the control flow between the ``Navigation`` subtree and the ``Recovery`` subtree, let's focus on the Navigation subtree. + +| + + .. image:: ../images/walkthrough/navigation_subtree.png + :align: center + +| + +The XML of this subtree is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +This subtree has two primary actions ``ComputePathToPose`` and ``FollowPath``. +If either of these two actions fail, they will attempt to clear the failure contextually. +The crux of the tree can be represented with only one parent and two children nodes like this: + +| + + .. image:: ../images/walkthrough/navigation_subtree_bare.png + :align: center + +| + +The parent ``PipelineSequence`` node allows the ``ComputePathToPose`` to be ticked, and once that succeeds, ``FollowPath`` to be ticked. +While the ``FollowPath`` subtree is being ticked, the ``ComputePathToPose`` subtree will be ticked as well. This allows for the path to be recomputed as the robot moves around. + +Both the ``ComputePathToPose`` and the ``FollowPath`` follow the same general structure. + +- Do the action + +- If the action fails, try to see if we can contextually recover + +The below is the ``ComputePathToPose`` subtree: + +| + + .. image:: ../images/walkthrough/contextual_recoveries.png + :align: center + +| + +The parent ``RecoveryNode`` controls the flow between the action, and the contextual recovery subtree. +The contextual recoveries for both ``ComputePathToPose`` and ``FollowPath`` involve checking if the recovery could help clear the error code and clearing the relevant costmap. + +Consider changing the ``number_of_retries`` parameter in the parent ``RecoveryNode`` control node if your application can tolerate more attempts at contextual recoveries before moving on to system-level recoveries. + +The only differences in the BT subtree of ``ComputePathToPose`` and ``FollowPath`` are outlined below: + +- The action node in the subtree: + - The ``ComputePathToPose`` subtree centers around the ``ComputePathToPose`` action. + - The ``FollowPath`` subtree centers around the ``FollowPath`` action. + +- The use of conditional flow control (``Fallback``): + - The ``ComputePathToPose`` subtree incorporates logic to handle the robot's behavior as it nears the goal. When using feasible planners, re-planning within a small radius (e.g., < 1.0m) can be detrimental due to state estimation drift or path-tracking errors, often resulting in unnecessary "looping" behaviors. + To prevent this, the subtree uses a ``ReactiveSequence`` with the ``IsGoalNearby`` node. If the robot is within a specified proximity threshold and the current path remains valid (i.e., no new obstacles), the subtree will skip the re-planning request. This allows the robot to smoothly transition into its final approach using its current path without unnecessary re-planning. + - The ``FollowPath`` subtree, by contrast, does not typically use this conditional gating. Once a path is available, the controller is invoked directly to produce velocity commands. +- The ``RateController`` that decorates the ``ComputePathToPose`` subtree + The ``RateController`` decorates the ``ComputePathToPose`` subtree to keep planning at the specified frequency. The default frequency for this BT is 1 hz. + This is done to prevent the BT from flooding the planning server with too many useless requests at the tree update rate (100Hz). Consider changing this frequency to something higher or lower depending on the application and the computational cost of + calculating the path. There are other decorators that can be used instead of the ``RateController``. Consider using the ``SpeedController`` or ``DistanceController`` decorators if appropriate. + +- The costmap that is being cleared within the contextual recovery: + - The ``ComputePathToPose`` subtree clears the global costmap. The global costmap is the relevant costmap in the context of the planner + - The ``FollowPath`` subtree clears the local costmap. The local costmap is the relevant costmap in the context of the controller + +This subtree also utilizes the ``PlannerSelector``, ``ControllerSelector``, ``GoalCheckerSelector``, ``ProgressCheckerSelector``, and ``PathHandlerSelector`` nodes. These nodes offer flexibility for applications that need to adjust navigation behavior on the fly. + +Recovery Subtree +================ + +The ``Recovery`` subtree is the second big "half" of the Nav2 default ``navigate_to_pose_w_replanning_and_recovery.xml`` tree. +In short, this subtree is triggered when the ``Navigation`` subtree returns ``FAILURE`` and controls the recoveries at the system level (in the case the contextual recoveries in the ``Navigation`` subtree were not sufficient). + +| + + .. image:: ../images/walkthrough/recovery_subtree.png + :align: center + +| + +And the XML snippet: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + +At the top level, a ``Sequence`` ensures the following steps are executed in order: + +- A ``Fallback`` node first checks whether planner or controller recoveries might help resolve the issue. If either returns ``SUCCESS``, the fallback succeeds and the sequence proceeds to the next step. + +- A ``ReactiveFallback`` that controls the flow between the rest of the system wide recoveries, and asynchronously checks if a new goal has been received. + +If at any point the goal gets updated, this subtree will halt all children and return ``SUCCESS``. This allows for quick reactions to new goals and preempt currently executing recoveries. +This should look familiar to the contextual recovery portions of the ``Navigation`` subtree. This is a common BT pattern to handle the situation "Unless 'this condition' happens, Do action A". + +These condition nodes can be extremely powerful and are typically paired with ``ReactiveFallback``. It can be easy to imagine wrapping this whole ``navigate_to_pose_w_replanning_and_recovery`` tree +in a ``ReactiveFallback`` with a ``isBatteryLow`` condition -- meaning the ``navigate_to_pose_w_replanning_and_recovery`` tree will execute *unless* the battery becomes low (and then enter a different subtree for docking to recharge). + +If the goal is never updated, the behavior tree will go on to the ``RoundRobin`` node. These are the default four system-level recoveries in the BT are: + +- A sequence that clears both costmaps (local, and global) + +- ``Spin`` action + +- ``Wait`` action + +- ``BackUp`` action + +Upon ``SUCCESS`` of any of the four children of the parent ``RoundRobin``, the robot will attempt to renavigate in the ``Navigation`` subtree. +If this renavigation was not successful, the next child of the ``RoundRobin`` will be ticked. + +For example, let's say the robot is stuck and the ``Navigation`` subtree returns ``FAILURE``: +(for the sake of this example, let's assume that the goal is never updated). + +1. The Costmap clearing sequence in the ``Recovery`` subtree is attempted, and returns ``SUCCESS``. The robot now moves to ``Navigation`` subtree again + +2. Let's assume that clearing both costmaps was not sufficient, and the ``Navigation`` subtree returns ``FAILURE`` once again. The robot now ticks the ``Recovery`` subtree + +3. In the ``Recovery`` subtree, the ``Spin`` action will be ticked. If this returns ``SUCCESS``, then the robot will return to the main ``Navigation`` subtree *BUT* let's assume that the ``Spin`` action returns ``FAILURE``. In this case, the tree will *remain* in the ``Recovery`` subtree + +4. Let's say the next action, ``Wait`` returns ``SUCCESS``. The robot will then move on to the ``Navigation`` subtree + +5. Assume the ``Navigation`` subtree returns ``FAILURE`` (clearing the costmaps, attempting a spin, and waiting were *still* not sufficient to recover the system). The robot will move onto the ``Recovery`` subtree and attempt the ``BackUp`` action. Let's say that the robot attempts the ``BackUp`` action and was able to successfully complete the action. The ``BackUp`` action node returns ``SUCCESS`` and so now we move on to the Navigation subtree again. + +6. In this hypothetical scenario, let's assume that the ``BackUp`` action allowed the robot to successfully navigate in the ``Navigation`` subtree, and the robot reaches the goal. In this case, the overall BT will still return ``SUCCESS``. + +If the ``BackUp`` action was not sufficient enough to allow the robot to become un-stuck, the above logic will go on indefinitely until the ``number_of_retries`` in the parent of the ``Navigate`` subtree and ``Recovery`` subtree is exceeded, or if all the system-wide recoveries in the ``Recovery`` subtree return ``FAILURE`` (this is unlikely, and likely points to some other system failure). diff --git a/behavior_trees/overview/nav2_specific_nodes.rst b/behavior_trees/overview/nav2_specific_nodes.rst new file mode 100644 index 0000000000..b36c0bf78c --- /dev/null +++ b/behavior_trees/overview/nav2_specific_nodes.rst @@ -0,0 +1,385 @@ +.. _nav2_specific_nodes: + +Introduction To Nav2 Specific Nodes +=================================== +.. warning:: + Vocabulary can be a large point of confusion here when first starting out. + - A ``Node`` when discussing BTs is entirely different than a ``Node`` in the ROS 2 context + + - An ``ActionNode`` in the context of BTs is not necessarily connected to an Action Server in the ROS 2 context (but often it is) + +There are quite a few custom Nav2 BT nodes that are provided to be used in the Nav2 specific fashion. Some commonly used Nav2 nodes will be described below. +The full list of custom BT nodes can be found in the `nav2_behavior_tree plugins folder `_. +The `configuration guide <../../configuration/packages/configuring-bt-xml.html>`_ can also be quite useful. + +Action Nodes +------------ + +* ComputePathToPose - ComputePathToPose Action Server Client (Planner Interface) + +* FollowPath - FollowPath Action Server Client (Controller Interface) + +* Spin, Wait, Backup - Behaviors Action Server Client + +* ClearCostmapService - ClearCostmapService Server Clients + +Upon completion, these action nodes will return ``SUCCESS`` if the action server believes the action has been completed correctly, ``RUNNING`` when still running, and will return ``FAILURE`` otherwise. Note that in the above list, +the `ClearCostmapService` action node is *not* an action server client, but a service client. + +Condition Nodes +--------------- + +* GoalUpdated - Checks if the goal on the goal topic has been updated + +* GoalReached - Checks if the goal has been reached + +* InitialPoseReceived - Checks to see if a pose on the ``initial_pose`` topic has been received + +* isBatteryLow - Checks to see if the battery is low by listening on the battery topic + +The above list of condition nodes can be used to probe particular aspects of the system. Typically they will return ``SUCCESS`` if the condition is true and ``FAILURE`` otherwise. +The key condition that is used in the default Nav2 BT is ``GoalUpdated`` which is checked asynchronously within particular subtrees. This condition node allows for the behavior described as "If the goal has been updated, then we must replan". +Condition nodes are typically paired with ReactiveFallback nodes. + +Decorator Nodes +--------------- + +* Distance Controller - Will tick children nodes every time the robot has traveled a certain distance + +* Rate Controller - Controls the ticking of its child node at a constant frequency. The tick rate is an exposed port + +* Goal Updater - Will update the goal of children nodes via ports on the BT + +* Single Trigger - Will only tick its child node once, and will return ``FAILURE`` for all subsequent ticks + +* Speed Controller - Controls the ticking of its child node at a rate proportional to the robot's speed + +Control: PipelineSequence +------------------------- +The ``PipelineSequence`` control node re-ticks previous children when a child returns ``RUNNING``. +This node is similar to the ``Sequence`` node, with the additional property that the children prior to the "current" are re-ticked, (resembling the flow of water in a pipe). +If at any point a child returns ``FAILURE``, all children will be halted and the parent node will also return ``FAILURE``. Upon ``SUCCESS`` of the **last node** in the sequence, this node will halt and return ``SUCCESS``. + +To explain this further, here is an example BT that uses PipelineSequence. + +| + + .. image:: ../images/control_pipelineSequence.png + :align: center + +| + +.. code-block:: xml + + + + + + + + + + + +1. ``Action_A``, ``Action_B``, and ``Action_C`` are all ``IDLE``. +2. When the parent PipelineSequence is first ticked, let's assume ``Action_A`` returns ``RUNNING``. The parent node will now return ``RUNNING`` and no other nodes are ticked. + +| + + .. image:: ../images/control_pipelineSequence_RUNNING_IDLE_IDLE.png + :align: center + +| + +3. Now, let's assume ``Action_A`` returns ``SUCCESS``, ``Action_B`` will now get ticked and will return ``RUNNING``. ``Action_C`` has not yet been ticked so will return ``IDLE``. + +| + + .. image:: ../images/control_pipelineSequence_SUCCESS_RUNNING_IDLE.png + :align: center + +| + +4. ``Action_A`` gets ticked again and returns ``RUNNING``, and ``Action_B`` gets re-ticked and returns ``SUCCESS`` and therefore the BT goes on to tick ``Action_C`` for the first time. Let's assume ``Action_C`` returns ``RUNNING``. The retick-ing of ``Action_A`` is what makes PipelineSequence useful. + +| + + .. image:: ../images/control_pipelineSequence_RUNNING_SUCCESS_RUNNING.png + :align: center + +| + +5. All actions in the sequence will be re-ticked. Let's assume ``Action_A`` still returns ``RUNNING``, where as ``Action_B`` returns ``SUCCESS`` again, and ``Action_C`` now returns ``SUCCESS`` on this tick. The sequence is now complete, and therefore ``Action_A`` is halted, even though it was still ``RUNNING``. + +| + + .. image:: ../images/control_pipelineSequence_RUNNING_SUCCESS_SUCCESS.png + :align: center + +| + +Recall that if ``Action_A``, ``Action_B``, or ``Action_C`` returned ``FAILURE`` at any point of time, the parent would have returned ``FAILURE`` and halted any children as well. + +For additional details regarding the ``PipelineSequence`` please see the `PipelineSequence configuration guide <../../configuration/packages/bt-plugins/controls/PipelineSequence.html>`_. + +Control: Recovery +--------------------- +The Recovery control node has only two children and returns ``SUCCESS`` if and only if the first child returns ``SUCCESS``. +If the first child returns ``FAILURE``, the second child will be ticked. This loop will continue until either: + +* The first child returns ``SUCCESS`` (which results in ``SUCCESS`` of the parent node) + +* The second child returns ``FAILURE`` (which results in ``FAILURE`` of the parent node) + +* The ``number_of_retries`` input parameter is violated + +This node is usually used to link together an action, and a recovery action as the name suggests. The first action will typically be the "main" behavior, +and the second action will be something to be done in case of ``FAILURE`` of the main behavior. Often, the ticking of the second child action will promote the chance the first action will succeed. + +| + + .. image:: ../images/control_recovery_node.png + :align: center + +| + +.. code-block:: xml + + + + + + + + + + +In the above example, let's assume ``ComputePathToPose`` fails. ``ClearLocalCostmap`` will be ticked in response, and return ``SUCCESS``. +Now that we have cleared the costmap, let's say the robot is correctly able to compute the path and ``ComputePathToPose`` now returns ``SUCCESS``. Then, the parent RecoveryNode will also return ``SUCCESS`` and the BT will be complete. + +For additional details regarding the ``RecoveryNode`` please see the `RecoveryNode configuration guide <../../configuration/packages/bt-plugins/controls/RecoveryNode.html>`_. + +Control: RoundRobin +----------------------- +The RoundRobin control node ticks its children in a round robin fashion until a child returns ``SUCCESS``, in which the parent node will also return ``SUCCESS``. +If all children return ``FAILURE`` so will the parent RoundRobin. + +Here is an example BT we will use to walk through the concept. + +| + + .. image:: ../images/control_round_robin.png + :align: center + +| + +.. code-block:: xml + + + + + + + + + + + +1. All the nodes start at ``IDLE`` + +| + + .. image:: ../images/control_round_robin_IDLE_IDLE_IDLE.png + :align: center + +| + +2. Upon tick of the parent node, the first child (``Action_A``) is ticked. Let's assume on tick the child returns ``RUNNING``. +In this case, no other children are ticked and the parent node returns ``RUNNING`` as well. + +| + + .. image:: ../images/control_round_robin_RUNNING_IDLE_IDLE.png + :align: center + +| + +3. Upon the next tick, let's assume that ``Action_A`` returns ``FAILURE``. +This means that ``Action_B`` will get ticked next, and ``Action_C`` remains unticked. +Let's assume ``Action_B`` returns ``RUNNING`` this time. That means the parent RoundRobin node will also return ``RUNNING``. + +| + + .. image:: ../images/control_round_robin_FAILURE_RUNNING_IDLE.png + :align: center + +| + +4. Upon this next tick, let's assume that ``Action_B`` returns ``SUCCESS``. The parent RoundRobin will now halt all children and return ``SUCCESS``. +The parent node retains this state information, and will tick ``Action_C`` upon the next tick rather than start from ``Action_A`` like Step 2 did. + +| + + .. image:: ../images/control_round_robin_FAILURE_SUCCESS_IDLE.png + :align: center + +| + +5. On this tick, let's assume ``Action_C`` returns ``RUNNING``, and so does the parent RoundRobin. No other nodes are ticked. + +| + + .. image:: ../images/control_round_robin_FAILURE_SUCCESS_RUNNING.png + :align: center + +| + + +6. On this last tick, let's assume ``Action_C`` returns ``FAILURE``. The parent will circle and tick ``Action_A`` again. ``Action_A`` returns ``RUNNING`` and so will the parent RoundRobin node. This pattern will continue indefinitely unless all children return ``FAILURE``. + +| + + .. image:: ../images/control_round_robin_RUNNING_IDLE_FAILURE.png + :align: center + +| + +For additional details regarding the ``RoundRobin`` please see the `RoundRobin configuration guide <../../configuration/packages/bt-plugins/controls/RoundRobin.html>`_. + +Control: NonblockingSequence +---------------------------- + +The ``NonblockingSequence`` control node ticks all children as long as they return ``SUCCESS`` or ``RUNNING``. This node is similar to the ``PipelineSequence`` node, with the additional property that all children are re-ticked as long as ``SUCCESS`` or ``RUNNING``, instead of stopping at the latest ``RUNNING`` node. If at any point a child returns ``FAILURE``, all children will be halted and the parent node will also return ``FAILURE``. Upon ``SUCCESS`` of **all nodes** in the sequence, this node will halt and return ``SUCCESS``. + +Note that even if a node returns ``SUCCESS`` in a previous tick, on the next tick, the ``NonblockingSequence`` will still tick the successful node, possibly restarting it. This is to ensure that successful nodes do not latch a stale state while waiting for another long running node to be complete + +To explain this further, here is an example BT that uses NonblockingSequence. + +| + + .. image:: ../images/control_nonblockingSequence.png + :align: center + + + +.. code-block:: xml + + + + + + + + + + + +1. ``Action_A``, ``Action_B``, and ``Action_C`` are all ``IDLE``. + +2. When the parent NonblockingSequence is first ticked, let's assume ``Action_A`` returns ``RUNNING``. Following this, ``Action_B`` will be ticked, and let's assume it also returns ``RUNNING``. Finally, ``Action_C`` will be ticked, and let's assume it also returns ``RUNNING``. With three ``RUNNING`` children, the NonblockingSequence will return ``RUNNING`` + +| + + .. image:: ../images/control_nonblockingSequence_RUNNING_RUNNING_RUNNING.png + :align: center + +| + +3. On the next tick of the the parent NonblockingSequence, all actions in the sequence will be re-ticked. Let's assume ``Action_A`` returns ``SUCCESS``, and ``Action_B`` and ``Action_C`` still return ``RUNNING``. In this configuration, the NonblockingSequence still returns ``RUNNING``, as there are two nodes in the children that are ``RUNNING`` + +| + + .. image:: ../images/control_nonblockingSequence_SUCCESS_RUNNING_RUNNING.png + :align: center + +| + +4. Now, let's assume on the next re-tick, ``Action_A`` and ``Action_C`` return ``SUCCESS``, and ``Action_B`` returns ``RUNNING``. In this configuration, the NonblockingSequence still returns ``RUNNING``, as there is still one child node that is ``RUNNING``. Note that ``ActionA`` was re-ticked and again returned ``SUCCESS`` in this case, it did not skip due to previously returning `SUCCESS``. + +| + + .. image:: ../images/control_nonblockingSequence_SUCCESS_RUNNING_SUCCESS.png + :align: center + +| + +5. Finally, Let's assume ``Action_A``, ``Action_B``, and ``Action_C`` all return ``SUCCESS``. The sequence is now complete, and therefore ``Action_A``, ``Action_B``, and ``Action_C`` are all halted and NonblockingSequence returns ``SUCCESS``. + +| + + .. image:: ../images/control_nonblockingSequence_SUCCESS_SUCCESS_SUCCESS.png + :align: center + +| + +Recall that if ``Action_A``, ``Action_B``, or ``Action_C`` returned ``FAILURE`` at any point of time, the parent would have returned ``FAILURE`` and halted any children as well. + +For additional details regarding the ``NonblockingSequence`` please see the `NonblockingSequence configuration guide <../../configuration/packages/bt-plugins/controls/NonblockingSequence.html>`_. + +Control: PersistentSequence +---------------------------- + +The ``PersistentSequence`` is similar to the ``Sequence`` node, but it stores the index of the last running child in the blackboard (key: "current_child_idx"), and it does not reset the index on halt. + +For more information see the ``Sequence`` BT node in BT.CPP. + +.. code-block:: xml + + + +