diff --git a/.codespell_words b/.codespell_words new file mode 100644 index 000000000..cd06cd2c6 --- /dev/null +++ b/.codespell_words @@ -0,0 +1,5 @@ +Configurating +Segway +implementors +retuned +segway diff --git a/.github/workflows/precommit.yaml b/.github/workflows/precommit.yaml new file mode 100644 index 000000000..6a474d2cc --- /dev/null +++ b/.github/workflows/precommit.yaml @@ -0,0 +1,15 @@ +--- +name: pre-commit + +on: + pull_request: + push: + branches: [main] + +jobs: + pre-commit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v3 + - uses: pre-commit/action@v3.0.1 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..0e044ae20 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,23 @@ +# To use: +# +# pre-commit run -a +# +# Or: +# +# pre-commit install # (runs every time you commit in git) +# +# To update this file: +# +# pre-commit autoupdate +# +# See https://github.com/pre-commit/pre-commit +--- +repos: + # Spellcheck in comments and docs + # skipping of *.svg files is not working... + - repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + args: ['--write-changes', '--ignore-words=.codespell_words'] + exclude: CHANGELOG\.rst|\.(svg|pyc|drawio|dcf|eds)$ diff --git a/2021summerOfCode/projects/create_configuration_assistant.rst b/2021summerOfCode/projects/create_configuration_assistant.rst index 02340a782..fbafe4b55 100644 --- a/2021summerOfCode/projects/create_configuration_assistant.rst +++ b/2021summerOfCode/projects/create_configuration_assistant.rst @@ -7,7 +7,7 @@ **Task description** -`Moveit `_ has long has a QT `configuration assistant `_. This setup assistent helps the user configure their UDRF and needs to setup MoveIt configuration files. +`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: diff --git a/2021summerOfCode/projects/multithreading.rst b/2021summerOfCode/projects/multithreading.rst index a7a9e3880..89f8d878a 100644 --- a/2021summerOfCode/projects/multithreading.rst +++ b/2021summerOfCode/projects/multithreading.rst @@ -12,7 +12,7 @@ Some examples include: - AMCL particle cloud updates - Costmap layer updates - Costmap sensor data population -- Controller critic evalulation +- Controller critic evaluation - Collision checking - Voxel grid ray casting - and more. diff --git a/2021summerOfCode/projects/semantics.rst b/2021summerOfCode/projects/semantics.rst index 00ccea683..7de827f95 100644 --- a/2021summerOfCode/projects/semantics.rst +++ b/2021summerOfCode/projects/semantics.rst @@ -18,7 +18,7 @@ After creating the generic representation, your project will be to create demons **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, retreive, or analyze semantic data for custom purposes +- 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) diff --git a/2021summerOfCode/projects/spinners.rst b/2021summerOfCode/projects/spinners.rst index d0f534cba..5ebb2e134 100644 --- a/2021summerOfCode/projects/spinners.rst +++ b/2021summerOfCode/projects/spinners.rst @@ -11,7 +11,7 @@ This project is admittedly abstract to explain to someone unfamiliar with the in 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 existance. 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. +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. diff --git a/configuration/packages/bt-plugins/actions/AssistedTeleop.rst b/configuration/packages/bt-plugins/actions/AssistedTeleop.rst index a30427e45..8f9effa22 100644 --- a/configuration/packages/bt-plugins/actions/AssistedTeleop.rst +++ b/configuration/packages/bt-plugins/actions/AssistedTeleop.rst @@ -33,7 +33,7 @@ Input Ports ====== ======= Description - Time to envoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). + Time to invoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). :server_name: diff --git a/configuration/packages/bt-plugins/actions/BackUp.rst b/configuration/packages/bt-plugins/actions/BackUp.rst index d3359974d..c3b66c4da 100644 --- a/configuration/packages/bt-plugins/actions/BackUp.rst +++ b/configuration/packages/bt-plugins/actions/BackUp.rst @@ -43,7 +43,7 @@ Input Ports ====== ======= Description - Time to envoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). + Time to invoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). :server_name: diff --git a/configuration/packages/bt-plugins/actions/DriveOnHeading.rst b/configuration/packages/bt-plugins/actions/DriveOnHeading.rst index 47525f346..0f66028f0 100644 --- a/configuration/packages/bt-plugins/actions/DriveOnHeading.rst +++ b/configuration/packages/bt-plugins/actions/DriveOnHeading.rst @@ -42,7 +42,7 @@ Input Ports ====== ======= Description - Time to envoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). + Time to invoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). :server_name: diff --git a/configuration/packages/bt-plugins/actions/Spin.rst b/configuration/packages/bt-plugins/actions/Spin.rst index 194b124b7..ed382943a 100644 --- a/configuration/packages/bt-plugins/actions/Spin.rst +++ b/configuration/packages/bt-plugins/actions/Spin.rst @@ -32,7 +32,7 @@ Input Ports ====== ======= Description - Time to envoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). + Time to invoke behavior for, if exceeds considers it a stuck condition or failure case (seconds). :server_name: diff --git a/configuration/packages/bt-plugins/actions/TruncatePath.rst b/configuration/packages/bt-plugins/actions/TruncatePath.rst index bcc894697..56279ce95 100644 --- a/configuration/packages/bt-plugins/actions/TruncatePath.rst +++ b/configuration/packages/bt-plugins/actions/TruncatePath.rst @@ -30,8 +30,8 @@ Input Ports Description The distance to the original goal for truncating the path. -Ouput Ports ------------ +Output Ports +------------ :output_path: diff --git a/configuration/packages/bt-plugins/actions/TruncatePathLocal.rst b/configuration/packages/bt-plugins/actions/TruncatePathLocal.rst index cb561a749..2b86647f1 100644 --- a/configuration/packages/bt-plugins/actions/TruncatePathLocal.rst +++ b/configuration/packages/bt-plugins/actions/TruncatePathLocal.rst @@ -96,8 +96,8 @@ Input Ports Description Maximum forward integrated distance along the path (starting from the last detected pose) to bound the search for the closest pose to the robot. When set to infinity (default), whole path is searched every time. -Ouput Ports ------------ +Output Ports +------------ :output_path: diff --git a/configuration/packages/bt-plugins/controls/RoundRobin.rst b/configuration/packages/bt-plugins/controls/RoundRobin.rst index 5a42179a5..b5ea94ce6 100644 --- a/configuration/packages/bt-plugins/controls/RoundRobin.rst +++ b/configuration/packages/bt-plugins/controls/RoundRobin.rst @@ -4,7 +4,7 @@ RoundRobin ========== -Custom control flow node used to create a round-robbin behavior for children BT nodes. +Custom control flow node used to create a round-robin behavior for children BT nodes. Example ------- diff --git a/configuration/packages/collision_monitor/configuring-collision-detector-node.rst b/configuration/packages/collision_monitor/configuring-collision-detector-node.rst index cecac0083..c2365bd0e 100644 --- a/configuration/packages/collision_monitor/configuring-collision-detector-node.rst +++ b/configuration/packages/collision_monitor/configuring-collision-detector-node.rst @@ -75,7 +75,7 @@ Parameters ============== ============================= Description: - Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting ``source_timeout: 0.0`` disables it. This parameter can be overriden per observation source. + Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting ``source_timeout: 0.0`` disables it. This parameter can be overridden per observation source. :base_shift_correction: @@ -136,7 +136,7 @@ Polygons parameters ============== ============================= Description: - Polygon vertexes, listed in ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]"`` format (e.g. ``"[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]"`` for the square in the front). Used for ``polygon`` type. Minimum 3 points for a triangle polygon. If not specified, the collision detector will use dynamic polygon subscription to ``polygon_sub_topic`` + Polygon vertices, listed in ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]"`` format (e.g. ``"[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]"`` for the square in the front). Used for ``polygon`` type. Minimum 3 points for a triangle polygon. If not specified, the collision detector will use dynamic polygon subscription to ``polygon_sub_topic`` :````.polygon_sub_topic: diff --git a/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst b/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst index 67a6c2d51..b2e55eb6a 100644 --- a/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst +++ b/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst @@ -137,7 +137,7 @@ Parameters ============== ============================= Description: - Maximum time interval in which source data is considered as valid. If no new data is received within this interval, the robot will be stopped. Setting ``source_timeout: 0.0`` disables this blocking mechanism. This parameter can be overriden per observation source. + Maximum time interval in which source data is considered as valid. If no new data is received within this interval, the robot will be stopped. Setting ``source_timeout: 0.0`` disables this blocking mechanism. This parameter can be overridden per observation source. :base_shift_correction: @@ -193,7 +193,7 @@ Parameters ============== ======= Description - Adds soft real-time priorization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` + Adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` :enable_stamped_cmd_vel: @@ -232,7 +232,7 @@ Polygons parameters ============== ============================= Description: - Polygon vertexes, listed in ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]"`` format (e.g. ``"[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]"`` for the square in the front). Used for ``polygon`` type. Minimum 3 points for a triangle polygon. If not specified, the collision monitor will use dynamic polygon subscription to ``polygon_sub_topic`` for points in the ``stop``/``slowdown``/``limit`` action types, or footprint subscriber to ``footprint_topic`` for ``approach`` action type. + Polygon vertices, listed in ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]"`` format (e.g. ``"[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]"`` for the square in the front). Used for ``polygon`` type. Minimum 3 points for a triangle polygon. If not specified, the collision monitor will use dynamic polygon subscription to ``polygon_sub_topic`` for points in the ``stop``/``slowdown``/``limit`` action types, or footprint subscriber to ``footprint_topic`` for ``approach`` action type. :````.polygon_sub_topic: @@ -424,7 +424,7 @@ All previous Polygon parameters apply, in addition to the following unique param ============== ============================= Description: - Polygon vertexes, listed in ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]"`` format (e.g. ``"[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]"`` for the square in the front). Used for ``polygon`` type. Minimum 3 points for a triangle polygon. Causes an error, if not specified. + Polygon vertices, listed in ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]"`` format (e.g. ``"[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]"`` for the square in the front). Used for ``polygon`` type. Minimum 3 points for a triangle polygon. Causes an error, if not specified. :``.``.linear_min: diff --git a/configuration/packages/configuring-amcl.rst b/configuration/packages/configuring-amcl.rst index 1952edc70..c4a1fa782 100644 --- a/configuration/packages/configuring-amcl.rst +++ b/configuration/packages/configuring-amcl.rst @@ -98,7 +98,7 @@ Parameters ============== ============================= Description - Percentage of beams after not matching map to force full update due to bad convergance. + Percentage of beams after not matching map to force full update due to bad convergence. :beam_skip_threshold: diff --git a/configuration/packages/configuring-controller-server.rst b/configuration/packages/configuring-controller-server.rst index 7223ae4dc..ede299531 100644 --- a/configuration/packages/configuring-controller-server.rst +++ b/configuration/packages/configuring-controller-server.rst @@ -34,7 +34,7 @@ Parameters ============== ======= Description - Adds soft real-time priorization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` + Adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` :action_server_result_timeout: diff --git a/configuration/packages/configuring-coverage-server.rst b/configuration/packages/configuring-coverage-server.rst index 36ac12e35..9879f757e 100644 --- a/configuration/packages/configuring-coverage-server.rst +++ b/configuration/packages/configuring-coverage-server.rst @@ -180,7 +180,7 @@ Parameters ============== ======== Description - The default custom swath order for the route planner in the ``CUSTOM`` mode. The length of this custom order must be ``>= swaths.size()``. Only relevent when using the ``CUSTOM`` Route Type. + The default custom swath order for the route planner in the ``CUSTOM`` mode. The length of this custom order must be ``>= swaths.size()``. Only relevant when using the ``CUSTOM`` Route Type. :default_spiral_n: @@ -191,7 +191,7 @@ Parameters ============== =============== Description - Default number of swaths to skip and double back on to create a spiral pattern in the route. Only relevent when usign the ``SPIRAL`` Route Type. ``SNAKE`` is a special case when Spiral N = 2. + Default number of swaths to skip and double back on to create a spiral pattern in the route. Only relevant when using the ``SPIRAL`` Route Type. ``SNAKE`` is a special case when Spiral N = 2. :default_path_continuity_type: diff --git a/configuration/packages/configuring-docking-server.rst b/configuration/packages/configuring-docking-server.rst index fd7d19724..107dc33cd 100644 --- a/configuration/packages/configuring-docking-server.rst +++ b/configuration/packages/configuring-docking-server.rst @@ -37,7 +37,7 @@ Parameters ============== ============== Description - Timeout (s) to wait to obtain intial perception of the dock. + Timeout (s) to wait to obtain initial perception of the dock. :wait_charge_timeout: diff --git a/configuration/packages/configuring-lifecycle.rst b/configuration/packages/configuring-lifecycle.rst index 453377708..42049e977 100644 --- a/configuration/packages/configuring-lifecycle.rst +++ b/configuration/packages/configuring-lifecycle.rst @@ -8,7 +8,7 @@ Source code on Github_. .. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_lifecycle_manager The Lifecycle Manager module implements the method for handling the lifecycle transition states for the stack in a deterministic way. -It will take in a set of ordered nodes to transition one-by-one into the configurating and activate states to run the stack. +It will take in a set of ordered nodes to transition one-by-one into the configuration and activate states to run the stack. It will then bring down the stack into the finalized state in the opposite order. It will also create bond connections with the servers to ensure they are still up and transition down all nodes if any are non-responsive or crashed. diff --git a/configuration/packages/configuring-map-server.rst b/configuration/packages/configuring-map-server.rst index b1ff531f5..3ee507da2 100644 --- a/configuration/packages/configuring-map-server.rst +++ b/configuration/packages/configuring-map-server.rst @@ -44,7 +44,7 @@ Map Saver Parameters ============== ============================= Description - Occupied space minimum probability threshhold value for occupancy grid. + Occupied space minimum probability threshold value for occupancy grid. Map Server Parameters ********************* diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index bec54202b..48fad3980 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -248,7 +248,7 @@ MPPI Parameters ============== =========================== Description - Whether to publish debuggin trajectories for visualization. This can slow down the controller substantially (e.g. 1000 batches of 56 size every 30hz is alot of data). + Whether to publish debugging trajectories for visualization. This can slow down the controller substantially (e.g. 1000 batches of 56 size every 30hz is a lot of data). :retry_attempt_limit: @@ -1131,7 +1131,7 @@ General Words of Wisdom The ``model_dt`` parameter generally should be set to the duration of your control frequency. So if your control frequency is 20hz, this should be ``0.05``. However, you may also set it lower **but not larger**. -Visualization of the trajectories using ``visualize`` uses compute resources to back out trajectories for visualization and therefore slows compute time. It is not suggested that this parameter is set to ``true`` during a deployed use, but is a useful debug instrument while tuning the system, but use sparingly. Visualizing 2000 batches @ 56 points at 30 hz is *alot*. +Visualization of the trajectories using ``visualize`` uses compute resources to back out trajectories for visualization and therefore slows compute time. It is not suggested that this parameter is set to ``true`` during a deployed use, but is a useful debug instrument while tuning the system, but use sparingly. Visualizing 2000 batches @ 56 points at 30 hz is *a lot*. The most common parameters you might want to start off changing are the velocity profiles (``vx_max``, ``vx_min``, ``wz_max``, and ``vy_max`` if holonomic) and the ``motion_model`` to correspond to your vehicle. Its wise to consider the ``prune_distance`` of the path plan in proportion to your maximum velocity and prediction horizon. The only deeper parameter that will likely need to be adjusted for your particular settings is the Obstacle critics' ``repulsion_weight`` since the tuning of this is proprtional to your inflation layer's radius. Higher radii should correspond to reduced ``repulsion_weight`` due to the penalty formation (e.g. ``inflation_radius - min_dist_to_obstacle``). If this penalty is too high, the robot will slow significantly when entering cost-space from non-cost space or jitter in narrow corridors. It is noteworthy, but likely not necessary to be changed, that the Obstacle critic may use the full footprint information if ``consider_footprint = true``, though comes at an increased compute cost. diff --git a/configuration/packages/configuring-velocity-smoother.rst b/configuration/packages/configuring-velocity-smoother.rst index b069cd955..536613bc2 100644 --- a/configuration/packages/configuring-velocity-smoother.rst +++ b/configuration/packages/configuring-velocity-smoother.rst @@ -25,7 +25,7 @@ Velocity Smoother Parameters ============== ======= Description - Adds soft real-time priorization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` + Adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` :smoothing_frequency: diff --git a/configuration/packages/nav2_waypoint_follower-plugins/photo_at_waypoint.rst b/configuration/packages/nav2_waypoint_follower-plugins/photo_at_waypoint.rst index 9dc153b1c..5d5bf1c3e 100644 --- a/configuration/packages/nav2_waypoint_follower-plugins/photo_at_waypoint.rst +++ b/configuration/packages/nav2_waypoint_follower-plugins/photo_at_waypoint.rst @@ -33,7 +33,7 @@ Parameters ============== ============================= Description - Camera image topic name to susbcribe + Camera image topic name to subscribe :````.save_images_dir: diff --git a/configuration/packages/smac/configuring-smac-hybrid.rst b/configuration/packages/smac/configuring-smac-hybrid.rst index 6619c6803..453cf2beb 100644 --- a/configuration/packages/smac/configuring-smac-hybrid.rst +++ b/configuration/packages/smac/configuring-smac-hybrid.rst @@ -266,7 +266,7 @@ Parameters ====== ======= Description - Advanced feature: Cache the obstacle map dynamic programming distance expansion heuristic between subsiquent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + Advanced feature: Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. :````.allow_primitive_interpolation: @@ -288,7 +288,7 @@ Parameters ====== ======= Description - Advanced feature: This allows a user to disable downsampling of the obstacle heuristic's costmap representation to search at the costmap's full-resolution. This will come at increased up-front costs while searching for the 2D approximate route to the goal in exchange for less search iterations and a slightly more smooth path. With ``smooth_path`` on, this increased smoothness is noticable but not massively different. When combined with all of the advanced features however, it can contribute to a better overall plan in exchange for some compute time. This scales with map size and complexity of the path plan requested. For simpler maps / paths, this may actually improve performance due to low up-front search times and lower iterations. + Advanced feature: This allows a user to disable downsampling of the obstacle heuristic's costmap representation to search at the costmap's full-resolution. This will come at increased up-front costs while searching for the 2D approximate route to the goal in exchange for less search iterations and a slightly more smooth path. With ``smooth_path`` on, this increased smoothness is noticeable but not massively different. When combined with all of the advanced features however, it can contribute to a better overall plan in exchange for some compute time. This scales with map size and complexity of the path plan requested. For simpler maps / paths, this may actually improve performance due to low up-front search times and lower iterations. :````.use_quadratic_cost_penalty: @@ -409,7 +409,7 @@ Example cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. retrospective_penalty: 0.015 lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. - cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsiquent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. debug_visualizations: false # For Hybrid nodes: Whether to publish expansions on the /expansions topic as an array of poses (the orientation has no meaning) and the path's footprints on the /planned_footprints topic. WARNING: heavy to compute and to display, for debug only as it degrades the performance. use_quadratic_cost_penalty: False downsample_obstacle_heuristic: True diff --git a/configuration/packages/smac/configuring-smac-lattice.rst b/configuration/packages/smac/configuring-smac-lattice.rst index 33d88535c..200bf510d 100644 --- a/configuration/packages/smac/configuring-smac-lattice.rst +++ b/configuration/packages/smac/configuring-smac-lattice.rst @@ -226,7 +226,7 @@ Parameters ====== ======= Description - Cache the obstacle map dynamic programming distance expansion heuristic between subsiquent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. :````.allow_reverse_expansion: @@ -356,7 +356,7 @@ Example retrospective_penalty: 0.015 lattice_filepath: "" # The filepath to the state lattice graph lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. - cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsiquent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. allow_reverse_expansion: false # If true, allows the robot to use the primitives to expand in the mirrored opposite direction of the current robot's orientation (to reverse). smooth_path: True # If true, does a simple and quick smoothing post-processing to the path smoother: diff --git a/development_guides/involvement_docs/index.rst b/development_guides/involvement_docs/index.rst index 3743718da..c7103f295 100644 --- a/development_guides/involvement_docs/index.rst +++ b/development_guides/involvement_docs/index.rst @@ -92,7 +92,7 @@ developer. In the commit message of the contribution, (described more fully later in this document), the developer simply adds a ``Signed-off-by`` statement and thereby agrees to the DCO. -In practice, its easier to just ``git commit -s -m "commit messsage."``. +In practice, its easier to just ``git commit -s -m "commit message."``. Where ``-s`` adds this automatically. If you forgot to add this to a commit, it is easy to append via: ``git commit --amend -s``. diff --git a/getting_started/index.rst b/getting_started/index.rst index 58ab4fe2e..98e85e74c 100644 --- a/getting_started/index.rst +++ b/getting_started/index.rst @@ -57,7 +57,7 @@ Running the Example For ``ROS 2 Dashing Diademata`` or earlier, use ``nav2_simulation_launch.py``. However, it is recommended to use the most recent `ROS 2 LTS distribution - `_ for improved stablity and feature + `_ for improved stability and feature completeness. ``headless`` defaults to true; if not set to false, gzclient (the 3d view) is not started. diff --git a/migration/Dashing.rst b/migration/Dashing.rst index 13fc0fd95..0477282d7 100644 --- a/migration/Dashing.rst +++ b/migration/Dashing.rst @@ -41,7 +41,7 @@ Behavior tree cpp v3 supports plugins and will be converted in the next release. Navigation2 Architectural Changes ********************************* -The ``nav2_world_model`` package was removed. The individual ``nav2_planner`` and ``nav2_controller`` servers now host their relevent costmaps. +The ``nav2_world_model`` package was removed. The individual ``nav2_planner`` and ``nav2_controller`` servers now host their relevant costmaps. This was done to reduce network traffic and ensure up-to-date information for the safety-critical elements of the system. As above mentions, plugins were introduced into the stack and these servers each host plugins for navigation, control, and costmap layers. diff --git a/migration/Foxy.rst b/migration/Foxy.rst index 323fb796e..1fb9302b0 100644 --- a/migration/Foxy.rst +++ b/migration/Foxy.rst @@ -140,7 +140,7 @@ Original GitHub tickets: Costmap Filters *************** -A new concept interacting with spatial-dependent objects called "Costmap Filters" appeared in Galactic (more information about this concept could be found at :ref:`concepts` page). Costmap filters are acting as a costmap plugins, applied to a separate costmap above common plugins. In order to make a filtered costmap and change robot's behavior in annotated areas, filter plugin reads the data came from filter mask. Then this data is being linearly transformed into feature map in a filter space. It could be passability of an area, maximum speed limit in m/s, robot desired direction in degrees or anything else. Transformed feature map along with the map/costmap, sensors data and current robot position is used in plugin's algorithms to make required updates in the resulting costmap and robot's behavor. +A new concept interacting with spatial-dependent objects called "Costmap Filters" appeared in Galactic (more information about this concept could be found at :ref:`concepts` page). Costmap filters are acting as a costmap plugins, applied to a separate costmap above common plugins. In order to make a filtered costmap and change robot's behavior in annotated areas, filter plugin reads the data came from filter mask. Then this data is being linearly transformed into feature map in a filter space. It could be passability of an area, maximum speed limit in m/s, robot desired direction in degrees or anything else. Transformed feature map along with the map/costmap, sensors data and current robot position is used in plugin's algorithms to make required updates in the resulting costmap and robot's behavior. Architecturally, costmap filters consists from ``CostmapFilter`` class which is a basic class incorporating much common of its inherited filter plugins: @@ -151,7 +151,7 @@ Architecturally, costmap filters consists from ``CostmapFilter`` class which is Each costmap filter subscribes to filter info topic (publishing by `Costmap Filter Info Publisher Server `_) having all necessary information for loaded costmap filter and filter mask topic. ``SpeedFilter`` additionally publishes maximum speed restricting `messages `_ targeted for a Controller to enforce robot won't exceed given limit. -High-level design of this concept could be found `here `_. The functionality of costmap filters is being disscussed in `the ticket #1263 `_ and carried out by `PR #1882 `_. The following tutorials: :ref:`navigation2_with_keepout_filter` and :ref:`navigation2_with_speed_filter` will help to easily get involved with ``KeepoutFilter`` and ``SpeedFilter`` functionalities. +High-level design of this concept could be found `here `_. The functionality of costmap filters is being discussed in `the ticket #1263 `_ and carried out by `PR #1882 `_. The following tutorials: :ref:`navigation2_with_keepout_filter` and :ref:`navigation2_with_speed_filter` will help to easily get involved with ``KeepoutFilter`` and ``SpeedFilter`` functionalities. SmacPlanner *********** @@ -160,7 +160,7 @@ A new package, ``nav2_smac_planner`` was added containing 4 or 8 connected 2D A* The ``nav2_smac_planner`` package contains an optimized templated A* search algorithm used to create multiple A*-based planners for multiple types of robot platforms. We support differential-drive and omni-directional drive robots using the ``SmacPlanner2D`` planner which implements a cost-aware A* planner. We support cars, car-like, and ackermann vehicles using the ``SmacPlanner`` plugin which implements a Hybrid-A* planner. This plugin is also useful for curvature constrained planning, like when planning robot at high speeds to make sure they don't flip over or otherwise skid out of control. -The ``SmacPlanner`` fully-implements the Hybrid-A* planner as proposed in `Practical Search Techniques in Path Planning for Autonomous Driving `_, including hybrid searching, CG smoothing, analytic expansions and hueristic functions. +The ``SmacPlanner`` fully-implements the Hybrid-A* planner as proposed in `Practical Search Techniques in Path Planning for Autonomous Driving `_, including hybrid searching, CG smoothing, analytic expansions and heuristic functions. ThetaStarPlanner **************** @@ -171,7 +171,7 @@ This package implements an optimized version of the Theta* Path Planner (specifi RegulatedPurePursuitController ****************************** -A new package, ``nav2_regulated_pure_pursuit_controller`` was added containing a novel varient of the Pure Pursuit algorithm. +A new package, ``nav2_regulated_pure_pursuit_controller`` was added containing a novel variant of the Pure Pursuit algorithm. It also includes configurations to enable Pure Pursuit and Adaptive Pure Pursuit variations as well. This variation is specifically targeting service / industrial robot needs. diff --git a/migration/Galactic.rst b/migration/Galactic.rst index fc7bd483f..a25b623ed 100644 --- a/migration/Galactic.rst +++ b/migration/Galactic.rst @@ -30,7 +30,7 @@ The Smac Planner was significantly improved, of both the 2D and Hybrid-A* implem - Precompute primitives at all orientation bins - SmacPlanner2D parameters are now all reconfigurable - Both Hybrid-A* and State Lattice planners are now fully admissible - - Hybrid-A* and State Lattice have had their parameterization for path smoothing readded. + - Hybrid-A* and State Lattice have had their parameterization for path smoothing re-added. - The smoother now enables kinematically feasible boundary conditions. - State Lattice supports turning in place primitive types - Retrospective penalty added to speed up the planner, making it prioritize later search branches before earlier ones, which have negligible chance to improve path in vast majority of situations @@ -154,12 +154,12 @@ The Rotation Shim Controller is suitable for: Spawning the robot in Gazebo **************************** -`This PR 2473 `_ deletes the pkg ``nav2_gazebo_spawner`` inside nav2_bringup directory. Instead of ``nav2_gazebo_spawner`` the Node `spawn_entity.py `_ of ``gazebo_ros`` is recomended to spawn the robot in gazebo. +`This PR 2473 `_ deletes the pkg ``nav2_gazebo_spawner`` inside nav2_bringup directory. Instead of ``nav2_gazebo_spawner`` the Node `spawn_entity.py `_ of ``gazebo_ros`` is recommended to spawn the robot in gazebo. Note that * gazebo should be started with both ``libgazebo_ros_init.so`` and ``libgazebo_ros_factory.so`` to work correctly. - * spawn_entity node could not remap /tf and /tf_static to tf and tf_static in the launch file yet, used only for multi-robot situations. This problem was overcame by adding remapping argument ``/tf:=tf`` ``/tf_static:=tf_static`` under ros2 tag in each plugin which publishs transforms in the SDF file. It is essential to differentiate the tf's of the different robot. + * spawn_entity node could not remap /tf and /tf_static to tf and tf_static in the launch file yet, used only for multi-robot situations. This problem was overcame by adding remapping argument ``/tf:=tf`` ``/tf_static:=tf_static`` under ros2 tag in each plugin which publishes transforms in the SDF file. It is essential to differentiate the tf's of the different robot. Recovery Behavior Timeout ************************* @@ -212,7 +212,7 @@ When BT action nodes throw exceptions due to networking or action server failure BT Navigator Groot Multiple Navigators ************************************** -`This PR 2627 `_ creates separate parameters for groot monitoring for the NavToPose and NavThroughPoses navigator types so you can individually track the state of each behavior tree through the ZMQ publisher. This resolves a long-standing problem after we added multiple navigator types to BT Navigator that you could only view the nav to poses BT execution live. BT.CPP and Groot only support one static ZMQ stream at a time, so there is a bit of a quirk where you must locally reset Groot after switching trees in order to view the live stream of the Nav Through Poses BT, if in use. This is a state of the BT.CPP and Groot libraries and not something we can resolve withing Nav2. +`This PR 2627 `_ creates separate parameters for groot monitoring for the NavToPose and NavThroughPoses navigator types so you can individually track the state of each behavior tree through the ZMQ publisher. This resolves a long-standing problem after we added multiple navigator types to BT Navigator that you could only view the nav to poses BT execution live. BT.CPP and Groot only support one static ZMQ stream at a time, so there is a bit of a quirk where you must locally reset Groot after switching trees in order to view the live stream of the Nav Through Poses BT, if in use. This is a state of the BT.CPP and Groot libraries and not something we can resolve within Nav2. There is some thought into the future regarding complete deprecation of live BT monitoring using Groot due to this quirk and the almost-certain infux of tickets on the topic. Groot will however always be supported for visualizing behavior tree XML files and modifications, simply not visualizing the BT execution live during robot navigation. @@ -253,7 +253,7 @@ Replanning Only if Path is Invalid Fix CostmapLayer clearArea invert param logic ********************************************* -`This PR 2772 `_ fixes the invert paramlogic of the CostmapLayer clearArea fonction. Hence correcting the behavior of the clearAroundRobot and clearExceptRegion services and their corresponding BT actions. +`This PR 2772 `_ fixes the invert paramlogic of the CostmapLayer clearArea function. Hence correcting the behavior of the clearAroundRobot and clearExceptRegion services and their corresponding BT actions. Dynamic Composition ******************* diff --git a/migration/Humble.rst b/migration/Humble.rst index 7eb0672c8..550bf9966 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -121,11 +121,11 @@ Publish Costmap Layers Give Behavior Server Access to Both Costmaps ******************************************** -`PR #3255 `_ addes the ability for a behavior to access the local and global costmap. +`PR #3255 `_ adds the ability for a behavior to access the local and global costmap. To update behaviors, any reference to the global_frame must be updated to the local_frame parameter along with the ``configuration`` method which now takes in the local and global collision checkers. -Lastly, ``getResourceInfo`` must be overriden to return ``CostmapInfoType::LOCAL``. Other options include ``GLOBAL`` if the behavior useses global costmap and/or footprint) +Lastly, ``getResourceInfo`` must be overridden to return ``CostmapInfoType::LOCAL``. Other options include ``GLOBAL`` if the behavior useses global costmap and/or footprint) or ``BOTH`` if both are required. This allows us to only create and maintain the minimum amount of expensive resources. New Model Predictive Path Integral Controller @@ -224,4 +224,4 @@ More information about ``Denoise Layer`` plugin and how it works could be found SmacPlannerHybrid viz_expansions parameter ****************************************** -`PR #3577 `_ adds a new paremeter for visualising SmacPlannerHybrid expansions for debug purpose. +`PR #3577 `_ adds a new parameter for visualising SmacPlannerHybrid expansions for debug purpose. diff --git a/migration/Iron.rst b/migration/Iron.rst index 6011de40f..efec22d43 100644 --- a/migration/Iron.rst +++ b/migration/Iron.rst @@ -25,13 +25,13 @@ A new parameter ``enable_stamped_cmd_vel`` has been added to all of the publishe Add VelocityPolygon in Collision Monitor **************************************** -`PR #3708 `_ adds ``VelocityPolgon`` type in Collision Monitor. This allows the user to setup multiple polygons to cover the range of the robot's velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot's velocity against each sub polygon to determine the approriate polygon to be used for collision checking. The tutorial is available in the :ref:`Configuring Collision Monitor with VelocityPolygon ` section. +`PR #3708 `_ adds ``VelocityPolgon`` type in Collision Monitor. This allows the user to setup multiple polygons to cover the range of the robot's velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot's velocity against each sub polygon to determine the appropriate polygon to be used for collision checking. The tutorial is available in the :ref:`Configuring Collision Monitor with VelocityPolygon ` section. Change polygon points parameter format in Collision Monitor *********************************************************** -`PR #4020 `_ changes the format of the Polygon points parameter from ``vector`` to ``string``. This makes the polygon description more uniform accross the Collision Monitor and Costmap_2D. +`PR #4020 `_ changes the format of the Polygon points parameter from ``vector`` to ``string``. This makes the polygon description more uniform across the Collision Monitor and Costmap_2D. Now we can define a polygon's points in string that has a ``vector>`` structure like this ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y],...]"`` with a minimum of 4 points described. An example of a Square polygon will be written as follows. @@ -49,7 +49,7 @@ Now we can define a polygon's points in string that has a ``vector`_ adds soft real-time priorization to the controller server to better ensure resources to time sensitive portions of the codebase. The Simple Action Server now has a ``realtime`` input field exposed in the Controller Server via the parameter ``use_realtime_priority`` which will set the controller's execution thread to a higher priority than the rest of the system to meet scheduling deadlines. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions. This is currently only enabled in the Controller Server, who's execution thread is sensitive to scheduling priorities, but could be set with other threads in the future if found necessary. +`PR #3914 `_ adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. The Simple Action Server now has a ``realtime`` input field exposed in the Controller Server via the parameter ``use_realtime_priority`` which will set the controller's execution thread to a higher priority than the rest of the system to meet scheduling deadlines. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions. This is currently only enabled in the Controller Server, who's execution thread is sensitive to scheduling priorities, but could be set with other threads in the future if found necessary. .. code-block:: text @@ -77,7 +77,7 @@ See :ref:`docking_tutorial` for a tutorial on using this new capability! Thanks Introduce a new Multi-Robot Bringup Launch ****************************************** -`PR #3572 `_ introduces a new way of bringup tb3 multi-robot that names as ``cloned_tb3_simulation_launch.py`` for simulation. ``cloned_tb3_simulation_launch.py`` enables to bring up multiple robots with same parameter that described in ``nav2_multirobot_param_all.yaml``. And multiple robots are separeted by namespaces which are given as a Launch Arguments. +`PR #3572 `_ introduces a new way of bringup tb3 multi-robot that names as ``cloned_tb3_simulation_launch.py`` for simulation. ``cloned_tb3_simulation_launch.py`` enables to bring up multiple robots with same parameter that described in ``nav2_multirobot_param_all.yaml``. And multiple robots are separated by namespaces which are given as a Launch Arguments. Existing ``multi_tb3_simulation_launch.py`` which was utilized in previous is replaced with ``unique_tb3_simulation_launch.py``, allowing for multiple unique robot instances utilizing ``nav2_multirobot_params_.yaml`` configuration files. @@ -253,7 +253,7 @@ The stack no longer contains wall timers or wall rates. It will now use the node New Graceful Motion Controller ****************************** -`PR #4021 `_ introduces a new type of controller for differential robots based on a pose-following kinematic control law that generates a smooth and confortable trajectory. +`PR #4021 `_ introduces a new type of controller for differential robots based on a pose-following kinematic control law that generates a smooth and comfortable trajectory. See :ref:`configuring_graceful_motion_controller` for more information. diff --git a/plugin_tutorials/docs/writing_new_behavior_plugin.rst b/plugin_tutorials/docs/writing_new_behavior_plugin.rst index d08efdfc9..e4a9c374b 100644 --- a/plugin_tutorials/docs/writing_new_behavior_plugin.rst +++ b/plugin_tutorials/docs/writing_new_behavior_plugin.rst @@ -54,11 +54,11 @@ Let's learn more about the methods needed to write a Behavior Plugin **if you di | | and shared pointer to a collision checker. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | activate() | Method is called when behavior server enters on_activate state. Ideally | Yes | -| | this method should implement operations which are neccessary before the | | +| | this method should implement operations which are necessary before the | | | | behavior goes to an active state. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | deactivate() | Method is called when behavior server enters on_deactivate state. Ideally | Yes | -| | this method should implement operations which are neccessary before | | +| | this method should implement operations which are necessary before | | | | behavior goes to an inactive state. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | cleanup() | Method is called when behavior server goes to on_cleanup state. Ideally | Yes | @@ -80,7 +80,7 @@ This tutorial uses this wrapper so these are the main elements we will address. | | velocity for the current cycle, publishing it and checking for completion. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | onConfigure() | Method is called when behavior server enters on_configure state. Ideally | No | -| | this method should implement operations which are neccessary before | | +| | this method should implement operations which are necessary before | | | | behavior goes to a configured state (get parameters, etc). | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | onCleanup() | Method is called when behavior server goes to on_cleanup state. Ideally | No | @@ -123,7 +123,7 @@ We receive an action goal, ``command``, which we want to process. This is the "call for help" message that we want to send via SMS to our brothers in arms in the operations center. We use the service Twilio to complete this task. -Please `create an account `_ and get all the relavent information needed for creating the service (e.g. ``account_sid``, ``auth_token``, and a phone number). +Please `create an account `_ and get all the relevant information needed for creating the service (e.g. ``account_sid``, ``auth_token``, and a phone number). You can set these values as parameters in your configuration files corresponding to the ``onConfigure()`` parameter declarations. We use the ``_twilio`` object to send our message with your account information from the configuration file. diff --git a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst b/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst index 56eaad958..8750f9280 100644 --- a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst +++ b/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst @@ -54,11 +54,11 @@ The list of methods, their descriptions, and necessity are presented in the tabl | | parent node, controller name, tf buffer pointer and shared pointer to costmap. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | activate() | Method is called when controller server enters on_activate state. Ideally this method | Yes | -| | should implement operations which are neccessary before controller goes to an active | | +| | should implement operations which are necessary before controller goes to an active | | | | state. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | deactivate() | Method is called when controller server enters on_deactivate state. Ideally this | Yes | -| | method should implement operations which are neccessary before controller goes to an | | +| | method should implement operations which are necessary before controller goes to an | | | | inactive state. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | cleanup() | Method is called when controller server goes to on_cleanup state. Ideally this method | Yes | diff --git a/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst b/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst index 48c8722da..ae4d1ada7 100644 --- a/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst +++ b/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst @@ -48,19 +48,19 @@ Let's learn more about the methods needed to write a planner plugin. | | shared pointer to costmap. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | activate() | Method is called when planner server enters on_activate state. Ideally this | Yes | -| | method should implement operations which are neccessary before planner goes | | +| | method should implement operations which are necessary before planner goes | | | | to an active state. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | deactivate() | Method is called when planner server enters on_deactivate state. Ideally | Yes | -| | this method should implement operations which are neccessary before planner | | +| | this method should implement operations which are necessary before planner | | | | goes to an inactive state. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | cleanup() | Method is called when planner server goes to on_cleanup state. Ideally this | Yes | -| | method should clean up resoures which are created for the planner. | | +| | method should clean up resources which are created for the planner. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ | createPlan() | Method is called when planner server demands a global plan for specified | Yes | | | start and goal pose. This method returns `nav_msgs\:\:msg\:\:Path` carrying | | -| | global plan. This method takes 2 input parmas: start pose and goal pose. | | +| | global plan. This method takes 2 input params: start pose and goal pose. | | +----------------------+-----------------------------------------------------------------------------+-------------------------+ For this tutorial, we will be using methods ``StraightLine::configure()`` and ``StraightLine::createPlan()`` to create straight-line planner. diff --git a/plugin_tutorials/docs/writing_new_navigator_plugin.rst b/plugin_tutorials/docs/writing_new_navigator_plugin.rst index 333dc7035..3eaeda37a 100644 --- a/plugin_tutorials/docs/writing_new_navigator_plugin.rst +++ b/plugin_tutorials/docs/writing_new_navigator_plugin.rst @@ -34,7 +34,7 @@ We will be implementing pure point-to-point navigation behavior. The code in thi Our example plugin class ``nav2_bt_navigator::NavigateToPoseNavigator`` inherits from the base class ``nav2_core::BehaviorTreeNavigator``. The base class provides a set of virtual methods to implement a navigator plugin. These methods are called at runtime by the BT Navigator server or as a response to ROS 2 actions to process a navigation request. -Note that this class has itself a base class of ``NavigatorBase``. This class is to provide a non-templated base-class for use in loading the plugins into vectors for storage and calls for basic state transition in the lifecycle node. Its members (e.g. ``on_XYZ``) are implemented for you in ``BehaviorTreeNavigator`` and marked as ``final`` so they are not possible to be overrided by the user. The API that you will be implementing for your navigator are the virtual methods within ``BehaviorTreeNavigator``, not ``NavigatorBase``. These ``on_XYZ`` APIs are implemented in necessary functions in ``BehaviorTreeNavigator`` to handle boilerplate logic regarding the behavior tree and action server to minimize code duplication across the navigator implementations (e.g. ``on_configure`` will create the action server, register callbacks, populate the blackboard with some necessary basic information, and then call a user-defined ``configure`` function for any additional user-specific needs). +Note that this class has itself a base class of ``NavigatorBase``. This class is to provide a non-templated base-class for use in loading the plugins into vectors for storage and calls for basic state transition in the lifecycle node. Its members (e.g. ``on_XYZ``) are implemented for you in ``BehaviorTreeNavigator`` and marked as ``final`` so they are not possible to be overridden by the user. The API that you will be implementing for your navigator are the virtual methods within ``BehaviorTreeNavigator``, not ``NavigatorBase``. These ``on_XYZ`` APIs are implemented in necessary functions in ``BehaviorTreeNavigator`` to handle boilerplate logic regarding the behavior tree and action server to minimize code duplication across the navigator implementations (e.g. ``on_configure`` will create the action server, register callbacks, populate the blackboard with some necessary basic information, and then call a user-defined ``configure`` function for any additional user-specific needs). The list of methods, their descriptions, and necessity are presented in the table below: @@ -42,18 +42,18 @@ The list of methods, their descriptions, and necessity are presented in the tabl | **Virtual method** | **Method description** | **Requires override?** | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | getDefaultBTFilepath() | Method is called on initialization to retrieve the default BT filepath to use for | Yes | -| | navigation. This may be done via parameters, hardcoded logic, sentinal files, etc. | | +| | navigation. This may be done via parameters, hardcoded logic, sentinel files, etc. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | configure() | Method is called when BT navigator server enters on_configure state. This method | No | -| | should implement operations which are neccessary before navigator goes to an active | | +| | should implement operations which are necessary before navigator goes to an active | | | | state, such as getting parameters, setting up the blackboard, etc. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | activate() | Method is called when BT navigator server enters on_activate state. This method | No | -| | should implement operations which are neccessary before navigator goes to an active | | +| | should implement operations which are necessary before navigator goes to an active | | | | state, such as create clients and subscriptions. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | deactivate() | Method is called when BT navigator server enters on_deactivate state. This | No | -| | method should implement operations which are neccessary before navigator goes to an | | +| | method should implement operations which are necessary before navigator goes to an | | | | inactive state. | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | cleanup() | Method is called when BT navigator server goes to on_cleanup state. This method | No | @@ -70,7 +70,7 @@ The list of methods, their descriptions, and necessity are presented in the tabl | onPreempt() | Method is called when a new goal is requesting preemption over the existing | Yes | | | goal currently being processed. If the new goal is viable, it should make all | | | | appropriate updates to the BT and blackboard such that this new request may | | -| | immediately start being processed without hard cancelation of the initial task | | +| | immediately start being processed without hard cancellation of the initial task | | | | (e.g. preemption). | | +---------------------------+---------------------------------------------------------------------------------------+------------------------+ | goalCompleted() | Method is called when a goal is completed to populate the action result object or | Yes | @@ -208,7 +208,7 @@ If however a goal is preempted (e.g. a new action request comes in while an exis } } -Note that here you can also see the ``initializeGoalPose`` method called. This method will set the goal parameters for this navigator onto the blackboard and reset important state information to cleanly re-use a behavior tree without old state information, as shown below: +Note that here you can also see the ``initializeGoalPose`` method called. This method will set the goal parameters for this navigator onto the blackboard and reset important state information to cleanly reuse a behavior tree without old state information, as shown below: .. code-block:: c++ diff --git a/plugins/index.rst b/plugins/index.rst index 7267ef8fa..4c44dd462 100644 --- a/plugins/index.rst +++ b/plugins/index.rst @@ -8,7 +8,7 @@ Namely, the costmap layer, planner, controller, behavior tree, and behavior plug A list of all known plugins are listed here below for ROS 2 Navigation. If you know of a plugin, or you have created a new plugin, please consider submitting a pull request with that information. -This file can be found and editted under ``sphinx_docs/plugins/index.rst``. +This file can be found and edited under ``sphinx_docs/plugins/index.rst``. For tutorials on creating your own plugins, please see :ref:`writing_new_costmap2d_plugin`, :ref:`writing_new_nbt_plugin`, :ref:`writing_new_nav2controller_plugin`, :ref:`writing_new_nav2planner_plugin`, :ref:`writing_new_behavior_plugin`, or :ref:`writing_new_nav2navigator_plugin`. Behavior-Tree Navigators @@ -38,12 +38,12 @@ Costmap Layers +--------------------------------+------------------------+----------------------------------+ | Plugin Name | Creator | Description | +================================+========================+==================================+ -| `Voxel Layer`_ | Eitan Marder-Eppstein | Maintains persistant | +| `Voxel Layer`_ | Eitan Marder-Eppstein | Maintains persistent | | | | 3D voxel layer using depth and | | | | laser sensor readings and | | | | raycasting to clear free space | +--------------------------------+------------------------+----------------------------------+ -| `Range Layer`_ | David Lu | Uses a probabalistic model to | +| `Range Layer`_ | David Lu | Uses a probabilistic model to | | | | put data from sensors that | | | | publish range msgs on the costmap| +--------------------------------+------------------------+----------------------------------+ @@ -174,7 +174,7 @@ Planners | | | Ackermann, diff, omni, and | | | | | legged robots. | | +---------------------------+---------------------------------------+------------------------------+---------------------+ -|`ThetaStarPlanner`_ | Anshumaan Singh | An implementaion of Theta* | Differential, | +|`ThetaStarPlanner`_ | Anshumaan Singh | An implementation of Theta* | Differential, | | | | using either 4 or 8 | Omnidirectional | | | | connected neighborhoods, | | | | | assumes the robot as a | | @@ -327,98 +327,98 @@ Progress Checkers Behavior Tree Nodes =================== -+--------------------------------------------+---------------------+------------------------------------------+ -| Action Plugin Name | Creator | Description | -+============================================+=====================+==========================================+ -| `Back Up Action`_ | Michael Jeronimo | Calls backup behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Drive On Heading Action`_ | Joshua Wallace | Calls drive on heading behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Assisted Teleop Action`_ | Joshua Wallace | Calls assisted teleop behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Clear Entire Costmap Service`_ | Carl Delsey | Calls clear entire costmap service | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Clear Costmap Except Region Service`_ | Guillaume Doisy | Calls clear costmap except region service| -+--------------------------------------------+---------------------+------------------------------------------+ -| `Clear Costmap Around Robot Service`_ | Guillaume Doisy | Calls clear costmap around robot service | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Compute Path to Pose Action`_ | Michael Jeronimo | Calls Nav2 planner server | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Smooth Path Action`_ | Matej Vargovcik | Calls Nav2 smoother server | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Follow Path Action`_ | Michael Jeronimo | Calls Nav2 controller server | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Navigate to Pose Action`_ | Michael Jeronimo | BT Node for other | -| | | BehaviorTree.CPP BTs to call | -| | | Navigation2 as a subtree action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Reinitalize Global Localization Service`_ | Carl Delsey | Reinitialize AMCL to a new pose | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Spin Action`_ | Carl Delsey | Calls spin behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Wait Action`_ | Steve Macenski | Calls wait behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Truncate Path`_ | Francisco Martín | Modifies a path making it shorter | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Truncate Path Local`_ | Matej Vargovcik | Extracts a path section around robot | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Planner Selector`_ | Pablo Iñigo Blasco | Selects the global planner based on a | -| | | topic input, otherwises uses a default | -| | | planner id | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Controller Selector`_ | Pablo Iñigo Blasco | Selects the controller based on a | -| | | topic input, otherwises uses a default | -| | | controller id | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Goal Checker Selector`_ | Pablo Iñigo Blasco | Selects the goal checker based on a | -| | | topic input, otherwises uses a default | -| | | goal checker id | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Smoother Selector`_ | Owen Hooper | Selects the smoother based on a | -| | | topic input, otherwises uses a default | -| | | smoother id | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Progress Checker Selector`_ | Steve Macenski | Selects the progress checker based on a | -| | | topic input, otherwises uses a default | -| | | progress checker id | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Navigate Through Poses`_ | Steve Macenski | BT Node for other BehaviorTree.CPP BTs | -| | | to call Nav2's NavThroughPoses action | -| | | | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Remove Passed Goals`_ | Steve Macenski | Removes goal poses passed or within a | -| | | tolerance for culling old viapoints from | -| | | path re-planning | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Remove In Collision Goals`_ | Tony Najjar | Removes goal poses that have a footprint | -| | | or point cost above a threshold. | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Compute Path Through Poses`_ | Steve Macenski | Computes a path through a set of poses | -| | | rather than a single end goal pose | -| | | using the planner plugin specified | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel Control Action`_ |Pradheep Padmanabhan | Cancels Nav2 controller server | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel BackUp Action`_ |Pradheep Padmanabhan | Cancels backup behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel Spin Action`_ |Pradheep Padmanabhan | Cancels spin behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel Wait Action`_ |Pradheep Padmanabhan | Cancels wait behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel Drive on Heading Action`_ | Joshua Wallace | Cancels drive on heading behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel Assisted Teleop Action`_ | Joshua Wallace | Cancels assisted teleop behavior action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Cancel Complete Coverage Action`_ | Steve Macenski | Cancels compute complete coverage | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Compute Complete Coverage Path Action`_ | Steve Macenski | Calls coverage planner server | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Get Pose From Path Action`_ | Marc Morcos | Extracts a pose from a path | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Dock Robot Action`_ | Steve Macenski | Calls dock robot action | -+--------------------------------------------+---------------------+------------------------------------------+ -| `Undock Robot Action`_ | Steve Macenski | Calls undock robot action | -+--------------------------------------------+---------------------+------------------------------------------+ ++---------------------------------------------+---------------------+------------------------------------------+ +| Action Plugin Name | Creator | Description | ++=============================================+=====================+==========================================+ +| `Back Up Action`_ | Michael Jeronimo | Calls backup behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Drive On Heading Action`_ | Joshua Wallace | Calls drive on heading behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Assisted Teleop Action`_ | Joshua Wallace | Calls assisted teleop behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Clear Entire Costmap Service`_ | Carl Delsey | Calls clear entire costmap service | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Clear Costmap Except Region Service`_ | Guillaume Doisy | Calls clear costmap except region service| ++---------------------------------------------+---------------------+------------------------------------------+ +| `Clear Costmap Around Robot Service`_ | Guillaume Doisy | Calls clear costmap around robot service | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Compute Path to Pose Action`_ | Michael Jeronimo | Calls Nav2 planner server | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Smooth Path Action`_ | Matej Vargovcik | Calls Nav2 smoother server | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Follow Path Action`_ | Michael Jeronimo | Calls Nav2 controller server | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Navigate to Pose Action`_ | Michael Jeronimo | BT Node for other | +| | | BehaviorTree.CPP BTs to call | +| | | Navigation2 as a subtree action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Reinitialize Global Localization Service`_ | Carl Delsey | Reinitialize AMCL to a new pose | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Spin Action`_ | Carl Delsey | Calls spin behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Wait Action`_ | Steve Macenski | Calls wait behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Truncate Path`_ | Francisco Martín | Modifies a path making it shorter | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Truncate Path Local`_ | Matej Vargovcik | Extracts a path section around robot | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Planner Selector`_ | Pablo Iñigo Blasco | Selects the global planner based on a | +| | | topic input, otherwises uses a default | +| | | planner id | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Controller Selector`_ | Pablo Iñigo Blasco | Selects the controller based on a | +| | | topic input, otherwises uses a default | +| | | controller id | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Goal Checker Selector`_ | Pablo Iñigo Blasco | Selects the goal checker based on a | +| | | topic input, otherwises uses a default | +| | | goal checker id | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Smoother Selector`_ | Owen Hooper | Selects the smoother based on a | +| | | topic input, otherwises uses a default | +| | | smoother id | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Progress Checker Selector`_ | Steve Macenski | Selects the progress checker based on a | +| | | topic input, otherwises uses a default | +| | | progress checker id | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Navigate Through Poses`_ | Steve Macenski | BT Node for other BehaviorTree.CPP BTs | +| | | to call Nav2's NavThroughPoses action | +| | | | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Remove Passed Goals`_ | Steve Macenski | Removes goal poses passed or within a | +| | | tolerance for culling old viapoints from | +| | | path re-planning | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Remove In Collision Goals`_ | Tony Najjar | Removes goal poses that have a footprint | +| | | or point cost above a threshold. | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Compute Path Through Poses`_ | Steve Macenski | Computes a path through a set of poses | +| | | rather than a single end goal pose | +| | | using the planner plugin specified | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel Control Action`_ |Pradheep Padmanabhan | Cancels Nav2 controller server | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel BackUp Action`_ |Pradheep Padmanabhan | Cancels backup behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel Spin Action`_ |Pradheep Padmanabhan | Cancels spin behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel Wait Action`_ |Pradheep Padmanabhan | Cancels wait behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel Drive on Heading Action`_ | Joshua Wallace | Cancels drive on heading behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel Assisted Teleop Action`_ | Joshua Wallace | Cancels assisted teleop behavior action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Cancel Complete Coverage Action`_ | Steve Macenski | Cancels compute complete coverage | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Compute Complete Coverage Path Action`_ | Steve Macenski | Calls coverage planner server | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Get Pose From Path Action`_ | Marc Morcos | Extracts a pose from a path | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Dock Robot Action`_ | Steve Macenski | Calls dock robot action | ++---------------------------------------------+---------------------+------------------------------------------+ +| `Undock Robot Action`_ | Steve Macenski | Calls undock robot action | ++---------------------------------------------+---------------------+------------------------------------------+ .. _Back Up Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/back_up_action.cpp .. _Drive On Heading Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/drive_on_heading_action.cpp diff --git a/setup_guides/odom/setup_odom.rst b/setup_guides/odom/setup_odom.rst index ddae151cd..2b4d7a007 100644 --- a/setup_guides/odom/setup_odom.rst +++ b/setup_guides/odom/setup_odom.rst @@ -546,7 +546,7 @@ You should see an output as shown below. From the output above, we can see that the ``ekf_filter_node`` is subscribed to ``/demo/imu`` and ``/demo/odom``. We can also see that the ``ekf_filter_node`` publishes on the ``odometry/filtered``, ``accel/filtered``, and ``/tf`` topics. -You may also verify that ``robot_localization`` is publishing the ``odom`` => ``base_link`` transform by using the tf2_echo utility. Run the folllowing command in a separate command line terminal: +You may also verify that ``robot_localization`` is publishing the ``odom`` => ``base_link`` transform by using the tf2_echo utility. Run the following command in a separate command line terminal: .. code-block:: shell diff --git a/setup_guides/sensors/setup_sensors.rst b/setup_guides/sensors/setup_sensors.rst index 134cbedfb..0418a4264 100644 --- a/setup_guides/sensors/setup_sensors.rst +++ b/setup_guides/sensors/setup_sensors.rst @@ -218,7 +218,7 @@ Similar to the lidar sensor, we create ``camera_link`` which will be referenced Launch and Build Files ====================== -To verify that the sensors are set up properly and that they can see objects in our environemnt, let us launch ``sam_bot`` in a Gazebo world with objects. +To verify that the sensors are set up properly and that they can see objects in our environment, let us launch ``sam_bot`` in a Gazebo world with objects. Let us create a Gazebo world with a single cube and a single sphere that are within the range of ``sam_bot``'s sensors so we can verify if it can see the objects correctly. To create the world, create a directory named ``world`` at the root of your project and create a file named ``my_world.sdf`` inside the ``world`` folder . Then copy the contents of `world/my_world.sdf `_ and paste them inside ``my_world.sdf``. @@ -227,7 +227,7 @@ Now, let us edit our launch file, `launch/display.launch.py ``sensors`` transform is now being published by ``robot_state_publisher`` and the ``odom`` => ``base_link`` transform by our Gazebo plugins. Both transforms should now be dislpayed show without errors in RViz. +RViz and the Gazebo should now be launched with ``sam_bot`` present in both. Recall that the ``base_link`` => ``sensors`` transform is now being published by ``robot_state_publisher`` and the ``odom`` => ``base_link`` transform by our Gazebo plugins. Both transforms should now be displayed show without errors in RViz. Launching slam_toolbox ---------------------- @@ -481,7 +481,7 @@ We can also check that the transforms are correct by executing the following lin ros2 run tf2_tools view_frames.py Note: For Galactic and newer, it should be ``view_frames`` and not ``view_frames.py`` -The line above will create a ``frames.pdf`` file that shows the current transform tree. Your tranform tree should be similar to the one shown below: +The line above will create a ``frames.pdf`` file that shows the current transform tree. Your transform tree should be similar to the one shown below: .. image:: images/view_frames.png :align: center diff --git a/setup_guides/transformation/setup_transforms.rst b/setup_guides/transformation/setup_transforms.rst index 8ee60ed06..124dd5616 100644 --- a/setup_guides/transformation/setup_transforms.rst +++ b/setup_guides/transformation/setup_transforms.rst @@ -55,13 +55,13 @@ Open up your command line and execute the following command: ros2 run tf2_ros static_transform_publisher 0.1 0 0.2 0 0 0 base_link base_laser -With this, we are now sucessfully publishing our ``base_link`` to ``base_laser`` transform in TF2. Let us now check if it is working properly through ``tf2_echo``. Open up a separate command line window and execute the following: +With this, we are now successfully publishing our ``base_link`` to ``base_laser`` transform in TF2. Let us now check if it is working properly through ``tf2_echo``. Open up a separate command line window and execute the following: .. code-block:: shell ros2 run tf2_ros tf2_echo base_link base_laser -You should be able to observe a repeated output simiar to the one below. +You should be able to observe a repeated output similar to the one below. .. code-block:: shell @@ -112,4 +112,4 @@ In this tutorial, we have discussed about the concept of transforms and how they In the last section, we have also explored using the static_transform_publisher of TF2 to publish our transforms. You may use this to set up your transforms for Nav2, but this is generally not the best way to do it. In most robotics projects, we make use of the Robot State Publisher since it is much easier to use and scales well as our robot gets more complex. We will be talking about the Robot State Publisher, URDF, and how to set it up in the next tutorial on :ref:`urdf_handson`. -Lastly, we also discussed the three published transform requirements of Nav2 and the neccessary REPs to keep in mind when setting them up. +Lastly, we also discussed the three published transform requirements of Nav2 and the necessary REPs to keep in mind when setting them up. diff --git a/setup_guides/urdf/setup_urdf.rst b/setup_guides/urdf/setup_urdf.rst index b0f72b5c8..9eec74054 100644 --- a/setup_guides/urdf/setup_urdf.rst +++ b/setup_guides/urdf/setup_urdf.rst @@ -321,7 +321,7 @@ To keep things simpler when we get to visualization, we have provided an RVIz co Value: Orbit (rviz) Saved: ~ -Lastly, let us modify the ``CMakeLists.txt`` file in the project root directory to include the files we just created during the package installation process. Add the following snippet to ``CMakeLists.txt`` file preferrably above the ``if(BUILD_TESTING)`` line: +Lastly, let us modify the ``CMakeLists.txt`` file in the project root directory to include the files we just created during the package installation process. Add the following snippet to ``CMakeLists.txt`` file preferably above the ``if(BUILD_TESTING)`` line: .. code-block:: shell @@ -372,7 +372,7 @@ Let us first define macros containing the inertial properties of the geometric p .. code-block:: xml :lineno-start: 17 - + diff --git a/tutorials/docs/adding_a_nav2_task_server.rst b/tutorials/docs/adding_a_nav2_task_server.rst index ac5b35ee9..9f8e78e9a 100644 --- a/tutorials/docs/adding_a_nav2_task_server.rst +++ b/tutorials/docs/adding_a_nav2_task_server.rst @@ -20,7 +20,7 @@ The Lifecycle node is the first key component of a nav2 task server. Lifecycle n Lifecycle nodes contain state machine transitions that enable deterministic behavior in ROS 2 servers. The Lifecycle node transitions in Nav2 are handled by the ``Lifecycle Manager``. The Lifecycle Manager transitions the states of the Lifecycle nodes and provides greater control over the state of a system. -The primary states of a Lifecycle node are ``Unconfigured``, ``Inactive``, ``Active``, and ``Finalized``. A Lifecycle node starts in an ``Unconfigured`` state after being instantiated. The Lifecycle Manager transitions a node from ``Unconfigured`` to ``Inactive`` by implementing the ``Configurating`` transition. The ``Configurating`` transition sets up all configuration parameters and prepares any required setup such as memory allocation and the set up of the static publication and subscription topics. A node in the ``Inactive`` state is allowed to reconfigure its parameters and but cannot perform any processing. From the ``Inactive`` state, the Lifecyle Manager implements the ``Activating`` transition state to transition the node from ``Inactive`` to ``Active``, which is the main state. A node in the ``Active`` state is allowed to perform any processing operation. In case a node crashes, the Lifecycle Manager shuts down the system to prevent any critical failures. On shutdown, the necessary cleanup operations are performed and the nodes are transitioned to the ``Finalized`` state via ``Deactivating``, ``CleaningUp``, and ``ShuttingDown`` transition states. +The primary states of a Lifecycle node are ``Unconfigured``, ``Inactive``, ``Active``, and ``Finalized``. A Lifecycle node starts in an ``Unconfigured`` state after being instantiated. The Lifecycle Manager transitions a node from ``Unconfigured`` to ``Inactive`` by implementing the ``Configurating`` transition. The ``Configurating`` transition sets up all configuration parameters and prepares any required setup such as memory allocation and the set up of the static publication and subscription topics. A node in the ``Inactive`` state is allowed to reconfigure its parameters and but cannot perform any processing. From the ``Inactive`` state, the Lifecycle Manager implements the ``Activating`` transition state to transition the node from ``Inactive`` to ``Active``, which is the main state. A node in the ``Active`` state is allowed to perform any processing operation. In case a node crashes, the Lifecycle Manager shuts down the system to prevent any critical failures. On shutdown, the necessary cleanup operations are performed and the nodes are transitioned to the ``Finalized`` state via ``Deactivating``, ``CleaningUp``, and ``ShuttingDown`` transition states. .. seealso:: For more information on Lifecycle management, see the article on `Managed Nodes `_. @@ -182,7 +182,7 @@ Error codes are attached to the response of the action message. An example can b As stated in the message, the priority order of the errors should match the message order, 0 is reserved for NONE and the first error code in the sequence is reserved for UNKNOWN. Since the the route server is a external server, the errors codes start at 10000 and go up to 10099. -In order to propigate your server's error code to the rest of the system it must be added to the nav2_params.yaml file. +In order to propagate your server's error code to the rest of the system it must be added to the nav2_params.yaml file. The `error_code_id_names` inside of the BT Navigator define what error codes to look for on the blackboard by the server. The lowest error code of the sequence is then returned - whereas the code enums increase the higher up in the software stack - giving higher priority to lower-level failures. diff --git a/tutorials/docs/adding_smoother.rst b/tutorials/docs/adding_smoother.rst index f384bad27..7d17a2979 100644 --- a/tutorials/docs/adding_smoother.rst +++ b/tutorials/docs/adding_smoother.rst @@ -31,7 +31,7 @@ Tutorial Steps 0- Familiarization with the Smoother BT Node -------------------------------------------- -The :ref:`bt_smooth_action` BT node is a behavior tree node that interacts with the smoother task server similar to that which you may expect to find for the planner or controller servers. It contains the action client to call the server and specifies its arguments and return types as BT ports. It too calls the server via an action interface that may be seperately interacted with via other servers and client library languages. +The :ref:`bt_smooth_action` BT node is a behavior tree node that interacts with the smoother task server similar to that which you may expect to find for the planner or controller servers. It contains the action client to call the server and specifies its arguments and return types as BT ports. It too calls the server via an action interface that may be separately interacted with via other servers and client library languages. Please see the BT node's configuration page to familiarize yourself with all aspects, but the core ports to note are the ``unsmoothed_path`` input port and the ``smoothed_path`` output port. The first takes in a raw path from a planning algorithm and the latter will set the value of the smoothed output path post-smoothing. Other ports are available that fully implements the Smoother Server's action API. diff --git a/tutorials/docs/docker_dev.rst b/tutorials/docs/docker_dev.rst index cbe4f0aa8..99c82d943 100644 --- a/tutorials/docs/docker_dev.rst +++ b/tutorials/docs/docker_dev.rst @@ -17,7 +17,7 @@ Overview ======== This tutorial is a hands on walkthrough from your first Docker usage to commands and processes you can use for development of ROS 2 applications using Docker. -This is not an exhausive introduction by any stretch, but should help you go from nothing to a functional process you can use on a daily basis for development and testing. +This is not an exhaustive introduction by any stretch, but should help you go from nothing to a functional process you can use on a daily basis for development and testing. If you know some basics about Docker already, you can skip to later sections about development and deployment. You'll also find a set of Docker images in the Appendix to this tutorial which are useful for developing with Nav2 or a containerized deployment of it. The same process template can be used for other company applications and projects as well. @@ -32,9 +32,9 @@ Preliminaries ============= Docker is a tool used to build, deploy, test, and otherwise work with software in an isolated environment, called a *container*. -This diffs from a VM in that it shares the same linux kernal as your host operating system, making it faster to spin up and share host resources. +This diffs from a VM in that it shares the same linux kernel as your host operating system, making it faster to spin up and share host resources. By building or deploying software in this isolated environment, you can ensure many users, robots, or servers are running the same software with the same software versions across many instances. -It gives you a controlled environment to work in that is reproducable on other developer's machines and even work in a different (linux-based) operating system than your computer currently runs. +It gives you a controlled environment to work in that is reproducible on other developer's machines and even work in a different (linux-based) operating system than your computer currently runs. For example, you can run a 22.04 Docker container that contains ROS 2 Humble on Nvidia Jetson's Jetpack 5.1 (which is a flavor of 20.04) and deploy that container to a fleet of robots. In common Docker language, an *image* is the built ``Dockerfile`` which can be used to create *containers*. @@ -42,7 +42,7 @@ Thus, *containers* are self-contained, runnable instances of the docker *image*. The ``Dockerfile`` is a set of instructions for how to build an image to create some kind of environment to work in - and often contain applications to deploy in that environment. The Dockerfile instruct sets have a number of options such as: -- ``ARG``: Obtain build-time arugments +- ``ARG``: Obtain build-time arguments - ``FROM``: Specify a base image to build from - ``RUN``: Run a particular command - ``WORKDIR``: Set the working directory @@ -139,7 +139,7 @@ We mentioned before that the container on spin up will automatically source the touch navigator_dockerlayer.txt l # <-- you should see this file -Nice! It all works. Now, if we exit our iteractive session (type ``exit``), we should reenter our computer. +Nice! It all works. Now, if we exit our interactive session (type ``exit``), we should reenter our computer. In that second terminal, if you rerun ``sudo docker ps``, you should see that the list of containers is now empty since our container is no longer running. If you want to see a full list of containers, including exited containers, you can use the flag ``-a`` to display all containers. @@ -270,7 +270,7 @@ For each distribution, there are a couple of variants: - ``ros-core``: Contains only the ROS core communication protocols and utilities - ``ros-base``: Contains ``ros-core`` and other core utilities like pluginlib, bond, actions, etc -- ``perception``: Contains ``ros-base`` and image common, pipeline, laser filters, laser geomtry, vision opencv, etc +- ``perception``: Contains ``ros-base`` and image common, pipeline, laser filters, laser geometry, vision opencv, etc - ``desktop``: Contains ``ros-base`` and tutorials, lifecycle, rviz2, teleop, and rqt - ``desktop-full``: Contains ``desktop``, ``perception`` and simulation @@ -422,7 +422,7 @@ Nav2 Development Image ---------------------- This container downloads, but does not install Nav2. -Instead, it pulls the dependencies so that when you run this container, you obtain everything needed to immedately start building and working with Nav2 on any ROS 2 distribution, including Rolling. +Instead, it pulls the dependencies so that when you run this container, you obtain everything needed to immediately start building and working with Nav2 on any ROS 2 distribution, including Rolling. .. code-block:: bash diff --git a/tutorials/docs/get_backtrace.rst b/tutorials/docs/get_backtrace.rst index 6c88d6913..55c2fcedb 100644 --- a/tutorials/docs/get_backtrace.rst +++ b/tutorials/docs/get_backtrace.rst @@ -174,7 +174,7 @@ From Large Project ================== Working with launch files with multiple nodes is a little different so you can interact with your GDB session without being bogged down by other logging in the same terminal. -For this reason, when working with larger launch files, its good to pull out the specific server you're interested in and launching it seperately. +For this reason, when working with larger launch files, its good to pull out the specific server you're interested in and launching it separately. These instructions are targeting Nav2, but are applicable to any large project with many nodes of any type in a series of launch file(s). As such, for this case, when you see a crash you'd like to investigate, its beneficial to separate this server from the others. @@ -189,7 +189,7 @@ If your server of interest is being launched from a nested launch file (e.g. an - Launch the server's launch file in another terminal following the instructions in `From a Launch File`_. -Alternatively, if you server of interest is being launched in these files directly (e.g. you see a ``Node``, ``LifecycleNode``, or inside a ``ComponentContainer``), you will need to seperate this from the others: +Alternatively, if you server of interest is being launched in these files directly (e.g. you see a ``Node``, ``LifecycleNode``, or inside a ``ComponentContainer``), you will need to separate this from the others: - Comment out the node's inclusion from the parent launch file @@ -228,7 +228,7 @@ To debug directly from the nav2 bringup launch files you may want to do the foll - Recompile the package of interest with ``-g`` flag for debug symbols. -- Launch normally with ``ros2 launch nav2_bringup tb3_simulation_launch.py use_composition:=False``. A seperate xterm window will open with the proccess of intrest running in gdb. +- Launch normally with ``ros2 launch nav2_bringup tb3_simulation_launch.py use_composition:=False``. A separate xterm window will open with the process of interest running in gdb. .. note:: Turning off composition has serious performance impacts. If this is important to you please follow "From Large Project". diff --git a/tutorials/docs/get_profile.rst b/tutorials/docs/get_profile.rst index ed28dd491..b664f791c 100644 --- a/tutorials/docs/get_profile.rst +++ b/tutorials/docs/get_profile.rst @@ -20,7 +20,7 @@ The following steps show ROS 2 users how to modify the Nav2 stack to get profili Preliminaries ============= -This tutorial makes use of two tools, callgrind from the ``Valgrind`` set of tools and ``kcachegrind``. Valgrind is used to get the profiling information about the program and kcachegrind is the visualization engine used to interprete this information to do useful work. +This tutorial makes use of two tools, callgrind from the ``Valgrind`` set of tools and ``kcachegrind``. Valgrind is used to get the profiling information about the program and kcachegrind is the visualization engine used to interpret this information to do useful work. Thus, we must install them. @@ -56,7 +56,7 @@ As in our generic example, for a given node, we need to compile with debug flags colcon build --packages-select --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo -Optionally, you may add the following line to the ``CMakeLists.txt`` of the package you're looking to profile. This may be preferable when you have a workspace with many packages but would like to only compile a subset with debug information using a single ``colcon build`` invokation. +Optionally, you may add the following line to the ``CMakeLists.txt`` of the package you're looking to profile. This may be preferable when you have a workspace with many packages but would like to only compile a subset with debug information using a single ``colcon build`` invocation. It is important that this should be added to both the host server and plugin packages(s) if you would like the results of a plugin's run-time profile. diff --git a/tutorials/docs/integrating_vio.rst b/tutorials/docs/integrating_vio.rst index 6fc8c8f2c..49c082c11 100644 --- a/tutorials/docs/integrating_vio.rst +++ b/tutorials/docs/integrating_vio.rst @@ -43,7 +43,7 @@ We're using the ZED X for the purposes of this tutorial due to its: - Smaller size similar to other AMR depth sensors -- High quality depth information at relevent ranges for mobile robotics and manipulation +- High quality depth information at relevant ranges for mobile robotics and manipulation - Hardware synchronized IMU @@ -148,7 +148,7 @@ While out of the scope of this tutorial, it is possible to continue to produce V - Fuse that topic into a global localization EKF in ``world_frame: map`` along with other sources of information (e.g. external IMU, AMCL, GPS, etc). -- The fusion of multiple global localization techniques should be done carefully. The most trusted source should be set ``_differential: false`` to use the actual pose information. All other subsiquent systems should use ``_differential: true`` so that diverging coordinate systems do not create bouncing solutions. Instead, this will fuse one as absolute poses and the other as the changes of poses between iterations. +- The fusion of multiple global localization techniques should be done carefully. The most trusted source should be set ``_differential: false`` to use the actual pose information. All other subsequent systems should use ``_differential: true`` so that diverging coordinate systems do not create bouncing solutions. Instead, this will fuse one as absolute poses and the other as the changes of poses between iterations. Testing it Out! @@ -160,7 +160,7 @@ The Visual-Inertial Odometry's error over these datasets is 4.1% over the 70m pa .. note:: - Steve is walking his robot dog through Golden Gate Park in San Francisco, CA with a joystick to collect this data. Steve's a bad robot driver (he doesn't play video games), the zig-zagging you see is due to his lack of good joystick control + the quadruped has alot of additional assymmetric weight on it. It is not representative of Nav2 and should be mocked. *Its meant to test the accuracy of the VIO solution in more harsh conditions... yeah... lets go with that*. + Steve is walking his robot dog through Golden Gate Park in San Francisco, CA with a joystick to collect this data. Steve's a bad robot driver (he doesn't play video games), the zig-zagging you see is due to his lack of good joystick control + the quadruped has a lot of additional asymmetric weight on it. It is not representative of Nav2 and should be mocked. *Its meant to test the accuracy of the VIO solution in more harsh conditions... yeah... lets go with that*. .. raw:: html diff --git a/tutorials/docs/navigation2_on_real_turtlebot3.rst b/tutorials/docs/navigation2_on_real_turtlebot3.rst index 2979b8a14..a128760c1 100644 --- a/tutorials/docs/navigation2_on_real_turtlebot3.rst +++ b/tutorials/docs/navigation2_on_real_turtlebot3.rst @@ -33,8 +33,8 @@ If you don't have them installed, please follow :ref:`getting_started`. Tutorial Steps ============== -0- Setup Your Enviroment Variables ----------------------------------- +0- Setup Your Environment Variables +----------------------------------- Run the following commands first whenever you open a new terminal during this tutorial. diff --git a/tutorials/docs/navigation2_with_keepout_filter.rst b/tutorials/docs/navigation2_with_keepout_filter.rst index 047cd67b5..8308128d4 100644 --- a/tutorials/docs/navigation2_with_keepout_filter.rst +++ b/tutorials/docs/navigation2_with_keepout_filter.rst @@ -53,7 +53,7 @@ where ``free_thresh`` and ``occupied_thresh`` thresholds are expressed in percen There is another parameter in a YAML metadata file called ``negate``. By default it is set to ``false``. When it is set to ``true``, blacker pixels will be considered as free, whiter pixels - as occupied. In this case we should count color lightness instead of darkness for ``trinary`` and ``scale`` modes. ``negate`` has no effect on ``raw`` mode. -For Keepout Filter ``OccupancyGrid`` value is proportional to the passibility of area corresponting to this cell: higher values means more impassable areas. Cells with occupied values covers keep-out zones where robot will never enter or pass through. ``KeepoutFilter`` can also act as a "weighted areas layer" by setting the ``OccupancyGrid`` to something between ``[1-99]`` non-occupied values. Robot is allowed to move in these areas, however its presence there would be "undesirable" there (the higher the value, the sooner planners will try to get the robot out of this area). +For Keepout Filter ``OccupancyGrid`` value is proportional to the passibility of area corresponding to this cell: higher values means more impassable areas. Cells with occupied values covers keep-out zones where robot will never enter or pass through. ``KeepoutFilter`` can also act as a "weighted areas layer" by setting the ``OccupancyGrid`` to something between ``[1-99]`` non-occupied values. Robot is allowed to move in these areas, however its presence there would be "undesirable" there (the higher the value, the sooner planners will try to get the robot out of this area). Keepout Filter also covers preferred lanes case, where robots should moving only on pre-defined lanes and permitted areas e.g. in warehouses. To use this feaure you need to prepare the mask image where the lanes and permitted areas will be marked with free values while all other areas will be occupied. TIP for drawing the mask in a ``trinary`` or ``scale`` mode: typically, amount of pixels belonging to lanes are much less than pixels covering other areas. In this case initially all lanes data might be drawn with a black pencil over white background and then (just before saving a PGM) "color inversion" tool in a image raster editor might be used. diff --git a/tutorials/docs/navigation2_with_stvl.rst b/tutorials/docs/navigation2_with_stvl.rst index 1e08f20cb..b88453276 100644 --- a/tutorials/docs/navigation2_with_stvl.rst +++ b/tutorials/docs/navigation2_with_stvl.rst @@ -42,7 +42,7 @@ Another available pluginlib plugin for Costmap2D in Navigation2 is STVL. STVL is another 3D perception plugin similar to the Voxel Layer. A more detailed overview of how it works can be found `in this repo `_, however it buffers 3D data from depth cameras, sonars, lidars, and more into a sparse volumetic world model and removes voxels over time proportional with a sensor model and time-based expiration. -This can be especially useful for robots in highly dynamic envrionments and decreases the resource utilization for 3D sensor processing by up to 2x. +This can be especially useful for robots in highly dynamic environments and decreases the resource utilization for 3D sensor processing by up to 2x. STVL also treats 3D lidars and radars as first class citizens for support. The ROSCon talk for STVL can be found `in this video `_. diff --git a/tutorials/docs/using_collision_monitor.rst b/tutorials/docs/using_collision_monitor.rst index a32423312..7b54e4570 100644 --- a/tutorials/docs/using_collision_monitor.rst +++ b/tutorials/docs/using_collision_monitor.rst @@ -115,7 +115,7 @@ Configuring Collision Monitor with VelocityPolygon .. image:: images/Collision_Monitor/dexory_velocity_polygon.gif :width: 800px -For this part of tutorial, we will set up the Collision Monitor with ``VelocityPolygon`` type for a ``stop`` action. ``VelocityPolygon`` allows the user to setup multiple polygons to cover the range of the robot's velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot's velocity against each sub polygon to determine the approriate polygon to be used for collision checking. +For this part of tutorial, we will set up the Collision Monitor with ``VelocityPolygon`` type for a ``stop`` action. ``VelocityPolygon`` allows the user to setup multiple polygons to cover the range of the robot's velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot's velocity against each sub polygon to determine the appropriate polygon to be used for collision checking. In general, here are the steps to configure the Collision Monitor with ``VelocityPolygon`` type: