Merge pull request #235 from clearpathrobotics/ONAV-2127

Assisted teleop documentation + release notes

docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx

@@ -16,6 +16,49 @@ The OutdoorNav software publishes to the topics in this section either
 all the time or while an autonomous navigation missions is running. They
 can be used to monitor the behaviour of OutdoorNav.
 
+
+#### /assisted_teleop/cmd_vel
+
+  **Message Type:** geometry_msgs/Twist
+
+  **Description:** The safe output velocity from the assisted teleop node
+computes. If assisted teleop is enabled the UGV will use this velocity.
+
+#### /assisted_teleop/footprint
+
+  **Message Type:** geometry_msgs/Polygon
+
+  **Description:** The footprint that the assisted teleop node uses to compute
+if it is in a collision state.
+
+#### /assisted_teleop/obstacle_map
+
+  **Message Type:** [clearpath_safety_msgs/ObstacleMap](definitions.mdx#msg-obstacle-map)
+
+  **Description:** The radial mapping of detected obstacles used to populate the joystick
+on the OutdoorNav UI.
+
+#### /assisted_teleop/safe_path
+
+  **Message Type:** nav_msgs/Path
+
+  **Description:** The path used by assisted teleop to lookahead for collisions.
+
+#### /assisted_teleop/safety_footprints
+
+  **Message Type:** nav_msgs/Path
+
+  **Description:** Footprint sets used for detecting obstacles and slowing
+down the robot to a standstill. The footprints are modular in size
+according to the current velocity of the robot.
+
+#### /assisted_teleop/state
+
+  **Message Type:** [clearpath_safety_msgs/AssistedTeleopState](definitions.mdx#msg-assisted-teleop-state)
+
+  **Description:** The current state of the assisted teleop node including
+any error conditions that may occur.
+
 #### /control_selection/control_state
 
   **Message Type:** [clearpath_control_msgs/ControlSelectionState](definitions.mdx#msg-control-selection-state)
@@ -116,7 +159,7 @@ Unknown space that the robot uses to detect obstacles.
 
 #### /navigation/local_plan
 
-  **Message Type:** nav_msgs/msg/Path
+  **Message Type:** nav_msgs/Path
 
   **Description:** The MPC local plan that the navigation uses to control
 the robot along the reference path.

docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx

@@ -588,6 +588,36 @@ uint8 trigger_type
 string message
 ```
 
+#### clearpath_safety_msgs/AssistedTeleopState.msg {#msg-assisted-teleop-state}
+
+```
+# Assisted teleoperation message indicating the current state of the protection
+
+uint8 STATE_ACTIVE = 0
+uint8 STATE_DISABLED = 1
+uint8 STATE_COLLISION_IMMINENT = 2
+uint8 STATE_STOPPED = 3
+uint8 STATE_COLLISION = 4
+uint8 STATE_ERROR = 5
+uint8 state
+
+uint8 ASSIST_ON = 100
+uint8 ASSIST_OFF_SERVICE = 101
+uint8 ASSIST_OFF_JOYSTICK_OVERRIDE = 102
+uint8 ASSIST_OFF_SENSOR_TIMEOUT = 103
+uint8 assist_off_trigger
+
+string error_message
+```
+
+#### clearpath_safety_msgs/ObstacleMap.msg {#msg-obstacle-map}
+
+```
+# Assisted teleoperation message indicating the threat level of obstacles surrounding the platform
+
+float32[] threat_level
+```
+
 #### clearpath_safety_msgs/WatchdogStatus.msg {#msg-safety-watchdog}
 
 ```
@@ -947,6 +977,9 @@ bool ok
 ```
 # A list of UUIDs of items we want to delete
 string[] uuids
+
+# An optional ID of the parent object we're deleting from
+string parent_id
 ---
 # A list of UUIDs that we were asked to delete, but failed to
 string[] failed_uuids

docs_outdoornav_user_manual/features/assisted_teleoperation.mdx

@@ -0,0 +1,105 @@
+---
+title: Assisted Teleoperation
+sidebar_label: Assisted Teleoperation
+sidebar_position: 1
+toc_min_heading_level: 2
+toc_max_heading_level: 4
+---
+
+:::danger SAFETY WARNING
+
+Making changes to any of the following variables will decrease system safety. It is recommended that users
+only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx).
+
+:::
+
+:::note
+
+Changes to any of the following variables will only take effect after power cycling the UGV.
+
+:::
+
+
+As of version 0.12.0, the OutdoorNav software contains an assisted teleoperation feature that will help users
+teleoperate their UGV safely, without worry of colliding into obstacles.
+
+<center>
+  <figure>
+    <img
+      src="/img/outdoornav_images/assisted_teleop_twist_mux.png"
+      width="1000"
+    />
+    <figcaption>Block Diagram of Assisted Teleoperation Twist Mux</figcaption>
+  </figure>
+</center>
+
+
+The assisted teleoperation feature is intended to work with the following sources of velocity input:
+
+| Input source | Topic  |
+|--------------|--------|
+| UI Joystick         | `/ui_teleop/cmd_vel` |
+| PS4 Controlller     | `/bluetooth_teleop/cmd_vel` or `/joy_teleop/cmd_vel`|
+| Logitech Controller | `/joy_teleop/cmd_vel` | 
+
+
+The Assisted teleop feature will **NOT** work on the following sources of velocity input:
+
+| Input source | Topic |
+|--------------|-------|
+| External Command   | `/cmd_vel` |
+| Keyboard Command   | `/kb_teleop/cmd_vel` |
+| Interactive Marker | `/twist_marker_server/cmd_vel` |
+
+The Assisted Teleoperation feature can be activated/deactivated according to your required application requirements.
+This can be done by setting the **ENABLE_ASSISTED_TELEOP** environment variable in the 
+`/opt/onav/<onav_version>/config/autonomy.env` file, where *onav_version*
+is the currently running version of OutdoorNav.
+
+## Functionality
+
+The intended purpose for the assisted teleoperation feature is to provide some software level safety for users while they are teleoperating the UGV.
+This feature is intended to solely provide software level safety and does not use any hardware level PLCs to trigger a motor disconnect. It is to be
+treated as a tool that provides a sense of security to the user, such that they will not accidentally crash the UGV any obstacles. The feature
+constantly monitors the 2D/3D LiDAR sensor data that it is provided and uses this information to control the velocity of the UGV. As the UGV 
+approaches obstacles, it will decrease the velocity of the UGV and will bring the UGV to a complete stop if the user continues to drive 
+towards the oncoming obstacle.
+
+For visualization details of the assisted teleoperation feature, please consult the [UI Manual Mode](../web_user_interface/ui_manual_mode.mdx) page.
+
+### Enable/Disable from the UI
+
+From the OutdoorNav UI you are able to enable/disable the "Teleop Assist" by using the toggle that is located by the UI joystick.
+
+### Enable/Disable using Joystick
+
+To disable the "Teleop Assist" when driving the UGV with the PS4 or Logitech controllers, you will need to press and hold the following button:
+
+| Controller Type  | Button |
+|--------------|-------|
+| PS4 controller   | **O** |
+| Logitech controller   | **B** |
+
+### Error/Warnings
+
+OutdoorNav will throw warnings and display them on the UI related to the status of the assisted teleoperation feature.
+Below are the errors/warnings you may see:
+
+| Error/Warning | Reason |
+|---------------|--------|
+| **"Error: Failed to communicate with the Assisted Teleop node"** | The assisted teleoperation node is not running or has crashed |
+| **"Error: No sensors configured"**  | The assisted teleoperation node is running but no sensors have been configured to be used as obstacle detection sources |
+| **"Error: Invalid twist_mux configuration"** | The twists mux configuration has been modified and does not satisfy the requirements for safe operation under the requirements of assisted teleoperation  |
+| **"Error: Unknown platform type"** | The assisted teleoperation node cannot determine the type of platform you are on |
+| **"WARNING: Assisted teleoperation OFF due to service"** | The UI toggle switch or the `/assisted_teleop/enable` service has disabled assisted teloperation |
+| **"WARNING: Assisted teleoperation OFF due to joystick override"** | The enable/disable button on the UGV remote joystick has been pressed |
+| **"WARNING: Assisted teleoperation OFF due to sensor timeout"** | Communication has been lost between the assisted teloperation node and one of the configured 2D/3D detection sensors. |
+| **"Warning: Robot is in a collision state and cannot be driven while assisted teleop is enabled. Please disable assisted teleop to recover."** | The robot is is a state where is is too close to an obstacle. This will mostly occur when you are at a charge dock but may also occur if you are driving/rotating in a tight space. You may need to disable the Teleop Assist to continue remote operation |
+
+
+## Limitations
+
+The assisted teleoperation features has similar limitations to those of our collision avoidance features. 
+Performance degradation will be experiences in rain and/or snow conditions, as well as in tall grass environments.
+The assisted teleoperation feature also only work if obstacles are detected by the 3D sensors. If obstacles appear
+in any of the UGVs blind spots, the assisted teleoperation feature will not prevent collision with these obstacles.

docs_outdoornav_user_manual/features/collision_avoidance.mdx

@@ -9,7 +9,7 @@ toc_max_heading_level: 4
 :::danger SAFETY WARNING
 
 Making changes to any of the following variables may decrease system safety. It is recommended that users
-only modify these parameters in consultation with Clearpath Robotics Support.
+only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx).
 
 :::
 

docs_outdoornav_user_manual/release_notes.mdx

@@ -6,6 +6,43 @@ toc_min_heading_level: 2
 toc_max_heading_level: 4
 ---
 
+## 0.12.0
+
+### New Features
+-   Modified mission planning modes. Now includes:
+    -   Map mode (which allows the user to create maps of an environment 
+        and send mission using said map)
+    -   Waypoint mode (which allows the user to create more direct mission 
+        by placing waypoints directly on the Aerial overlay)
+-   Added an Assisted teleoperation feature to prevent robot collisions with 
+    obstacles when it is being teleoperated.
+-   Added the upgrade command to the CLI tool. Customers can now upgrade their 
+    software as long as they are eligible to be upgraded to the newest version. 
+    Please contact [Support](./support.mdx) for more information.
+-   New visualization of status command in CLI tool
+-   Added a filebrowser extension to access/view the robot filesystem for easier 
+    media access
+
+### API Features
+
+-   Added new message definitions and service calls for the storage/editing of Maps
+
+### Bug Fixes
+
+-   1973: Fixed python “machineid” error during installation
+-   2089: Fixed the no serial number on /platform/id topic
+-   2169: Fixed the mission manager/scheduler still requesting during Teleop only mode
+
+### Known Issues
+
+-   1396: Robot gets temporarily stuck at start of mission when near a Waypoint
+-   1844: [MPC] Maximum acceleration param doesn't appear to have any effect
+-   2332: upgrading from 0.11 to 0.12.0 in teleoperation only configuration and Q62 
+    installed causes duplication of axis driver. Please contact [Support](./support.mdx)
+    if you run into this issue.
+-   2344: Autonomy not going down during low-power mode
+-   2360: Waypoint/Map modes use different mouse click to open context menus
+
 ## 0.11.0
 
 ### New Features
@@ -44,7 +81,7 @@ toc_max_heading_level: 4
 
 ### API Features
 
--   Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api))
+-   Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx))
     -   Mission.action added from_start and *start_waypoint_uuid* fields
     -   ExecuteMissionByUuid.action:  added from_start and *start_waypoint_uuid* fields
 -   Message Definition changes