From db157f1341bc69816d97f0c0857029ce351642a1 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Mon, 19 Aug 2024 17:05:39 -0700 Subject: [PATCH 1/3] adding doc updates for docking Signed-off-by: Steve Macenski --- .../packages/configuring-docking-server.rst | 5 +-- migration/Jazzy.rst | 9 ++++- tutorials/docs/using_docking.rst | 34 ++++++++++--------- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/configuration/packages/configuring-docking-server.rst b/configuration/packages/configuring-docking-server.rst index 107dc33cd..9d35bfb1f 100644 --- a/configuration/packages/configuring-docking-server.rst +++ b/configuration/packages/configuring-docking-server.rst @@ -8,7 +8,8 @@ Source code on Github_. .. _Github: https://github.com/open-navigation/opennav_docking The Docking Server in ``opennav_docking`` implements a server for docking and undocking a robot. -It uses plugin `dock` implementations for a particular platform to enable the framework to generalize to robots of many different kinematic models, charging methods, sensor modalities, and so on. +This can be from Charging stations (i.e. docks) or non-charging docking locations such as the end of a conveyer belt or a pallet. +It uses plugin `dock` implementations for a particular platform to enable the framework to generalize to robots of many different kinematic models, charging methods, sensor modalities, charging-type, and so on. It can also handle a database of many different docking locations and dock models to handle a heterogeneous environment. This task server is designed be called by an application BT or autonomy application to dock once completed with tasks or battery is low -- not within the navigate-to-pose action itself (though `undock` may be called from inside navigate actions!). @@ -489,7 +490,7 @@ Example # Types of docks dock_plugins: ['nova_carter_dock'] nova_carter_dock: - plugin: 'opennav_docking::SimpleChargingDock' + plugin: 'opennav_docking::SimpleChargingDock' # Also 'opennav_docking::SimpleNonChargingDock' docking_threshold: 0.05 staging_x_offset: -0.7 use_external_detection_pose: true diff --git a/migration/Jazzy.rst b/migration/Jazzy.rst index 627397589..72797814b 100644 --- a/migration/Jazzy.rst +++ b/migration/Jazzy.rst @@ -8,9 +8,16 @@ Moving from ROS 2 Jazzy to K-Turtle, a number of stability improvements were add New Nav2 Loopback Simulator *************************** -The ``nav2_looback_sim`` is a stand-alone simulator to create a "loopback" for non-physical simulation to replace robot hardware, physics simulators (Gazebo, Bullet, Isaac Sim, etc). +The ``nav2_loopback_sim`` is a stand-alone simulator to create a "loopback" for non-physical simulation to replace robot hardware, physics simulators (Gazebo, Bullet, Isaac Sim, etc). It computes the robot's odometry based on the command velocity's output request to create a perfect 'frictionless plane'-style simulation for unit testing, system testing, R&D on higher level systems, testing behaviors without concerning yourself with localization accuracy or system dynamics, and multirobot simulations. +Docking with Static Infrastructure or Dynamic Docking +***************************************************** + +In `PR #4627 `_ a docking plugin type and logic was added to support non-charging dock types in the nav2 docking server. +This allows users to specify docking locations to static infrastructure, such as conveyers, or dynamic docking locations, such as a pallet. +It also includes a new docking plugin to demonstrate the new docking server capabilities ``simple_non_charging_dock``. + New RViz panel for Docking ************************** diff --git a/tutorials/docs/using_docking.rst b/tutorials/docs/using_docking.rst index 0bf361622..74cecc87d 100644 --- a/tutorials/docs/using_docking.rst +++ b/tutorials/docs/using_docking.rst @@ -16,10 +16,11 @@ Overview This tutorial shows how to use the Docking Server with Nav2 robot systems. The Docking Server is a general framework which can be used with arbitrary types of robots and charging docks in order to auto-dock them. -This is accomplished via plugin ``ChargingDock`` s which implement the dock specifics like detecting the pose of the dock using sensor data, how to detect when the robot is in contact with the dock, and when charging has successfully started. -A configuration of the docking server can contain a database of many docks of different plugin ``ChargingDock`` types to handle a broad range of docking locations and hardware dock revisions. -Included with the package is an example ``SimpleChargingDock`` plugin which contains features and methods very common for robot docking. -It is likely that you may be able to use this as well rather than developing your own charging dock plugin to get started. +This is accomplished via plugins ``ChargingDock`` and ``NonChargingDock`` which implement the dock specifics like detecting the pose of the dock using sensor data, how to detect when the robot is in contact with the dock, and when charging has successfully started. +A configuration of the docking server can contain a database of many docks of different plugin ``ChargingDock`` and ``NonChargingDock`` types to handle a broad range of docking locations and hardware dock revisions. +Included with the package is an example ``SimpleChargingDock`` and ``SimpleNonChargingDock`` plugins which contains features and methods very common for robot docking. +These support charging stations and docking with static infrastructure (ex. conveyer belts) or dynamic docking (ex pallets) locations. +It is likely that you may be able to use this as well rather than developing your own dock plugin to get started. The docking procedure is as follows: @@ -28,7 +29,7 @@ The docking procedure is as follows: 3. Use the dock's plugin to initially detect the dock and return the docking pose 4. Enter a vision-control loop where the robot attempts to reach the docking pose while its actively being refined by the vision system 5. Exit the vision-control loop once contact has been detected or charging has started -6. Wait until charging starts and return success. +6. Wait until charging starts (if applicable) and return success. Thanks to NVIDIA for sponsoring this Docking Server package and this tutorial! You can find how to dock your Nova Carter robot using Nav2 and this work in the `nova_carter_docking package `_! @@ -53,33 +54,34 @@ See ``opennav_docking`` README for complete concept explanations, parameters, an ChargingDock Plugins ==================== -``opennav_docking_core::ChargingDock`` plugins are established to abstract out robot- and dock-specifics from the generalized framework. +``opennav_docking_core::ChargingDock`` and ``opennav_docking_core::ChargingDock`` plugins are established to abstract out robot- and dock-specifics from the generalized framework. This allows a system to leverage this framework and provide its own methods for detecting the dock's current pose, when the robot is charging, and when contact is made. -Luckily, there are several common ROS APIs that allow us to create a semi-generalized ``SimpleChargingDock`` plugin that allows out-of-the-box docking as long as users provide ``JointState``, ``BatteryState``, and detected dock pose ``PoseStamped`` topics. -However, one way or another, your system requires an applicable ``ChargingDock`` plugin for each type of dock you wish to use. +Luckily, there are several common ROS APIs that allow us to create semi-generalized ``SimpleChargingDock`` and ``SimpleNonChargingDock`` plugins that allows out-of-the-box docking as long as users provide ``JointState``, ``BatteryState``, and detected dock pose ``PoseStamped`` topics. +However, one way or another, your system requires an applicable ``ChargingDock`` or ``NonChargingDock`` plugin for each type of dock you wish to use. -The ``ChargingDock`` plugin has a few key APIs: +The plugins has a few key APIs: - ``PoseStamped getStagingPose(const Pose & pose, const string & frame)`` which must provide the pre-docking staging pose given a dock's location and frame. - ``bool getRefinedPose(PoseStamped & pose)`` which must provide the detected (or pass through) pose of the dock - ``bool isDocked()`` which provides if we've made contact with the dock -- ``bool isCharging()`` which provides if we've started charging while docked -- ``bool disableCharging()`` which should disable charging, if under the robot's control for undocking -- ``bool hasStoppedCharging()`` which indicates if we've successfully stopped charging on undocking +- ``bool isCharging()`` which provides if we've started charging while docked (charging docks only) +- ``bool disableCharging()`` which should disable charging, if under the robot's control for undocking (charging docks only) +- ``bool hasStoppedCharging()`` which indicates if we've successfully stopped charging on undocking (charging docks only) The ``SimpleChargingDock`` provides an implementation with common options for these APIs: - ``getStagingPose`` - Finds a relative offset pose with translation and rotation from the dock's pose - ``getRefinedPose`` - Filters a detected pose topic of type ``PoseStamped`` into the fixed frame *or* is a pass through function returning the dock's database location if detection is not enabled - ``isDocked`` - Returns as dock if a pose tolerance is met relative to the dock *or* if the ``JointStates`` of the motors detect a clear spike due to stalling by driving into the dock's surface, if enabled -- ``isCharging`` - Returns charging if ``isDocked`` *or* if ``BatteryState``'s current is above a threshold, if enabled -- ``disableCharging`` - Always ``true``, considers disable of charging as automatic when robot leaves dock -- ``hasStoppedCharging`` - The inverse of ``isCharging`` +- ``isCharging`` - Returns charging if ``isDocked`` *or* if ``BatteryState``'s current is above a threshold, if enabled (charging docks only) +- ``disableCharging`` - Always ``true``, considers disable of charging as automatic when robot leaves dock (charging docks only) +- ``hasStoppedCharging`` - The inverse of ``isCharging`` (charging docks only) Thus, for testing (no detection, no battery information, no joint state information) and realistic application (dock detection, battery status information, joint state information), this dock plugin can be used. It can also be used when only some of the information if available as well. If your robot or dock does not fall into these implementations (i.e. using custom battery or detection messages that cannot be converted into ROS standard types), then you may be required to build your own plugin to meet your particular needs. However, you can use the ``SimpleChargingDock`` assuming you turn off these settings and dock blind to get started. +There is an equivalent ``SimpleNonChargingDock`` plugin for non-charging docking needs. If you do not currently have a way to detect your dock, dock detection can be done easily using Apriltags and the `isaac_ros_apriltag `_ or `ROS image_proc `_ nodes to get started. Use the Isaac ROS if using a Jetson platform to obtain a GPU optimized pipeline with your camera feeds. @@ -150,7 +152,7 @@ The analog of this is shown below as an independent ``dock_database.yaml`` which Note that you are required to provide at least 1 dock plugin and 1 dock instance. The Docking Server's Action API can take in a dock's instance information separately to bypass the database, but its plugin must exist in the server's configuration. If you plan to only use this API, you can set a ``dummy_dock``. -Generally speaking, its wise to set your docks in the database and use the Docking Server's API to dock at an instance's Dock ID to decouple the semantic information about docks from the action request (requiring your application instead to have all of the docks' locations), but bypassing the database can be useful for testing. +Generally speaking, its wise to set your docks in the database and use the Docking Server's API to dock at an instance's Dock ID to decouple the semantic information about docks from the action request (requiring your application instead to have all of the docks' locations), but bypassing the database can be useful for testing and movable docking targets. The dock poses in the map can be annotated using your favorite map editing tools, obtained by ``/clicked_point`` in rviz2, or measured location. From 5e23fac119377d8d09f15273698c7f5ec4524e2a Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Mon, 19 Aug 2024 17:08:46 -0700 Subject: [PATCH 2/3] fix spelling Signed-off-by: Steve Macenski --- configuration/packages/configuring-docking-server.rst | 2 +- tutorials/docs/using_docking.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/configuration/packages/configuring-docking-server.rst b/configuration/packages/configuring-docking-server.rst index 9d35bfb1f..937766a64 100644 --- a/configuration/packages/configuring-docking-server.rst +++ b/configuration/packages/configuring-docking-server.rst @@ -8,7 +8,7 @@ Source code on Github_. .. _Github: https://github.com/open-navigation/opennav_docking The Docking Server in ``opennav_docking`` implements a server for docking and undocking a robot. -This can be from Charging stations (i.e. docks) or non-charging docking locations such as the end of a conveyer belt or a pallet. +This can be from Charging stations (i.e. docks) or non-charging docking locations such as the end of a conveyor belt or a pallet. It uses plugin `dock` implementations for a particular platform to enable the framework to generalize to robots of many different kinematic models, charging methods, sensor modalities, charging-type, and so on. It can also handle a database of many different docking locations and dock models to handle a heterogeneous environment. This task server is designed be called by an application BT or autonomy application to dock once completed with tasks or battery is low -- not within the navigate-to-pose action itself (though `undock` may be called from inside navigate actions!). diff --git a/tutorials/docs/using_docking.rst b/tutorials/docs/using_docking.rst index 74cecc87d..91eab963b 100644 --- a/tutorials/docs/using_docking.rst +++ b/tutorials/docs/using_docking.rst @@ -19,7 +19,7 @@ The Docking Server is a general framework which can be used with arbitrary types This is accomplished via plugins ``ChargingDock`` and ``NonChargingDock`` which implement the dock specifics like detecting the pose of the dock using sensor data, how to detect when the robot is in contact with the dock, and when charging has successfully started. A configuration of the docking server can contain a database of many docks of different plugin ``ChargingDock`` and ``NonChargingDock`` types to handle a broad range of docking locations and hardware dock revisions. Included with the package is an example ``SimpleChargingDock`` and ``SimpleNonChargingDock`` plugins which contains features and methods very common for robot docking. -These support charging stations and docking with static infrastructure (ex. conveyer belts) or dynamic docking (ex pallets) locations. +These support charging stations and docking with static infrastructure (ex. conveyor belts) or dynamic docking (ex pallets) locations. It is likely that you may be able to use this as well rather than developing your own dock plugin to get started. The docking procedure is as follows: From 596fac93c4ca94b477bb2b3ff68cc072608df0a5 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Mon, 19 Aug 2024 17:16:19 -0700 Subject: [PATCH 3/3] a few final touches --- roadmap/roadmap.rst | 7 +++++-- tutorials/docs/using_docking.rst | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/roadmap/roadmap.rst b/roadmap/roadmap.rst index 570b1cb35..f4a5aec28 100644 --- a/roadmap/roadmap.rst +++ b/roadmap/roadmap.rst @@ -24,11 +24,11 @@ Jazzy Roadmap | | | | | | +--------------------------------+------------------------+ -| `Fuse Migration`_ | Medium | +| `Fuse Migration`_ | Medium (incomplete) | | | | | | | +--------------------------------+------------------------+ -| `Ignition Migration`_ | Medium (in progress) | +| `Ignition Migration`_ | Medium (DONE) | | | | | | | +--------------------------------+------------------------+ @@ -52,6 +52,9 @@ Jazzy Roadmap | Monitor Polygons | | | | | +--------------------------------+------------------------+ +| Nav2 auto-docking capability | Medium (DONE) | +| | | ++--------------------------------+------------------------+ Iron Roadmap ************ diff --git a/tutorials/docs/using_docking.rst b/tutorials/docs/using_docking.rst index 91eab963b..b4f929ed9 100644 --- a/tutorials/docs/using_docking.rst +++ b/tutorials/docs/using_docking.rst @@ -15,7 +15,7 @@ Overview ======== This tutorial shows how to use the Docking Server with Nav2 robot systems. -The Docking Server is a general framework which can be used with arbitrary types of robots and charging docks in order to auto-dock them. +The Docking Server is a general framework which can be used with arbitrary types of robots and docks in order to auto-dock them. This is accomplished via plugins ``ChargingDock`` and ``NonChargingDock`` which implement the dock specifics like detecting the pose of the dock using sensor data, how to detect when the robot is in contact with the dock, and when charging has successfully started. A configuration of the docking server can contain a database of many docks of different plugin ``ChargingDock`` and ``NonChargingDock`` types to handle a broad range of docking locations and hardware dock revisions. Included with the package is an example ``SimpleChargingDock`` and ``SimpleNonChargingDock`` plugins which contains features and methods very common for robot docking.