diff --git a/README.md b/README.md index f9388449..01613a15 100644 --- a/README.md +++ b/README.md @@ -57,20 +57,22 @@ 6. Resolve any errors that the terminal reports, and rerun the command `npm run build`. 7. Finally, check that your updates adhere to our code formatting standard, by running the command `npm run format-check`. The terminal will either report: + - _All matched files use Prettier code style!_ - _Code style issues found in the above file(s). Forgot to run Prettier?_ You can fix the errors by running Prettier on a single file, with `npx prettier --write `. For example, you can run the command `npx prettier --write README.md` to format this README. + - Refer to the _package.json_ to understand what this script calls. - Refer to the _.prettierrc.json_ to understand the rules Prettier is using when checking files. - + Note, we used to suggest the command `npm run format-write` to update all the files in this repository. We don't suggest this command anymore, since it is then difficult for reviewers of Pull Requests to find the intended content changes. If you do continue to use this entire repositry command, you may see files that claim to be updated in Source Control, but don't have any visible changes. If so, you should run these commands in your terminal to prevent Git from noting these types of changes: - git config --global core.filemode false - git config --global core.autocrlf false + git config --global core.filemode false + git config --global core.autocrlf false 8. When ready, publish your branch on GitHub, and submit a Pull Request to merge your changes into the _development_ branch. Pull Requests to the _production_ branch will not merged. @@ -258,7 +260,8 @@ Follow this process to keep the _development_ and _production_ branches aligned, 4. After the Pull Request has been approved, you can merge it using the Create-a-Merge-Commit option. You should not use the Squash-and-Merge option here, otherwise _production_ will not have the latest commits from _development_, which were created in step 1 of this list. The source data will be the same on the 2 branches, but the commit hashes will not be aligned. - The Create-a-Merge-Commit option prevents this issue, by adding all the commits from _development_ to _production_, and also adding a commit to _production_ that mentions the Pull Request. + The Create-a-Merge-Commit option prevents this issue, by adding all the commits from _development_ to _production_, and also adding a commit to _production_ that mentions the Pull Request. + 5. _production_ has been updated, but it is one commit ahead of _development_. We want to update _development_ so we do not experience rebase issues next time we want to update the _production_ branch. To update _development_, go to VS Code: @@ -268,7 +271,7 @@ Follow this process to keep the _development_ and _production_ branches aligned, 4. Run `git rebase production`. This should pull one commit into _development_. It should be the commit related to merging the Pull Request. 5. Force Push this commit to the _development_ branch on GitHub. - Note: our branch protection rules in the GitHub repository only allow Administrators and Owners to Force Push to the _production_ and _development_ branches. + Note: our branch protection rules in the GitHub repository only allow Administrators and Owners to Force Push to the _production_ and _development_ branches. ## How does the deployed website get updated? diff --git a/components/introduction_husky_observer.mdx b/components/introduction_husky_observer.mdx new file mode 100644 index 00000000..654faf4c --- /dev/null +++ b/components/introduction_husky_observer.mdx @@ -0,0 +1,8 @@ +
+ +
+ +--- diff --git a/docs/robots/accessories/manipulators/kinova_gen3_lite.mdx b/docs/robots/accessories/manipulators/kinova_gen3_lite.mdx index da3cd076..0ff6897a 100644 --- a/docs/robots/accessories/manipulators/kinova_gen3_lite.mdx +++ b/docs/robots/accessories/manipulators/kinova_gen3_lite.mdx @@ -18,7 +18,7 @@ import TabItem from "@theme/TabItem"; | Description | CPR Item | | :-------------------------------- | :------------------------------------------------------: | -| Kinova Gen3 lite Bundle | [022586](/assets/pdf/clearpath_robotics_015822-TDS1.pdf) | +| Kinova Gen3 lite Bundle | [022586](/assets/pdf/clearpath_robotics_022586-TDS2.pdf) | | Kinova Gen3 lite, PACS™ kit | 027219 | --- diff --git a/docs/robots/indoor_robots/boxer/user_manual_boxer.mdx b/docs/robots/indoor_robots/boxer/user_manual_boxer.mdx index 6ec0ac21..5808abb5 100644 --- a/docs/robots/indoor_robots/boxer/user_manual_boxer.mdx +++ b/docs/robots/indoor_robots/boxer/user_manual_boxer.mdx @@ -215,7 +215,7 @@ Pull the robot out of the crate by hand, and then roll the robot down the wood r /> 3. Wait for the system to boot. - The Boxer's lights will go through a sequence of colors during this process: + The Boxer's lights will go through a sequence of colours during this process: - All white for approximately 30 seconds - All red for approximately 30 seconds diff --git a/docs/ros/config/live.mdx b/docs/ros/config/live.mdx index ff451284..b9b986a1 100644 --- a/docs/ros/config/live.mdx +++ b/docs/ros/config/live.mdx @@ -11,27 +11,33 @@ Users familiar with Clearpath's robots, know we provide desktop packages that fa This functionality requires a desktop manager to be installed; in other words, these commands will not work on robot computers since these run Ubuntu 22.04 server rather than desktop. # Installation + Install the desktop packages using `apt`. Make sure to have [added Clearpath packages](https://packages.clearpathrobotics.com/) to the source list before installation. + ```bash sudo apt install ros-humble-clearpath-desktop ros-humble-clearpath-config-live ``` # Setup + Before running the node, we will need to setup the working directory. First, create the directory `/etc/clearpath`. Then, copy your `robot.yaml` to `/etc/clearpath/robot.yaml`. # Run the Node + Running `view_model.launch.py` will generate the URDF of the robot from the `/etc/clearpath/robot.yaml` and then start RViz. It will then monitor the `/etc/clearpath/robot.yaml` for changes. Whenever changes are detected, the URDF will be regenerated and the RViz model will be updated. To run the node: + ```bash ros2 launch clearpath_viz view_model.launch.py ``` # Example + Starting off with the default A200 Husky YAML, we switch the top plate, add the sensor arch, a fath pivot mount, and finally a RealSense. Every time we want changes to take effect, we save the file. If after saving no changes take place, then it's an indication that these were invalid.
diff --git a/docs/ros/config/yaml.mdx b/docs/ros/config/yaml.mdx index 53849d99..7db900c8 100644 --- a/docs/ros/config/yaml.mdx +++ b/docs/ros/config/yaml.mdx @@ -131,7 +131,7 @@ sensors: camera: camera_name: camera_0 device_type: d435 - serial_no: '0' + serial_no: "0" enable_color: true rgb_camera.profile: 640,480,30 enable_depth: true @@ -267,8 +267,8 @@ There are three types of attachments: 1. **bumpers** modify the front face and rear face of the robot platform. 2. **fenders** modify the area above the wheels on the front and rear of the platform. -2. **top_plates** modify the top face of the robot platform. -3. **structures** are large custom parts that are added atop the top plate. +3. **top_plates** modify the top face of the robot platform. +4. **structures** are large custom parts that are added atop the top plate. #### Husky A200 {#attachments-a200} @@ -352,11 +352,13 @@ extras: ``` #### ROS Parameters + A common use case is to set and update the parameters to the `platform_velocity_controller` node. These can be used to modify the linear and angular velocity and acceleratation. These can be passed in as follows: **A200 Husky Controller Defaults:** + ```yaml platform: extras: @@ -373,8 +375,8 @@ platform: platform_velocity_controller.angular.z.min_acceleration": -6.0 ``` - **J100 Jackal Controller Defaults:** + ```yaml platform: extras: @@ -641,6 +643,7 @@ fath_pivot: ``` - **sick:** are mounts specifically designed to mount SICK LiDARs. The orientation of the LiDAR on the mount can be set to either `upright` or `inverted`. + ```yaml sick: - parent: base_link @@ -650,6 +653,7 @@ sick: ``` - **post:** are vertical extrusion rails to which sensors can be added. + ```yaml post: - parent: base_link @@ -661,6 +665,7 @@ post: ``` - **disk:** are circular plates which are used to mount circular sensors, i.e. the Velodyne + ```yaml disk: - parent: base_link @@ -813,6 +818,7 @@ gps: ``` - **_garmin_18x_** + ```yaml gps: - model: garmin_18x @@ -829,6 +835,7 @@ gps: ``` - **_novatel_smart6_** + ```yaml gps: - model: novatel_smart6 @@ -845,6 +852,7 @@ gps: ``` - **_novatel_smart7_** + ```yaml gps: - model: novatel_smart7 @@ -897,6 +905,7 @@ imu: ``` - **_redshift_um7:_** + ```yaml imu: - model: redshift_um7 @@ -1064,7 +1073,7 @@ camera: camera: camera_name: camera_0 device_type: d435 - serial_no: '0' + serial_no: "0" enable_color: true rgb_camera.profile: 640,480,30 enable_depth: true @@ -1097,7 +1106,7 @@ sensors: camera: camera_name: camera_0 device_type: d435 - serial_no: '0' + serial_no: "0" enable_color: true rgb_camera.profile: 640,480,30 enable_depth: true @@ -1136,7 +1145,6 @@ sensors: model: VLP16 fixed_frame: lidar3d_0_laser target_frame: lidar3d_0_laser - ```

diff --git a/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx b/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx index ec88247b..06ff0e3b 100644 --- a/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx +++ b/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx @@ -79,6 +79,14 @@ status, and whether the robot is dead reckoning.   **Description:** Result topic from the mission action. +#### /navigation/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** This output commanded velocity from the autonomy +software (OutdoorNav) to control the velocity of the platform. It is +commonly relayed directly into the UGV's velocity controller. + #### /navigation/distance_to_goal   **Message Type:** [clearpath_navigation_msgs/DistanceToGoal](definitions#msg-distance-to-goal) @@ -187,14 +195,6 @@ between the robot and the reference path) and as well as the heading error (ie. the difference between the current heading and the path direction). -#### /navigation/cmd_vel - -  **Message Type:** geometry_msgs/Twist - -  **Description:** This output commanded velocity from the autonomy -software (OutdoorNav) to control the velocity of the platform. It is -commonly relayed directly into the UGV's velocity controller. - #### /safety/safety_stop   **Message Type:** std_msgs/Bool @@ -326,6 +326,12 @@ The new dock will appear on the UI.   **Description:** Remove and existing dock from the database. Input to this service requires ether the UUID or the semantic name of the dock. +#### /dock/clear_data + +  **Service Type:** [std_srvs/srv/Trigger](definitions#srv-clear-dock-data) + +  **Description:** Remove all existing dock data from storage. + #### /dock/set_location/by_id   **Service Type:** [clearpath_dock_msgs/srv/SetDockLocationByID](definitions#srv-set-dock-location-by-id) @@ -351,12 +357,11 @@ localization according to the current sensor readings. If you are sending a mission to the UGV without using the UI and through the API, you must call this service before sending the mission. -#### /localization/set_pose (IN DEVELOPMENT) +#### /localization/reset -  **Service Type:** +  **Service Type:** [clearpath_localization_msgs/srv/ResetLocalization](definitions#srv-reset-localization) -  **Description:** This service can be used to reset or reinitialize the -localization of the UGV. +  **Description:** This service can be used to trigger a reset of the UGVs localization. #### /navigation/set_collision_avoidance diff --git a/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx b/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx index 3e5fa865..f060becf 100644 --- a/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx +++ b/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx @@ -1,7 +1,7 @@ --- title: Definitions sidebar_label: Definitions -sidebar_position: 5 +sidebar_position: 6 toc_min_heading_level: 2 toc_max_heading_level: 4 --- @@ -141,12 +141,32 @@ uint8 HEADING_RTK_FLOAT = 2 uint8 HEADING_RTK_FIXED = 3 uint8 heading_fix_type -uint8 num_connected_sats # Number of satellites connected to the antenna/receiver +uint8 num_connected_sats # Number of satellites connected to the antenna/receiver uint8 num_sats_solution # Number of sats used in solution -float32[] cn0 # The carrier-to-noise ratio of each connected satellite +float32[] cn0 # The carrier-to-noise ratio of each connected satellite float64 correction_age # Age of RTK corrections. -1 indicates none received ``` +#### clearpath_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} + +``` +# The entire contents of the Mission database +# Note that all of the following cases are valid: +# - a Task can be referenced in multiple Waypoints +# - a Waypoint can be referenced in multiple Missions +# - a Waypoint can be orphaned (i.e. not included in any Missions) +# - a Task can be orphaned (i.e. not included in any Waypoints) + +# All missions defined in the database +clearpath_navigation_msgs/Mission[] missions + +# All waypoints defined in the database +clearpath_navigation_msgs/Waypoint[] waypoints + +# All tasks defined in the database +clearpath_navigation_msgs/Task[] tasks +``` + #### clearpath_navigation_msgs/Mission.msg {#msg-navigation-mission} ``` @@ -154,23 +174,18 @@ float64 correction_age # Age of RTK corrections. -1 indicates none received std_msgs/Header header -# The goal's final waypoint -clearpath_navigation_msgs/Waypoint goalpoint - -# If a final heading is to be set for the goal, the following fields are required -bool enable_final_heading -float64 goalpoint_heading +# The human-readable name of this mission +string name -# If a goal tolerance is to be set for the goal, the following fields are required -bool enable_goal_tolerance -float64 position_tolerance -float64 yaw_tolerance +# A UUID string used to uniquely identify this mission +string uuid -# The intermediate waypoints on the way to the goal -clearpath_navigation_msgs/Waypoint[] viapoints +# The ordered list of Waypoints that make up the mission +clearpath_navigation_msgs/Waypoint[] waypoints -# The list of internal/external software calls that can be assigned to the goal. These will be called in the order that they are added to the list. -clearpath_navigation_msgs/Task[] tasks +# Configuration parameters for the mission +# Additional details TBD +string onav_config ``` #### clearpath_navigation_msgs/DistanceToGoal.msg {#msg-distance-to-goal} @@ -293,13 +308,26 @@ clearpath_navigation_msgs/PointVector[] cloud_vector #### clearpath_navigation_msgs/Task.msg {#msg-navigation-task} ``` -# Message definition for the tasks (ie. internal/external software calls) that can be assigned to an OutdoorNav mission. +# A single task that can be executed at a Waypoint +# The human-readable name of this task +string name -string task_name -string service_call +# A UUID string to uniquely identify this Task +string uuid + +# The ROS action that this task executes +string action_server_name + +# The version of this task string version + +# Numerical/boolean data to be passed to the action_server_name +# The exact meaning of these values is dependent on the underlying service float64[] floats + +# String data to be passed to the action_server_name +# The exact meaning of these values is dependent on the underlying service string[] strings ``` @@ -324,8 +352,33 @@ float32[2] point #### clearpath_navigation_msgs/Waypoints.msg {#msg-navigation-waypoints} ``` -float64 x -float64 y +# A single Waypoint along a Mission + +# A UUID string to uniquely identify this Waypoint +string uuid + +# The human-readable name of this Waypoint +string name + +# The latitude (in degrees) of this Waypoint +float64 latitude + +# The longitude (in degrees) of this Waypoint +float64 longitude + +# The compass heading (in degrees) of this Waypoint +float64 heading + +# A radius in meters indicating the acceptable radius from the target location +# Posititon tolerance is disabled if this value is negative +float64 position_tolerance + +# A tolerance in degrees indicating the acceptable deviation from the heading +# Heading tolerance is disabled if this value is negative +float64 yaw_tolerance + +# The ordered set of Tasks to execute once the goal position & orientation are reached +clearpath_navigation_msgs/Task[] tasks ``` #### clearpath_platform_msgs/PlatformID.msg {#msg-platform-id} @@ -349,101 +402,146 @@ bool[] lidar_watchdog_triggered bool[] camera_watchdog_triggered ``` -#### onav_ms2_msgs/msg/Mission.msg {#storage-mission} +#### cpr_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} ``` -# A mission containing one or more Waypoints, which may contain zero or more Tasks +# All missions defined in the database +cpr_navigation_msgs/Mission[] missions -# A UUID string used to uniquely identify this mission -string uuid +# All waypoints defined in the database +cpr_navigation_msgs/Waypoint[] waypoints -# The human-readable name of this mission -string name +# All tasks defined in the database +cpr_navigation_msgs/Task[] tasks +``` -# The ordered list of Waypoints that make up the mission -onav_ms2_msgs/Waypoint[] waypoints +#### cpr_mission_scheduler_msgs/msg/NextSchedule.msg -# Configuration parameters for the mission -# Currently unused, but planned for future development -string onav_config +``` +# The ID of the next schedule to start +# Empty if nothing is scheduled +string uuid + +# The time until the schedule starts (rounded to the nearest second) +duration time_to_start ``` -#### onav_ms2_msgs/msg/Task.msg {#storage-task} +#### cpr_mission_scheduler_msgs/msg/Schedule {#scheduler-schedule} ``` -# A single task that can be executed at a Waypoint +# Single-execution mode; the schedule starts at the designated time and runs once +uint8 MODE_ONCE=0 -# A UUID string to uniquely identify this Task -string uuid +# Looping mode; the schedule starts at the designated time, and every loop_interval seconds after +# for the designated number of repeats +uint8 MODE_LOOP=1 -# The human-readable name of this task +# Single-shot execution, but does NOT get added to the persistent storage +# Equivalent to MODE_ONCE, but for one-off, throw-away schedules (e.g. "Run X in 5 minutes") +uint8 MODE_TRANSIENT=2 + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so string name -# The ROS action that this task executes -string service_call +# The unique ID of this schedule +# A string of the form "12345678-90ab-cdef-1234-567890abcdef" +string uuid -# The version of this task -string version +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time -# Numerical/boolean data to be passed to the service_call -# The exact meaning of these values is dependent on the underlying service -float64[] floats +# Either MODE_ONCE or MODE_LOOP to indicate the execution mode +uint8 mode -# String data to be passed to the service_call -# The exact meaning of these values is dependent on the underlying service -string[] strings +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled ``` -#### onav_ms2_msgs/msg/Waypoint.msg {#storage-waypoint} +#### cpr_mission_scheduler_msgs/msg/StorageState.msg {#scheduler-state} ``` -# A single Waypoint along a Mission +# Single-execution mode; the schedule starts at the designated time and runs once +uint8 MODE_ONCE=0 -# A UUID string to uniquely identify this Waypoint -string uuid +# Looping mode; the schedule starts at the designated time, and every loop_interval seconds after +# for the designated number of repeats +uint8 MODE_LOOP=1 -# The human-readable name of this Waypoint +# Single-shot execution, but does NOT get added to the persistent storage +# Equivalent to MODE_ONCE, but for one-off, throw-away schedules (e.g. "Run X in 5 minutes") +uint8 MODE_TRANSIENT=2 + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so string name -# The latitude (in degrees) of this Waypoint -float64 latitude +# The unique ID of this schedule +# A string of the form "12345678-90ab-cdef-1234-567890abcdef" +string uuid -# The longitude (in degrees) of this Waypoint -float64 longitude +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time -# The compass heading (in degrees) of this Waypoint -float64 heading +# Either MODE_ONCE or MODE_LOOP to indicate the execution mode +uint8 mode -# A radius in meters indicating the acceptable radius from the target location -# Posititon tolerance is disabled if this value is negative -float64 position_tolerance +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats -# A tolerance in degrees indicating the acceptable deviation from the heading -# Heading tolerance is disabled if this value is negative -float64 yaw_tolerance +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval -# The ordered set of Tasks to execute once the goal position & orientation are reached -onav_ms2_msgs/Task[] tasks +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled ``` -#### onav_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} +#### cpr_mission_scheduler_msgs/msg/UtcTime.msg {#scheduler-time} ``` -# The entire contents of the Mission database -# Note that all of the following cases are valid: -# - a Task can be referenced in multiple Waypoints -# - a Waypoint can be referenced in multiple Missions -# - a Waypoint can be orphaned (i.e. not included in any Missions) -# - a Task can be orphaned (i.e. not included in any Waypoints) +# Represents a moment in time on a 24-hour clock -# All missions defined in the database -onav_ms2_msgs/Mission[] missions +# The hour, 0-23 +uint8 hour -# All waypoints defined in the database -onav_ms2_msgs/Waypoint[] waypoints +# The minute, 0-59 +uint8 minute -# All tasks defined in the database -onav_ms2_msgs/Task[] tasks +# The second, 0-59 +uint8 second + +# Milliseconds, 0-999 (not typically needed) +uint16 millisecond ``` #### Standard ROS Messages {#std-ros-msgs} @@ -505,7 +603,7 @@ bool success ``` # The UUID of the dock we're setting a location for -# If empty, a new dock is to be added with the location +# If empty, a new dock is to be added with the location string uuid --- # True if the location was updated/added successfully, otherwise False @@ -516,7 +614,7 @@ bool success ``` # The UUID of the dock we're setting a location for -# If empty, a new dock is to be added with the location +# If empty, a new dock is to be added with the location string name --- # True if the location was updated/added successfully, otherwise False @@ -534,57 +632,19 @@ float32 lon bool success ``` -#### clearpath_navigation_msgs/srv/SetDelayCompensation.srv {#srv-set-delay-compensation} - -``` -# Service definition to enable/disable the delay compensation feature. If enabling, the delay to compensate for must be specified in the request. - -bool enable_delay_compensation -uint16 delay ---- -bool success -string message -``` - -#### clearpath_navigation_msgs/srv/SetPathSmoother.srv {#srv-set-path-smoother} - -``` -# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. - -bool enable_path_smoother -float32 turn_radius -float32 step_size ---- -bool success -string message -``` - -#### clearpath_navigation_msgs/srv/SetPathShifter.srv {#srv-set-path-shifter} +#### clearpath_localization_msgs/srv/ResetLocalization.srv {#srv-reset-localization} ``` -# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. +# Service definition to reset the localization -bool enable_path_shifter -float32 path_shift_offset -float32 path_shift_time +bool require_gnss +uint32 gnss_samples --- bool success -string message -``` - -#### clearpath_navigation_msgs/srv/SetStopDistance.srv {#srv-set-stop-distance} - ``` -# Service definition to enable/disable the stop distance. If enabling, the stop distance must be specified in the request. -bool enable_stop_distance -float32 stop_distance ---- -bool success -string message -``` -#### onav_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} +#### clearpath_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} ``` # The UUID of the object we're inserting/removing @@ -602,40 +662,40 @@ int32 position bool ok ``` -#### onav_mission_manager_msgs/srv/CloneMission.srv {#storage-clonemission} +#### clearpath_mission_manager_msgs/srv/CloneMission.srv {#storage-clonemission} ``` # The desired name for the new mission string name # The additional configuration options -# see onav_ms2_msgs/msg/Mission for details +# see clearpath_navigation_msgs/msg/Mission for details string onav_config # The ordered list of Waypoint UUIDs to include in this mission string[] waypoint_ids --- # The resulting Mission, with an auto-generated UUID is returned -onav_ms2_msgs/Mission result +clearpath_navigation_msgs/Mission result ``` -#### onav_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} +#### clearpath_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} ``` # The desired name for the new mission string name # The additional configuration options -# see onav_mission_manager_msgs/msg/Mission for details +# see clearpath_mission_manager_msgs/msg/Mission for details string onav_config # The ordered list of Waypoint UUIDs to include in this mission string[] waypoint_ids --- # The resulting Mission, with an auto-generated UUID is returned -onav_ms2_msgs/Mission result +clearpath_navigation_msgs/Mission result ``` -#### onav_mission_manager_msgs/srv/CreateTask.srv {#storage-createtask} +#### clearpath_mission_manager_msgs/srv/CreateTask.srv {#storage-createtask} ``` # The desired name for the Task @@ -658,10 +718,10 @@ string[] strings string[] assign_to --- # The resulting Task with an auto-generated UUID is returned -onav_ms2_msgs/Task result +clearpath_navigation_msgs/Task result ``` -#### onav_mission_manager_msgs/srv/CreateWaypoint.srv {#storage-createwaypoint} +#### clearpath_mission_manager_msgs/srv/CreateWaypoint.srv {#storage-createwaypoint} ``` # The desired name for the Waypoint @@ -690,10 +750,10 @@ string[] task_ids string[] assign_to --- # The resulting Waypoint with an auto-generated UUID is returned -onav_ms2_msgs/Waypoint result +clearpath_navigation_msgs/Waypoint result ``` -#### onav_mission_manager_msgs/srv/DeleteById.srv {#storage-deletebyid} +#### clearpath_mission_manager_msgs/srv/DeleteById.srv {#storage-deletebyid} ``` # The UUID of the object we want to delete @@ -703,7 +763,7 @@ string uuid bool ok ``` -#### onav_mission_manager_msgs/srv/DeleteEverything.srv {#storage-deleteeverything} +#### clearpath_mission_manager_msgs/srv/DeleteEverything.srv {#storage-deleteeverything} ``` # Used to permanently delete everything from the database. @@ -716,7 +776,7 @@ bool yes_i_am_absolutely_sure_i_want_to_do_this bool ok ``` -#### onav_mission_manager_msgs/srv/ExportData.srv {#storage-exportdata} +#### clearpath_mission_manager_msgs/srv/ExportData.srv {#storage-exportdata} ``` --- @@ -728,69 +788,69 @@ bool ok string data ``` -#### onav_mission_manager_msgs/srv/GetAllMissions.srv {#storage-getallmissions} +#### clearpath_mission_manager_msgs/srv/GetAllMissions.srv {#storage-getallmissions} ``` --- # An array of all Missions defined in the database -onav_ms2_msgs/Mission[] missions +clearpath_navigation_msgs/Mission[] missions ``` -#### onav_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} +#### clearpath_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} ``` --- # The array of all Tasks defined in the database -onav_ms2_msgs/Task[] tasks +clearpath_navigation_msgs/Task[] tasks ``` -#### onav_mission_manager_msgs/srv/GetAllWaypoints.srv {#storage-getallwaypoints} +#### clearpath_mission_manager_msgs/srv/GetAllWaypoints.srv {#storage-getallwaypoints} ``` --- # The array of all Waypoints defined in the database -onav_ms2_msgs/Waypoint[] waypoints +clearpath_navigation_msgs/Waypoint[] waypoints ``` -#### onav_mission_manager_msgs/srv/GetEverything.srv {#storage-geteverything} +#### clearpath_mission_manager_msgs/srv/GetEverything.srv {#storage-geteverything} ``` --- # All Missions, Waypoints, and Tasks defined in the database -onav_mission_manager_msgs/StorageState state +clearpath_mission_manager_msgs/StorageState state ``` -#### onav_mission_manager_msgs/srv/GetMission.srv {#storage-getmission} +#### clearpath_mission_manager_msgs/srv/GetMission.srv {#storage-getmission} ``` # The UUID of the Mission we want to retrieve string uuid --- # The Mission with the given ID, or null if no Mission with that ID exists -onav_ms2_msgs/Mission mission +clearpath_navigation_msgs/Mission mission ``` -#### onav_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} +#### clearpath_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} ``` # The UUID of the Task we want to retrieve string uuid --- # The Task with the given ID, or null if no Task with that ID exists -onav_ms2_msgs/Task task +clearpath_navigation_msgs/Task task ``` -#### onav_mission_manager_msgs/srv/GetWaypoint.srv {#storage-getwaypoint} +#### clearpath_mission_manager_msgs/srv/GetWaypoint.srv {#storage-getwaypoint} ``` # The UUID of the Waypoint we want to retrieve string uuid --- # The Waypoint with the given ID, or null if no Waypoint with that ID exists -onav_ms2_msgs/Waypoint waypoint +clearpath_navigation_msgs/Waypoint waypoint ``` -#### onav_mission_manager_msgs/srv/ImportData.srv {#storage-importdata} +#### clearpath_mission_manager_msgs/srv/ImportData.srv {#storage-importdata} ``` # A base-64 encoded string representing a compressed version of @@ -801,10 +861,10 @@ onav_ms2_msgs/Waypoint waypoint string data --- # The state of the database after importing the data -onav_mission_manager_msgs/StorageState state +clearpath_mission_manager_msgs/StorageState state ``` -#### onav_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} +#### clearpath_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} ``` # The UUID of the mission we want to edit @@ -820,10 +880,10 @@ string onav_config string[] waypoint_ids --- # The edited Mission, or null if no mission with the given ID exists -onav_ms2_msgs/Mission result +clearpath_navigation_msgs/Mission result ``` -#### onav_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} +#### clearpath_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} ``` # The UUID of the Task to edit @@ -845,10 +905,10 @@ float64[] floats string[] strings --- # The edited Task, or null if no Task with the given ID exists -onav_ms2_msgs/Task result +clearpath_navigation_msgs/Task result ``` -#### onav_mission_manager_msgs/srv/UpdateWaypoint.srv {#storage-updatewaypoint} +#### clearpath_mission_manager_msgs/srv/UpdateWaypoint.srv {#storage-updatewaypoint} ``` # The UUID of the Waypoint to edit @@ -876,93 +936,610 @@ float64 yaw_tolerance string[] task_ids --- # The edited Waypoint, or null if no Waypoint with the given ID exists -onav_ms2_msgs/Waypoint result +clearpath_navigation_msgs/Waypoint result ``` -#### Standard ROS Services - -- [std_srvs/Empty](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/Empty.html) -- [std_srvs/SetBool](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/SetBool.html) - ------------------------------------------------------------------------- - -### Action Definitions - -#### clearpath_dock_msgs/action/Dock.action {#action-dock} +#### clearpath_navigation_msgs/srv/SetDelayCompensation.srv {#srv-set-delay-compensation} ``` -# Action definition for sending a Clearpath UGV to one of its charging dock. +# Service definition to enable/disable the delay compensation feature. If enabling, the delay to compensate for must be specified in the request. -# goal -string uuid -bool local_mode +bool enable_delay_compensation +uint16 delay --- -# result bool success ---- -# feedback -string state - -# the distance of the charger_link to the dock target -float64 distance_to_dock +string message ``` -#### clearpath_dock_msgs/action/Undock.action {#action-undock} +#### clearpath_navigation_msgs/srv/SetPathSmoother.srv {#srv-set-path-smoother} ``` -# Action definition for undocking a Clearpath UGV from one of its charging docks. +# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. -# goal -string uuid +bool enable_path_smoother +float32 turn_radius +float32 step_size --- -# result bool success ---- -# feedback -string state - -# the distance of the charger_link to the dock target -float64 distance_to_dock +string message ``` -#### clearpath_localization_msgs/action/SurveyBaseStation.action {#action-survey-base-station} +#### clearpath_navigation_msgs/srv/SetPathShifter.srv {#srv-set-path-shifter} ``` -# Action definition for surveying the base station +# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. -# goal -# the number of GPS fixes that will be used to compute to surveyed position -uint32 number_of_desired_fixes +bool enable_path_shifter +float32 path_shift_offset +float32 path_shift_time --- -# result bool success ---- -# feedback -# current progress, as a percentage, of the surveying -float32 percent_complete +string message ``` -#### clearpath_navigation_msgs/action/Mission.action {#action-mission} +#### clearpath_navigation_msgs/srv/SetStopDistance.srv {#srv-set-stop-distance} ``` -# Action definition for sending a mission to the Clearpath OutdoorNav software +# Service definition to enable/disable the stop distance. If enabling, the stop distance must be specified in the request. -# goal -clearpath_navigation_msgs/Mission mission +bool enable_stop_distance +float32 stop_distance --- -# result bool success ---- -# feedback -string state +string message ``` -#### clearpath_dock_msgs/action/Dock.action {#action-dock} +#### cpr_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} ``` -# Action definition for sending a Clearpath UGV to its charging dock. - -# goal +# The UUID of the object we're inserting/removing +# When removing, all instances with this UUID are deleted from the parent +string uuid + +# The UUID of the parent object +string parent_uuid + +# The zero-based index to insert the object into +# Ignored when removing +int32 position +--- +# True if the object was added/removed successfully, otherwise False +bool ok +``` + +#### cpr_mission_manager_msgs/srv/CloneMission.srv {#storage-clonemission} +``` +# The UUID of the mission to clone +string uuid + +# The new name for the mission +# If blank, the old mission name will be re-used with -copy appended to the end +string new_name + +# If true, the order of the waypoints within the cloned mission are reversed +bool reverse +--- +# The Mission with the given ID, or null if no Mission with that ID exists +cpr_navigation_msgs/Mission mission +``` + +:::note + +The `reverse` parameter was added in 0.9.0 + +::: + +#### cpr_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} + +``` +# The desired name for the new mission +string name + +# The additional configuration options +# see cpr_mission_manager_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids +--- +# The resulting Mission, with an auto-generated UUID is returned +cpr_navigation_msgs/Mission result +``` + +#### cpr_mission_manager_msgs/srv/CreateTask.srv {#storage-createtask} + +``` +# The desired name for the Task +string name + +# The ROS Action to invoke to execute the task +string service_call + +# The version of the task +string version + +# The numerical arguments to pass to the service_call +float64[] floats + +# The string arguments to pass to the service_call +string[] strings + +# Optional list of Waypoint UUIDs to assign this task to automatically +# The new task will be appended to the end of the existing Waypoints +string[] assign_to +--- +# The resulting Task with an auto-generated UUID is returned +cpr_navigation_msgs/Task result +``` + +#### cpr_mission_manager_msgs/srv/CreateWaypoint.srv {#storage-createwaypoint} + +``` +# The desired name for the Waypoint +string name + +# The latitude for the Waypoint in degrees +float64 latitude + +# The longitude for the Waypoint in degrees +float64 longitude + +# The compass heading in degrees for the Waypoint +float64 heading + +# The position tolerance for the Waypoint in meters +float64 position_tolerance + +# The orientation tolerance for the Waypoint in degrees +float64 yaw_tolerance + +# Optional ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids + +# Optional list of Mission UUIDs to assign the new Waypoint to +# The new Waypoint is appended to the end of the existing Missions +string[] assign_to +--- +# The resulting Waypoint with an auto-generated UUID is returned +cpr_navigation_msgs/Waypoint result +``` + +#### cpr_mission_manager_msgs/srv/DeleteById.srv {#storage-deletebyid} + +``` +# The UUID of the object we want to delete +string uuid +--- +# True if the item was successfully deleted, otherwise False +bool ok +``` + +#### cpr_mission_manager_msgs/srv/DeleteEverything.srv {#storage-deleteeverything} + +``` +# Used to permanently delete everything from the database. +# Use this service at your own risk + +# This must be set to true to confirm you really want to delete everything +bool yes_i_am_absolutely_sure_i_want_to_do_this +--- +# True if the database was cleared, otherwise False +bool ok +``` + +#### cpr_mission_manager_msgs/srv/ExportData.srv {#storage-exportdata} + +``` +--- +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### cpr_mission_manager_msgs/srv/GetAllMissions.srv {#storage-getallmissions} + +``` +--- +# An array of all Missions defined in the database +cpr_navigation_msgs/Mission[] missions +``` + +#### cpr_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} + +``` +--- +# The array of all Tasks defined in the database +cpr_navigation_msgs/Task[] tasks +``` + +#### cpr_mission_manager_msgs/srv/GetAllWaypoints.srv {#storage-getallwaypoints} + +``` +--- +# The array of all Waypoints defined in the database +cpr_navigation_msgs/Waypoint[] waypoints +``` + +#### cpr_mission_manager_msgs/srv/GetEverything.srv {#storage-geteverything} + +``` +--- +# All Missions, Waypoints, and Tasks defined in the database +cpr_mission_manager_msgs/StorageState state +``` + +#### cpr_mission_manager_msgs/srv/GetMission.srv {#storage-getmission} + +``` +# The UUID of the Mission we want to retrieve +string uuid +--- +# The Mission with the given ID, or null if no Mission with that ID exists +cpr_navigation_msgs/Mission mission +``` + +#### cpr_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} + +``` +# The UUID of the Task we want to retrieve +string uuid +--- +# The Task with the given ID, or null if no Task with that ID exists +cpr_navigation_msgs/Task task +``` + +#### cpr_mission_manager_msgs/srv/GetWaypoint.srv {#storage-getwaypoint} + +``` +# The UUID of the Waypoint we want to retrieve +string uuid +--- +# The Waypoint with the given ID, or null if no Waypoint with that ID exists +cpr_navigation_msgs/Waypoint waypoint +``` + +#### cpr_mission_manager_msgs/srv/ImportData.srv {#storage-importdata} + +``` +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +cpr_mission_manager_msgs/StorageState state +``` + +#### cpr_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} + +``` +# The UUID of the mission we want to edit +string uuid + +# The human-readable name for the Mission +string name + +# The configuration parameters for the Mission +string onav_config + +# The ordered list of Waypoint UUIDs to include in the Mission +string[] waypoint_ids +--- +# The edited Mission, or null if no mission with the given ID exists +cpr_navigation_msgs/Mission result +``` + +#### cpr_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} + +``` +# The UUID of the Task to edit +string uuid + +# The human-readable name for the Task +string name + +# The ROS Action that the Task executes +string service_call + +# The version of the Task +string version + +# The numerical data to pass to the service_call +float64[] floats + +# The string data to pass to the service_call +string[] strings +--- +# The edited Task, or null if no Task with the given ID exists +cpr_navigation_msgs/Task result +``` + +#### cpr_mission_manager_msgs/srv/UpdateWaypoint.srv {#storage-updatewaypoint} + +``` +# The UUID of the Waypoint to edit +string uuid + +# The human-readable name for the Waypoint +string name + +# The latitude of the Waypoint in degrees +float64 latitude + +# The longitude of the Waypoint in degrees +float64 longitude + +# The compass heading of the Waypoint in degrees +float64 heading + +# The Waypoint's position tolerance in meters +float64 position_tolerance + +# The Waypoint's orientation tolerance in degrees +float64 yaw_tolerance + +# The ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids +--- +# The edited Waypoint, or null if no Waypoint with the given ID exists +cpr_navigation_msgs/Waypoint result +``` + +#### cpr_mission_scheduler_msgs/srv/CloneSchedule.srv {#scheduler-cloneschedule} + +``` +# The UUID of the schedule to clone +string uuid + +# The name for the new copy of the schedule +string new_name +--- +# The cloned schedule +# This should be identical to the original, but with a new name and new UUID +cpr_mission_scheduler_msgs/Schedule schedule +``` + +#### cpr_mission_scheduler_msgs/srv/CreateSchedule.srv {#scheduler-createschedule} + +``` +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time + +# Either Schedule.MODE_ONCE, Schedule.MODE_LOOP, OR Schedule.MODE_TRANSIENT to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled + +--- + +# The created mission, as-saved on disk +cpr_mission_scheduler_msgs/Schedule result +``` + +#### cpr_mission_scheduler_msgs/srv/EnableSchedule.srv {#scheduler-enableschedule} + +``` +# The ID of the schedule to enable/disable +string uuid + +# Should this schedule be enabled or disabled? +bool enable + +--- + +# True if we successfully enabled/disabled the schedule +# False if there was an error or the schedule wasn't found +bool ok +``` + +#### cpr_mission_scheduler_msgs/srv/ExportData.srv {#scheduler-exportdata} + +``` +--- +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### cpr_mission_scheduler_msgs/srv/GetAllSchedules.srv {#scheduler-getallschedules} + +``` +--- +cpr_mission_scheduler_msgs/Schedule[] schedules +``` + +#### cpr_mission_scheduler_msgs/srv/GetNextSchedule.srv {#scheduler-getnextschedule} + +``` +--- +# The ID of the next schedule to start +# Empty if nothing is scheduled +string uuid + +# The time until the schedule starts (rounded to the nearest second) +duration time_to_start +``` + +#### cpr_mission_scheduler_msgs/srv/GetSchedule.srv {#scheduler-getschedule} + +``` +string uuid +--- +cpr_mission_scheduler_msgs/Schedule schedule +``` + +#### cpr_mission_scheduler_msgs/srv/ImportData.srv {#scheduler-importdata} + +``` +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +cpr_mission_scheduler_msgs/StorageState state +``` + +#### cpr_mission_scheduler_msgs/srv/UpdateSchedule.srv {scheduler-updateschedule} + +``` +# The ID of the mission to edit +string uuid + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time + +# Either Schedule.MODE_ONCE, Schedule.MODE_LOOP, OR Schedule.MODE_TRANSIENT to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled + +--- + +# The modified mission, as-saved on disk +cpr_mission_scheduler_msgs/Schedule result +``` + +#### Standard ROS Services + +- [std_srvs/Empty](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/Empty.html) +- [std_srvs/SetBool](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/SetBool.html) + +------------------------------------------------------------------------ + +### Action Definitions + +#### clearpath_dock_msgs/action/Dock.action {#action-dock} + +``` +# Action definition for sending a Clearpath UGV to one of its charging dock. + +# goal +string uuid +bool local_mode +--- +# result +bool success +--- +# feedback +string state + +# the distance of the charger_link to the dock target +float64 distance_to_dock +``` + +#### clearpath_dock_msgs/action/Undock.action {#action-undock} + +``` +# Action definition for undocking a Clearpath UGV from one of its charging docks. + +# goal +string uuid +--- +# result +bool success +--- +# feedback +string state + +# the distance of the charger_link to the dock target +float64 distance_to_dock +``` + +#### clearpath_localization_msgs/action/SurveyBaseStation.action {#action-survey-base-station} + +``` +# Action definition for surveying the base station + +# goal +# the number of GPS fixes that will be used to compute to surveyed position +uint32 number_of_desired_fixes +--- +# result +bool success +--- +# feedback +# current progress, as a percentage, of the surveying +float32 percent_complete +``` + +#### clearpath_navigation_msgs/action/Mission.action {#action-mission} + +``` +# Action definition for sending a mission to the Clearpath OutdoorNav software + +# goal +clearpath_navigation_msgs/Mission mission +--- +# result +bool success +--- +# feedback +string state +``` + +#### clearpath_dock_msgs/action/Dock.action {#action-dock} + +``` +# Action definition for sending a Clearpath UGV to its charging dock. + +# goal uint8 DOCK = 0 uint8 UNDOCK = 1 float32 type @@ -975,3 +1552,25 @@ bool success string state float64 dist_to_dock # (IN DEVELOPMENT) ``` + +#### cpr_mission_scheduler_msgs/action/RunScheduleByUuid.action {#scheduler-runschedulebyuuid} + +``` +# Action definition for executing a schedule on-demand +# Potentially only useful for debugging + +# The UUID of the schedule to execute +string uuid + +# Wait this long before starting the schedule +duration delay +--- +# Did the schedule terminate successfully? +bool success +--- +# The ID of the mission we're executing right now +string current_mission_uuid + +# One of "waiting" or "executing" indicating what the schedule is doing +string state +``` diff --git a/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx b/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx index 6b9d3683..3b220d50 100644 --- a/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx +++ b/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx @@ -40,7 +40,7 @@ is added to the end of the Task's `waypoints` list. **Description:** Create a deep-copy of a Mission. The new Mission will be given the provided name, or reuse the original mission's name wth `-copy` appended to the end if no name is provided. All Waypoints and their associated Tasks are also -duplicated but not renamed. +deep-copied. If the `reverse` parameter is set to `true` the order of waypoints is reversed in the new mission. :::note @@ -50,6 +50,12 @@ fail. Cloning a mission multiple times without specifying a unique name will add ::: +:::note + +The `reverse` parameter was added in 0.9.0 and is not available in older versions. + +::: + #### mission_manager/clone_task **Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions#storage-gettask) diff --git a/docs_outdoornav_user_manual/api/api_endpoints/mission_scheduler_api.mdx b/docs_outdoornav_user_manual/api/api_endpoints/mission_scheduler_api.mdx new file mode 100644 index 00000000..606e3a1c --- /dev/null +++ b/docs_outdoornav_user_manual/api/api_endpoints/mission_scheduler_api.mdx @@ -0,0 +1,199 @@ +--- +title: Mission Scheduler API +sidebar_label: Mission Scheduler API +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Mission Scheduler API provides a ROS interface for creating, deleting, editing, and executing missions on a daily +schedule. Schedules are stored in a database-like structure on-disk, and can be executed manually or automatically. + +The web UI is the primary method of creating and modifying schedules, though the ROS API is available should you wish +to write your own interface or create automation tools to interact with the scheduler. + +## The Schedule Object + +A schedule consists of one or more missions to be executed in the specified order at a particular start time. For +consistency the start time is expressed as a 24-hour time in UTC. + +The schedule must be in one of 3 modes: +- `MODE_ONCE` -- the mission is executed exactly once per day, at the indicted UTC time +- `MODE_LOOP` -- the mission is executed a set number of times per day, starting at the indicated UTC time and repeating + at fixed intervals until the desired number of repetitions is reached +- `MODE_TRANSIENT` -- the mission is run exactly once, and is not saved to the persistent storage. This is intended to + be used for deferred execution of a mission (e.g. `execute mission X in 5 minutes` would use a transient schedule) + +Deleting a mission from the Mission Manager will result in that mission being automatically removed from any schedules +it was part of. If a schedule has no missions it is automatically disabled, and cannot be re-enabled until it contains +at least one mission. + +### A Note on Schedule Timing + +Automatically-scheduled missions are executed at the provided time +/- 10 seconds. The duration provided by the +`next_schedule` topic and `get_next_schedule` service is therefore approximate. We recommend rounding the time to the +nearest minute when displaying the countdown information to the user in any sort of GUI. + +## Topics Exported by Mission Scheduler + +### mission_scheduler/next_schedule + +**Message Type:** [cpr_mission_scheduler_msgs/msg/NextSchedule](definitions#scheduler-nextschedule) + +**Description:** Publishes the UUID and duration to the next scheduled mission. If no missions are scheduled the UUID +will be blank. + +**Update Rate:** 1Hz + +### mission_scheduler/state + +**Message Type:** [cpr_mission_scheduler_msgs/msg/StorageState](definitions#scheduler-state) + +**Description:** Publishes the current state of the database. Anything that needs to display the current set of +schedules should subscribe to this topic + +**Update Rate:** Latched, publishes on state-change only + +## Services Exported by Mission Scheduler + +### mission_scheduler/add_mission + +**Service Type:** [cpr_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Add a mission to an existing schedule. + +### mission_scheduler/clone_schedule + +**Service Type:** [cpr_mission_scheduler_msgs/srv/CloneSchedule](definitions#scheduler-cloneschedule) + +**Description:** Perform a deep-copy of an existing schedule + +### mission_scheduler/create_schedule + +**Service Type:** [cpr_mission_scheduler_msgs/srv/CreateSchedule](definitions#scheduler-createschedule) + +**Description:** Create a new schedule + +### mission_scheduler/delete_all_schedules + +**Service Type:** [cpr_mission_manager_msgs/srv/DeleteEverything](definitions#storage-deleteeverything) + +**Description:** Delete all schedules. + +:::note + +This action is permanent and cannot be undone. Use with caution. + +::: + +### mission_scheduler/delete_schedule + +**Service Type:** [cpr_mission_manager_msgs/srv/DeleteById](definitions#storage-deletebyid) + +**Description:** Delete a single schedule. + +:::note + +This action is permanent and cannot be undone. Use with caution. + +::: + +### mission_scheduler/enable_schedule + +**Service Type:** [mission_scheduler/srv/UpdateSchedule](definitions#scheduler-enablechedule) + +**Description:** Enable or disable a schedule. + +:::note + +Disabled schedules can still be run manually with the `run_now` action (see below). Disabled schedules will never +be run automatically. + +::: + +### mission_scheduler/export + +**Service Type:** [cpr_mission_scheduler_msgs/srv/ExportData](definitions#scheduler-exportdata) + +**Description:** Export all schedule data to a base64 string to it can be backed-up or copied to another robot. + +:::note + +This service is intended to be used in combination with the `import_data` service to facilitate backups or +synchronizing schedules across multiple robots. + +::: + +### mission_scheduler/get_all_schedules + +**Service Type:** [mission_scheduler/srv/GetAllSchedules](definitions#scheduler-getallschedules) + +**Description:** Get the list of all schedules. The list will include enabled, disabled, and transient schedules. + +### mission_scheduler/get_next_schedule + +**Service Type:** [mission_scheduler/srv/GetNextSchedule](definitions#scheduler-getnextschedule) + +**Description:** Get the UUID of the next schedule that will be run automatically. If nothing is scheduled (e.g. because +there are no enabled schedules) the UUID will be blank. + +:::note + +The duration is the approximate time left before the schedule will be started automatically. Schedules will start at +their designated start time +/- 10 seconds. + +::: + +### mission_scheduler/get_schedule + +**Service Type:** [mission_scheduler/srv/GetSchedule](definitions#scheduler-getschedule) + +**Description:** Get the schedule with the provided UUID. If an error occurred, or no schedule with the provided UUID +exists, the returned object will have a blank UUID. + +### mission_scheduler/import + +**Service Type:** [cpr_mission_scheduler_msgs/srv/ImportData](definitions#scheduler-importdata) + +**Description:** Import data exported by the `export_data` service. This will delete all schedules and replace the +database contents with the imported data. + +:::note + +This service is intended to be used in combination with the `export_data` service to facilitate backups or +synchronizing schedules across multiple robots. + +::: + +### mission_scheduler/remove_mission + +**Service Type:** [cpr_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Remove the mission at a given position from a schedule, or remove all copies of a mission from a +schedule + +### mission_scheduler/update_schedule + +**Service Type:** [mission_scheduler/srv/UpdateSchedule](definitions#scheduler-updateschedule) + +**Description:** Modify an existing schedule. All of the schedule's properties are overwritten with the new values +provided in the service call. + +:::note + +Before modifying a schedule it is recommended to call the `get_schedule` service to get the schedule's current state, +copy all values to the service request object, and then change the fields you want to overwrite. + +::: + +## Actions Exported by Mission Scheduler + +### mission_scheduler/run_now + +**Action Type:** [cpr_mission_scheduler_msgs/action/RunScheduleByUuid](definitions#scheduler-runschedulebyuuid) + +**Description:** Execute the schedule with the given UUID. The `delay` parameter will defer the execution by the +specified time. This action can be used to run a disabled schedule, or run a schedule at a time other than its +scheduled start time. + +**Feedback Rate:** 1Hz diff --git a/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx b/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx new file mode 100644 index 00000000..e123509b --- /dev/null +++ b/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx @@ -0,0 +1,18 @@ +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +The API Examples section is currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + diff --git a/docs_outdoornav_user_manual/api/api_examples/mission_from_file.mdx b/docs_outdoornav_user_manual/api/api_examples/mission_from_file.mdx new file mode 100644 index 00000000..2c80b317 --- /dev/null +++ b/docs_outdoornav_user_manual/api/api_examples/mission_from_file.mdx @@ -0,0 +1,220 @@ +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +API examples are currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + +## The Code + +``` python +#! /usr/bin/env python3 + +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.yaml_config import YamlConfig +import time +import os + +# The file containing the mission configuration (adjust as needed) +MISSION_YAML_FILE = os.environ.get("HOME", "administrator") + "/example_ws/src/" + \ + "CPR-OutdoorNav/src/cpr_outdoornav_api_examples/config/sample_mission.yaml" + +class MissionFromYamlFile(RosNode): + """ + Create and run a mission loaded from a YAML configuration file. + Be sure that your robot is within 3 meters of your first Waypoint prior to starting the mission. + """ + + def __init__(self): + """Initialize the mission details and server connection.""" + + RosNode.__init__(self, 'mission_from_yaml_file') + self.mission = YamlConfig.yamlFileToMission(MISSION_YAML_FILE) + + # NOTE: to save the configuration to file, uncomment the following lines: + # YamlConfig.missionToYamlFile('/tmp/test1.yaml', self.mission) + + def run(self): + """Execute the mission.""" + + if not self.mission.startMission(): + return False + while not self.mission.isMissionComplete(): + time.sleep(1.0) + return self.mission.getMissionSuccess() + + +if __name__ == '__main__': + if MissionFromYamlFile().run(): + print("Mission completed successfully") + else: + print("Mission failed") + +``` + +## The Code Explained + +Let's break down the code. + +``` python +#! /usr/bin/env python3 +``` + +Every Python ROS Node will have this declaration at the top. The first line makes sure your script is executed as a Python3 script. + + +``` python +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.yaml_config import YamlConfig +``` + +We provide a library of classes that can be used within your file for ease of use. In the above example, we import the RosNode and YamlConfig classes. +The RosNode class is used by all of our examples to initialize a ROS node that will execute the example mission. The YamlConfig class is used to import +a YAML file and convert it to a Mission object. + +``` python +MISSION_YAML_FILE = os.environ.get("HOME", "administrator") + "/example_ws/src/" + \ + "CPR-OutdoorNav/src/cpr_outdoornav_api_examples/config/sample_mission.yaml" +``` + +This defines the file path of the YAML file that contains the mission to be executed. See the [YAML file](#yaml-file) below for the example YAML file +that will be executed. + +``` python +class MissionFromYamlFile(RosNode): +``` + +Creates a class for your example, which inherits a RosNode object. All python mission files are requried to inherit the RosNode class. + +``` python + RosNode.__init__(self, 'mission_from_yaml_file') + self.mission = YamlConfig.yamlFileToMission(MISSION_YAML_FILE)``` +``` + +Initialize the ROS node with name `mission_from_yaml_file` and import the the mission from the yaml config file. The `YamlConfig.yamlFileToMission()` function +reads teh configuration you have created in the YAML file and converts it into a Mission object. + +``` python + if not self.mission.startMission(): + return False +``` + +Upon execution of the script, the `self.mission.startMission()` function creates the mission client if not yet created, connects to the mission action server +and sends the goal to the action server to begin the execution of the mission. + +``` python + while not self.mission.isMissionComplete(): + time.sleep(1.0) + return self.mission.getMissionSuccess() +``` + +`self.mission.isMissionComplete()` monitors the mission status and only proceeds to terminating the mission has completed or been cancelled. + + +## YAML File {#yaml-file} + +The following YAML file is used in the above example mission. + +``` python +mission: + header: + seq: 0 + stamp: + secs: 0 + nsecs: 0 + frame_id: '' + name: "Sample Mission" + uuid: "8f57fd20-8a8c-4748-85ef-be1495b3ee06" + waypoints: + - + name: "Waypoint: 60" + uuid: "3edcedd7-ae0d-47cf-bd23-f7988d2779b7" + latitude: 50.10950820165676 + longitude: -97.31898507913323 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 61" + uuid: "ad23202e-7067-4f1c-8677-2dc07af1e729" + latitude: 50.1095698924641 + longitude: -97.31929487427445 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 62" + uuid: "fe452e77-4a26-41b0-b4ab-ee1859612a60" + latitude: 50.109437123117864 + longitude: -97.31946787675591 + heading: -1.0 + tasks: + - + name: "Wait" + uuid: "ec1121a8-7481-420f-b532-c47ea86afcd7" + service_call: "/wait" + version: "0.0.0" + floats: [3.0] + strings: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 63" + uuid: "5ed54c1f-1599-497a-9c16-93c7ca6c355e" + latitude: 50.109384820042074 + longitude: -97.3194477601883 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 64" + uuid: "2e021345-636b-4bd3-81ba-4f6901fdc016" + latitude: 50.10934056359333 + longitude: -97.31936192949982 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 65" + uuid: "00c041ee-2ca4-40ba-8e38-65ac900d5a1d" + latitude: 50.10946930962604 + longitude: -97.31921709021302 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 66" + uuid: "a5826fc5-b696-4b63-82aa-cc2e7a426640" + latitude: 50.10949344950718 + longitude: -97.31911382516594 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 67" + uuid: "7ff204b2-79a3-46da-a8c0-2c734b4c5314" + latitude: 50.10949613171619 + longitude: -97.31898910244675 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + onav_config: "To be determined" +``` diff --git a/docs_outdoornav_user_manual/api/api_examples/mission_with_custom_tasks.mdx b/docs_outdoornav_user_manual/api/api_examples/mission_with_custom_tasks.mdx new file mode 100644 index 00000000..fc062073 --- /dev/null +++ b/docs_outdoornav_user_manual/api/api_examples/mission_with_custom_tasks.mdx @@ -0,0 +1,243 @@ +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +API examples are currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + +Before being able to run the examples similar to the one explained below, it is required that you have written your own custom tasks. See the +[Custom Tasks](../../features/custom_tasks) section for information on how to develop tasks for your application. + +## The Code + +``` python +#! /usr/bin/env python3 + +import rospy +import actionlib +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from clearpath_navigation_msgs.msg import Task, UITaskResult, UITaskAction + + +CUSTOM_ACTION_NAME = "/record_gnss" +UNSPECIFIED_HEADING = -1 + + +class MissionWithCustomTask(RosNode): + """Create and run a mission with 3 waypoints, each of which executes a custom task. + + Our goal is to set up 3 waypoints, then create a mission such that the robot drives + to each waypoint in order. In addition, at each of the waypoints, a custom task will be + called to record the timestamp, goal name, and GPS coordinates. Since this is a custom task, + it is necessary to create an actionlib server to implement the custom task. + + The main component of this example is the mission builder, which builds up the set of goals, + including information on the custom tasks, and runs the mission, to execute the custom task. + + The coordinates used in this example are based on the cpr_agriculture_gazebo + world and should be updated to match the location in which the user's + robot will be operating. + """ + + class MissionBuilder: + """Creates and runs the mission, including custom tasks.""" + + def __init__(self): + """Creates the mission with 3 waypoints and custom tasks.""" + + # First waypoint, with custom task + waypoint_a_name = "A" + custom_task_a = Task() + custom_task_a.name = "my_custom_task_a" # choose any name here + custom_task_a.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_a.version = "1.0" # choose any version + custom_task_a.floats = [1000] # param: unique ID + custom_task_a.strings = [waypoint_a_name] # param: goal name + + # Second waypoint, with custom task + waypoint_b_name = "B" + custom_task_b = Task() + custom_task_b.name = "my_custom_task_b" # choose any name here + custom_task_b.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_b.version = "1.0" # choose any version + custom_task_b.floats = [1001] # param: unique ID + custom_task_b.strings = [waypoint_b_name] # param: goal name + + # Third waypoint, with custom task + waypoint_c_name = "C" + custom_task_c = Task() + custom_task_c.name = "my_custom_task_c" # choose any name here + custom_task_c.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_c.version = "1.0" # choose any version + custom_task_c.floats = [1002] # param: unique ID + custom_task_c.strings = [waypoint_c_name] # param: goal name + + waypoints = [ + Waypoint(waypoint_a_name, "uuid-waypoint-01", 43.50076203007681, -80.546296281104, UNSPECIFIED_HEADING), + Waypoint(waypoint_b_name, "uuid-waypoint-02", 43.50073600330896, -80.54621215801687, UNSPECIFIED_HEADING, [custom_task_b]), + Waypoint(waypoint_c_name, "uuid-waypoint-03", 43.50067256664828, -80.5462159469465, UNSPECIFIED_HEADING, [custom_task_c]), + ] + + # Build mission from two waypoints with custom tasks + self._mission = Mission("Custom task mission", "uuid-mission-1", waypoints) + + def getMission(self): + """Gets a reference to the mission. + + Returns + ------- + A reference to the mission. + """ + return self._mission + + def __init__(self): + """Initializes ROS, the custom task server, GPS subscriber and mission.""" + + RosNode.__init__(self, 'mission_with_custom_task') + self._mission_builder = MissionWithCustomTask.MissionBuilder() + + + def run(self): + """Execute the mission. + + This function blocks until the mission is complete. + + Returns + ------- + True on successful execution of the mission; else False on any error. + """ + + if not self._mission_builder.getMission().startMission(): + return False + while not self._mission_builder.getMission().isMissionComplete(): + rospy.sleep(1.0) + return self._mission_builder.getMission().getMissionSuccess() + + +if __name__ == '__main__': + if MissionWithCustomTask().run(): + print("Mission completed successfully") + else: + print("Mission failed") + rospy.signal_shutdown('Done') +``` + +## The Code Explained + +``` python +import rospy +import actionlib +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from clearpath_navigation_msgs.msg import Task, UITaskResult, UITaskAction +``` + +Import the `RosNode`, `Waypoint` and `Mission` classes which will be used to create the mission to be executed. +We also import the `Task` and `UITask` messages which are used to generate the action servers. + +``` python + class MissionBuilder: + """Creates and runs the mission, including custom tasks.""" + + def __init__(self): + """Creates the mission with 3 waypoints and custom tasks.""" + + # First waypoint, with custom task + waypoint_a_name = "A" + custom_task_a = Task() + custom_task_a.name = "my_custom_task_a" # choose any name here + custom_task_a.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_a.version = "1.0" # choose any version + custom_task_a.floats = [1000] # param: unique ID + custom_task_a.strings = [waypoint_a_name] # param: goal name + + # Second waypoint, with custom task + waypoint_b_name = "B" + custom_task_b = Task() + custom_task_b.name = "my_custom_task_b" # choose any name here + custom_task_b.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_b.version = "1.0" # choose any version + custom_task_b.floats = [1001] # param: unique ID + custom_task_b.strings = [waypoint_b_name] # param: goal name + + # Third waypoint, with custom task + waypoint_c_name = "C" + custom_task_c = Task() + custom_task_c.name = "my_custom_task_c" # choose any name here + custom_task_c.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_c.version = "1.0" # choose any version + custom_task_c.floats = [1002] # param: unique ID + custom_task_c.strings = [waypoint_c_name] # param: goal name + + + waypoints = [ + Waypoint(waypoint_a_name, "uuid-waypoint-01", 50.1095255, -97.3192484, UNSPECIFIED_HEADING, [custom_task_a]), + Waypoint(waypoint_b_name, "uuid-waypoint-02", 50.1094938, -97.3191085, UNSPECIFIED_HEADING, [custom_task_b]), + Waypoint(waypoint_c_name, "uuid-waypoint-03", 50.1094600, -97.3192100, UNSPECIFIED_HEADING, [custom_task_c]), + ] + + # Build mission from two waypoints with custom tasks + self._mission = Mission("Custom task mission", "uuid-mission-1", waypoints) +``` + +We create the `MissionBuilder` subclass that will create the mission to be executed. We initialize custom task objects +where we specify the `action_server_name` field with the specific action of the custom task. These are then added to the +Waypoints as a list of tasks and the Mission object is created. + +``` python + def __init__(self): + """Initializes ROS, the custom task server, GPS subscriber and mission.""" + + RosNode.__init__(self, 'mission_with_custom_task') + self._mission_builder = MissionWithCustomTask.MissionBuilder() +``` + +We initialize the example class by starting a ROS node and initialize the mission to be executed. + +``` python + def run(self): + """Execute the mission. + + This function blocks until the mission is complete. + + Returns + ------- + True on successful execution of the mission; else False on any error. + """ + + if not self._mission_builder.getMission().startMission(): + return False + while not self._mission_builder.getMission().isMissionComplete(): + time.sleep(1.0) + return self._mission_builder.getMission().getMissionSuccess() +``` + +The `run()` function starts the mission and checks for completion. Once complete we terminate the example code. + +``` python +if __name__ == '__main__': + if MissionWithCustomTask().run(): + print("Mission completed successfully") + else: + print("Mission failed") + rospy.signal_shutdown('Done') +``` + +The main python execution block. We first initialize the example class (runs the __init__ function) and then execute the run() function which +executes the mission and outputs the status information. + + diff --git a/docs_outdoornav_user_manual/api/api_examples/monitor_status.mdx b/docs_outdoornav_user_manual/api/api_examples/monitor_status.mdx new file mode 100644 index 00000000..8aeb3ca8 --- /dev/null +++ b/docs_outdoornav_user_manual/api/api_examples/monitor_status.mdx @@ -0,0 +1,162 @@ +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +API examples are currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + +## The Code + +``` python +#! /usr/bin/env python3 + +import rospy +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from cpr_outdoornav_api_examples_lib.platform_status import PlatformStatusMonitor +from cpr_outdoornav_api_examples_lib.control_status import ControlStatusMonitor +from cpr_outdoornav_api_examples_lib.localization_status import LocalizationStatusMonitor +from cpr_outdoornav_api_examples_lib.navigation_status import NavigationStatusMonitor + + +class MonitorStatus(RosNode): + """Run a simple mission and report status throughout. + + The coordinates used in this example are based on the cpr_agriculture_gazebo + world and should be updated to match the location in which the user's + robot will be operating. + """ + + def __init__(self): + """Initialize the mission details and server connection.""" + + RosNode.__init__(self, 'monitor_status') + waypoints = [ + Waypoint("A", "uuid-waypoint-1", 50.1094938, -97.3191085), + Waypoint("B", "uuid-waypoint-2", 50.1095100, -97.3192000), + Waypoint("C", "uuid-waypoint-3", 50.1095255, -97.3192484), + ] + self.mission = Mission("Monitor status mission", "uuid-mission-1", waypoints) + self._platform_status = PlatformStatusMonitor() + self._control_status = ControlStatusMonitor() + self._localization_status = LocalizationStatusMonitor() + self._navigation_status = NavigationStatusMonitor() + + def _reportStatus(self): + """Report the current status.""" + + rospy.loginfo("--------------------------------------------------------") + self._platform_status.report() + self._control_status.report() + self._localization_status.report() + self._navigation_status.report() + + def run(self): + """Execute the mission and report status.""" + + if not self.mission.startMission(): + rospy.logerr("Failed to start mission") + return False + while not self.mission.isMissionComplete(): + self._reportStatus() + rospy.sleep(1.0) + return self.mission.getMissionSuccess() + + +if __name__ == '__main__': + if MonitorStatus().run(): + print("Mission completed successfully") + else: + print("Mission failed") + +``` + +## The Code Explained + +``` python +import rospy +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from cpr_outdoornav_api_examples_lib.platform_status import PlatformStatusMonitor +from cpr_outdoornav_api_examples_lib.control_status import ControlStatusMonitor +from cpr_outdoornav_api_examples_lib.localization_status import LocalizationStatusMonitor +from cpr_outdoornav_api_examples_lib.navigation_status import NavigationStatusMonitor +``` + +Import the `RosNode`, `Waypoint`, `Mission` classes which will be used to create the mission to be executed. We also import the +`PlatformStatusMonitor`, `ControlStatusMonitor`, `LocalizationStatusMonitor`, `NavigationStatusMonitor` classes which are set up to monitor the topics +relavant to the platform, localization, contrle selection an navigation modules respectively. + +``` python + waypoints = [ + Waypoint("A", "uuid-waypoint-1", 50.1094938, -97.3191085), + Waypoint("B", "uuid-waypoint-2", 50.1095100, -97.3192000), + Waypoint("C", "uuid-waypoint-3", 50.1095255, -97.3192484), + ] + self.mission = Mission("Monitor status mission", "uuid-mission-1", waypoints) +``` + +After initializing the ROS node, we create a mission manually by first creating a list of Waypoint objects and then adding then using the waypoint list +to construct the Mission object. + +``` python + self._platform_status = PlatformStatusMonitor() + self._control_status = ControlStatusMonitor() + self._localization_status = LocalizationStatusMonitor() + self._navigation_status = NavigationStatusMonitor() +``` + +We then initialize the platform, control, localization and navigation monitors, which subscribes to several API topics. + +``` python + def _reportStatus(self): + """Report the current status.""" + + rospy.loginfo("--------------------------------------------------------") + self._platform_status.report() + self._control_status.report() + self._localization_status.report() + self._navigation_status.report() +``` + +The `_reportStatus()` function outputs the results of the monitors to the ROS logs. This includes both the internal ROS logs as well as terminal output. + +``` python + def run(self): + """Execute the mission and report status.""" + + if not self.mission.startMission(): + rospy.logerr("Failed to start mission") + return False + while not self.mission.isMissionComplete(): + self._reportStatus() + rospy.sleep(1.0) + return self.mission.getMissionSuccess() +``` + +The `run()` function starts the mission and checks for completion. Every seconds we run the `reportStatus()` function to output the status information. +Once complete we terminate the example code. + +``` python +if __name__ == '__main__': + if MonitorStatus().run(): + print("Mission completed successfully") + else: + print("Mission failed") +``` + +The main python execution block. We first initialize the example class (runs the __init__ function) and then execute the run() function which +executes the mission and outputs the status information. diff --git a/docs_outdoornav_user_manual/api/api_overview.mdx b/docs_outdoornav_user_manual/api/api_overview.mdx index c4f425d4..23d711db 100644 --- a/docs_outdoornav_user_manual/api/api_overview.mdx +++ b/docs_outdoornav_user_manual/api/api_overview.mdx @@ -23,7 +23,7 @@ The API is, at present, a [ROS 1 Noetic](http://wiki.ros.org/noetic) API, but will soon be extended to a ROS 2 API. The API is divided into two sections, whose details are provided below: -- [Platform API](/docs_outdoornav_user_manual/api/api_endpoints/platform_api): The set of [ROS +- [Platform API](./api_endpoints/platform_api): The set of [ROS Topics](http://wiki.ros.org/Topics) are used to comminucate with the hardware platform (eg. sensor data, wireless, battery state, command velocity). This API can be used by autonomy software packages to @@ -33,7 +33,7 @@ sections, whose details are provided below: - [Topics Subscribed to by UGV](/docs_outdoornav_user_manual/api/api_endpoints/platform_api#topics-subscribed-by-platform): The set of topics that are subscribed to by the hardware platform. -- [Autonomy API](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api): The set of [ROS +- [Autonomy API](./api_endpoints/autonomy_api): The set of [ROS Topics](http://wiki.ros.org/Topics) that are used for monitoring and controlling the the hardware platform through the OutdoorNav autonomy software. @@ -52,9 +52,9 @@ sections, whose details are provided below: The set of [ROS Actions](http://wiki.ros.org/actionlib) provided by OutdoorNav Software, for use by the client to modify/control the behaviour of the Autonomy. -- [Mission Manager API](/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api): The set of [ROS +- [Mission Manager API](./api_endpoints/mission_manager_api): The set of [ROS Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions -- [Definitions](/docs_outdoornav_user_manual/api/api_endpoints/definitions): The set of custom +- [Definitions](./api_endpoints/definitions): The set of custom [ROS Message](http://wiki.ros.org/Messages), [ROS Service](http://wiki.ros.org/Services), and [ROS Action](http://wiki.ros.org/actionlib) definitions. diff --git a/docs_outdoornav_user_manual/cpr_hardware.mdx b/docs_outdoornav_user_manual/cpr_hardware.mdx index 02cf466a..9592cc29 100644 --- a/docs_outdoornav_user_manual/cpr_hardware.mdx +++ b/docs_outdoornav_user_manual/cpr_hardware.mdx @@ -40,7 +40,7 @@ at the Microstrain website. If you are using UM6 or UM7 IMUs, you will need the magnetometer display package which is located at the following address on your UGV: -`/home/administrator/catkin_ws/Drivers/src/imu_tools/magnetometer_display`. +`~/catkin_ws/Drivers/src/imu_tools/magnetometer_display`. Follow these steps to calibrate the IMU on your machine: diff --git a/docs_outdoornav_user_manual/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/docs_outdoornav_user_manual/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index b263c9f3..51639337 100644 --- a/docs_outdoornav_user_manual/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/docs_outdoornav_user_manual/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -6,4 +6,4 @@ toc_min_heading_level: 2 toc_max_heading_level: 2 --- -Information incoming in release 0.9.0. Please contact Clearpath customer support at to discuss any related issue. +Information incoming in release 0.10.0. Please contact Clearpath customer support at support@clearpathrobotics.com to discuss any related issue. diff --git a/docs_outdoornav_user_manual/customized_tuning/tuning_overview.mdx b/docs_outdoornav_user_manual/customized_tuning/tuning_overview.mdx index 460f3fdc..74d2aaa3 100644 --- a/docs_outdoornav_user_manual/customized_tuning/tuning_overview.mdx +++ b/docs_outdoornav_user_manual/customized_tuning/tuning_overview.mdx @@ -11,15 +11,15 @@ OutdoorNav. Instructions for tuning specific platform types can be found here: -- [Differential Drive (Skid-Steer) Dynamics](tuning_instructions/differential_drive_dynamics) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics) +- [Differential Drive (Skid-Steer) Dynamics](./tuning_instructions/differential_drive_dynamics) +- [Ackermann Drive Dynamics](./tuning_instructions/ackermann_drive_dynamics) Lists of parameters related to each component of the autonomy can be found here: -- [Localization Parameters](tuning_parameters/localization_parameters) -- [Navigation Parameters](tuning_parameters/navigation_parameters) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters) +- [Localization Parameters](./tuning_parameters/localization_parameters) +- [Navigation Parameters](./tuning_parameters/navigation_parameters) +- [Collision Avoidance Parameters](./tuning_parameters/collision_avoidance_parameters) -In future releases, we will describe how the user can [Customize their UI](user_interface_customization) -as well as how to [Customize which Sensors](sensor_customization) are input into OutdoorNav. \ No newline at end of file +In future releases, we will describe how the user can [Customize their UI](./user_interface_customization) +as well as how to [Customize which Sensors](./sensor_customization) are input into OutdoorNav. \ No newline at end of file diff --git a/docs_outdoornav_user_manual/faq.mdx b/docs_outdoornav_user_manual/faq.mdx index 2d862a59..28b4db4e 100644 --- a/docs_outdoornav_user_manual/faq.mdx +++ b/docs_outdoornav_user_manual/faq.mdx @@ -6,12 +6,12 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- -## Autonomous Missions +## General 1. **How do I start, pause or stop a mission?** - See [Mission Execution](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#mission-execution) for - information on how to start, pause or stop a mission. + A mission can be started in a few different ways, i) through the web user interface (See [Mission Execution](./web_user_interface/ui_autonomous_mode#mission-execution)) or, + ii) through the ROS API (See [API Examples](./api/api_examples)). 2. **When I start a mission the UGV does not move. What could be the problem?** @@ -33,52 +33,162 @@ toc_max_heading_level: 4 A missing task setting for a Move PTZ task will block the execution of the Mission it is in. -3. **How do I delete a waypoint?** +3. **What version of ROS is compatible with OutdoorNav?** - Make sure the **Edit Missions** toggle is enabled, then click the - **Waypoint Mode** button. Now you can click the Waypoint you wish to - delete. A drop down list will appear. Select **Delete**. + Currently OutdoorNav is developed in ROS 1 (and is built in Docker containers on top of ROS 1 Noetic). + So, the recommended ROS version is ROS 1 Noetic. However, although not recommended, it is still + possible to use ROS 1 Melodic. Some issues may arise related to the mismatched message types. + Also, if trying to run any python scripts as Melodic targets Python2, whereas Noetic targets Python3. -4. **How do I add a Task to a Waypoint?** + Finally, official ROS 2 compatibility is currently unsupported. In theory, if you only have ROS 2 installed + on your system, you can try to install ROS 1 Noetic as well and set up a ros1_to_ros2 bridge. Since the + OutdoorNav software is packaged in Dockers, it will communicate directly ROS 1 and then the data can be + redirected by the ros1_to_ros2 bridge to ROS 2. - See [Add Task to Waypoint](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#add-task) for information on how - to add a Task to a Waypoint. +4. **How can I record ROS data?** -5. **Why is the "Save Image" Task failing?** + There are two ways to record ROS data. The first is [through the UI](./features/rosbag_recorder) and the + second is the more traditional method of accessing the command line of the UGV's computer and running + [rosbag record commands](http://wiki.ros.org/rosbag/Commandline). - Check the Waypoints that have a **Save Image** task in the Waypoint panel. - If you see a red warning triangle beside the **Save Image** task it means - that the settings for this task were not set. Set them and rerun the - mission. +5. **Where do all the video/audio/images get saved from the mission tasks?** + + All of the data that gets saved (ROSbags, video recordings, audio recordings, and saved images) get stored on + UGV's computer at the following location: `~/clearpath_files/...` + +## Autonomy + +1. **Am I able to send the UGV on a repeated loop?** + + When generating a single mission on the UI or through the API, it is not possible for the + mission to start at the location of the robot and end at the location of the robot. This has to do with + the navigation thinking that the UGV has already arrived at its goal and will not generate a path through + the Waypoints. However, it is possible to split the mission into two missions (ie. one to go to a + location and the second to return to the starting point). With these two missions you will then either be + able to send each mission one after the other or you can use the [Mission Scheduler](./features/mission_scheduler). + Add the two missions to the schedule and you will have the ability to also repeat this loop as many times as needed. + +2. **Why is surveying failing?** + + There are several checks that should be done: + + - Check that the base station is powered on, and that all the devices inside are powered on. + - From the UGV's computer, check that you can ping the base station. + +``` bash +ping 192.168.131.30 +``` + +  If all of these tests PASS, contact [Support](./support). -6. **The navigation gets stuck on the "Compute Path" feedback. - What should I do?** +3. **Is it possible to increase the maximum velocity of the UGV?** - Power cycle the UGV by powering off the base platform. Wait 10 - seconds, then turn the base power back on. Allow 1-2 minutes for the - software to start up and refresh the Web UI page. + The OutdoorNav software has been tune for specific maximum velocities depending on the platform, + 1.2 m/s, 1.0 m/s and 2.0 m/s for Jackal, Husky and Warthog UGVs, respectively. The Husky maximum velocity + is 1.0 m/s so increasing above this is not possible however if you would like to increase the maximum + velocity for either the Jackal or the Warthog, further tuning may be required. Consult the + [tuning guide](./customized_tuning/tuning_instructions/differential_drive_dynamics) and contact + [Support](./support) if required. -7. **The UGV position and/or heading are behaving erratically while the - UGV is stationary. What should I do?** +4. **My robot it detecting too many obstacles and replanning too frequently. How can I resolve this?** - Power cycle the UGV by powering off the base platform. Wait 10 - seconds, then turn the base power back on, wait 10 seconds, then - turn the computer power back on (labelled **PWR** on the port/right - side of mast). Allow 1-2 minutes for the software to startup and - refresh the Web UI page. + Please consult the [Limitations](./features/collision_avoidance#limitations) section of the collisison + avoidance feature. It will describe some limits to the obstaacle detection and can help you improve the + smoothness of the navigation. -## Autonomous Docking +5. **I am getting a 'Robot too far off path warning'. What should I do?** -1. **When trying to dock, my UGV drives towards the dock but stops 2 - meters away and remains there. "Docking Failed" is displayed in - the UI feedback bar. How can I fix this?** + These types of warnings appear on the UI under two conditions: + i) If the robot indicator (blue arrow on the UI) is not within 3.0 meters of the first Waypoint (the Green one on the UI). + ii) If the robot is outside of the allowable navigable space (defined by the path contraint, default: 3.0 meters around the reference path). + Enable the visualization of the [path contraint](./web_user_interface/ui_autonomous_mode#constrained_path) and Teleop the robot back into the + navigable space. - It is likely that one of these 3 things occurred: +6. **How can I remove certain sensors from the collision avoidance pipeline?** - 1. The Base Station was recently resurveyed, or - 2. The datum was recently changed, or - 3. The dock location was not set correctly. + If your robot is equipped with collision avoidance sensors (eg. Velodyne, Hokuyo, Sick LMS), it is + possible to enable/disable the throughput of each sensor data into the collision avoidance pipeline. + Consult the [Collision Avoidance](./features/collision_avoidance) section for these instructions. + +7. **Can I use OutdoorNav without using the UI?** + + We empower customers to send mission via either the UI or our [ROS 1 API](./api/api_overview). Through this + API, you are enabled to write either CPP code or Python scripts where you would generate your mission, survey the base station, + set the datum, assign [custom tasks](./features/custom_tasks) to your mission. If using Python, we provide a set of libraries that + speed up the develpment process. See some of the [example codes](./api/api_examples) for an idea of how to generate these scripts. + +## Web User Interface + +1. **How do I delete a waypoint on the UI?** + + Make sure the **Edit Missions** toggle is enabled, then click the + **Waypoint Mode** button. Now you can click the Waypoint you wish to + delete. A drop down list will appear. Select **Delete**. + +2. **How do I add a Task to a Waypoint on the UI?** + + See [Add Task to Waypoint](./web_user_interface/ui_autonomous_mode#add-task) for information on how + to add a Task to a Waypoint. + +3. **Why is the "Save Image" Task failing?** + + Check the Waypoints that have a **Save Image** task in the Waypoint panel. + If you see a red warning triangle beside the **Save Image** task it means + that the settings for this task were not properly set. Set them and rerun + the mission. + +4. **Are we able to make any changes to the UI?** + + Unfortunately, users are not currently enabled to make modifications to the user interface. + This feature will be available in a future release. Please direct any feature requests to [Support](./support). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](./features/custom_tasks) instructions. When adding the + custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_autonomous_mode#add-task) + for your custom task are correct. + +6. **Why are either of the GNSS Status indicator (POS and/or DIR) on the UI not Green?** + + i) If the **POS** indicator is YELLOW, and you are using an RTK base station: + - Check communication between the robot and the base station by pinging 192.168.131.30 (from the UGV's computer) + - Re-survey the base station + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the both the base station IP (192.168.131.30) and the position unit IP (192.168.131.31) and ensure that certain + settings are set correctly: + On the base station unit: + 1) surveyed_position/broadcast = True + tcp_server1/mode = SBP + tcp_server1/enabled sbp messages = 72,74,117,65535,114 + tcp_server1/address = 55556 + On the position unit: + 2) tcp_client0/mode = SBP + tcp_client0/enabled sbp messages = 0 + tcp_client0/address = 192.168.131.30:55556 + ii) If the **POS** indicator is RED: + - Check communication between the robot and the position GNSS unit by pinging 192.168.131.31 (from the UGV's computer) + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the position unit IP (192.168.131.31) and ensure that the unit is working by checking that satellites are being + tracked in the "Tracking" tab. + + iii) If the **DIR** indicator is YELLOW, + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the position unit IP (192.168.131.31) and the heading unit IP (192.168.131.32), and ensure that certain + settings are set correctly: + On the position unit: + 1) tcp_server1/mode = SBP + tcp_server1/enabled sbp messages = 74,117 + tcp_server1/address = 55556 + On the heading unit: + 2) tcp_client0/mode = SBP + tcp_client0/enabled sbp messages = 0 + tcp_client0/address = 192.168.131.31:55556 + solution/dgnss_solution_mode = Time Matched + solution/heading offset = 0 + solution/send heading = True + solution/soln freq = 5 + solution/output ever n obs = 1 + + iv) If the **DIR** indicator is RED: + - Check communication between the robot and the position GNSS unit by pinging 192.168.131.31 (from the UGV's computer) - If any of these have occurred recently and you did not reset the - dock location from the Web UI, you will need to do so by following - the instructions in [Set Dock Location](/docs_outdoornav_user_manual/getting_started/system_setup#set-dock-location). diff --git a/docs_outdoornav_user_manual/features/_category_.json b/docs_outdoornav_user_manual/features/_category_.json new file mode 100644 index 00000000..732c6cb7 --- /dev/null +++ b/docs_outdoornav_user_manual/features/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/docs_outdoornav_user_manual/navigation.mdx b/docs_outdoornav_user_manual/features/collision_avoidance.mdx similarity index 50% rename from docs_outdoornav_user_manual/navigation.mdx rename to docs_outdoornav_user_manual/features/collision_avoidance.mdx index faffa0f5..f32f5f66 100644 --- a/docs_outdoornav_user_manual/navigation.mdx +++ b/docs_outdoornav_user_manual/features/collision_avoidance.mdx @@ -1,348 +1,334 @@ ---- -title: Navigation -sidebar_label: Navigation -sidebar_position: 8 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## Features - -The OutdoorNav Software contains a set of features that can be enabled -or disabled according to your required application requirements. These -features can be enabled or disabled through the use of environment -variables, which should be added to the -`/home/administrator/cpr_outdoornav_launch/outdoornav_tuning.env`. The -following table describes the available features, their default state -and any additional parameters that we expose that may also be included -to tune the feature. - -| Feature | Description | -|-----------------------------|----------------------------------------| -| **Data Collection** | The data collection feature enabled the user to record rosbag data of the sensors, localization, and navigation components of OutdoorNav. If `true`, rosbags will be saved and timestamed in the `/home/administrator/onav_log/rosbag_data/` directory. If `false`, no rosbag will be recorded.

Environment Variable: `ENABLE_BAGGING` (Default: `false`). | -| **Collision Avoidance** | Collision avoidance is the UGV's ability to detect obstacles and stop/maneuver around the obstacle without any collisions. If `true`, the UGV will detect obstacles and if `false` no obstacles will be detected. Setting to `false` is not recommended and may cause harm to property or to individuals.

Environment Variable: `ENABLE_COLLISION_AVOIDANCE` (Default: `true`). | -| **Obstacle Avoidance Mode** | When collision avoidance is enabled, the UGV will behave in one of two ways according to the obstacle avoidance mode. If set to `true`, the UGV will perform obstacle avoidance maneuvers, replanning around detected obstacles. If set to `false`, the UGV will slow down to a stop in front of detected obstacles and wait for the obstacle to clear before proceeding.

Environment Variable: `OBSTACLE_AVOIDANCE_MODE` (Default: `true`). | -| **Continuous Planning** | The continuous planning feature allows the UGV to continuously monitor whether an obstacle is on the UGV's path and replan around said obstacle smoothly without the need for stopping in front of the obstacle. If disabled, the UGV will come to a full stop in front of an obstacle and then replan around said obstacle.

Environment Variable: `ENABLE_CONTINUOUS_PLANNER` (Default: `true`). | -| **Path Smoothing** | The path smoothing feature according to a specified turning radius. The default behaviour will generate point-to-point straight line paths.

Environment Variable: `ENABLE_PATH_SMOOTHER` (Default: `false`). | -| **Path Shifting** | The path shifting feature is designed to reduce the oscillation around the initial reference path if the UGV begins to deviate of said reference path. It is particularly useful for the Clearpath Robotics Warthog platform whose tires are incredibly pliable and results in unmodelled effects on the navigation.

Environment Variable: `ENABLE_PATH_SHIFTING` (Default: `false`). | -| **Constrained Replanning** | The constrained replanning feature restricts the area in which replanning paths can be generated. For example, if a `REPLANNING_CONSTRAINT` of 3.0 m is used, the UGV will not be allowed to replan a path that drives it more than 3.0 m from the initial path. This replanning area can be shown on the map over the connecting lines between waypoints. See [Constrained Replanning](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#constrained_path) for further details.

Environment Variable: `ENABLE_CONSTRAINED_REPLANNING` (Default: `false`).

Use the `REPLANNING_CONSTRAINT` environment variable to modify the replanning constraint (in meters). | -| **Stop Distance** | The stop distance feature allows the UGV to stop a predefined distance away from obstacles. This is useful if a UGV cannot drive in reverse and needs the required room in front of it to replan around an obstacle.

Environment Variable: `ENABLE_STOP_DISTANCE` (Default: `false`)

Use the `STOP_DISTANCE` environment variable to modify the stop distance (in meters). Note that if the stop distance is larger than 4.5 meters for the Clearpath Robotics Jackal and Husky UGVs, or 10.0 meters for the Clearpath Robotics Warthog UGV, the computational load will increase and may cause a decrease in performance in the navigation. | -| **Delay Compensation** | The delay compensation feature is able to compensate for mechanical delay on UGVs where either the accelerator introduces delay into the linear velocity or the steering introduces delay in the angular velocity. This feature is not required for Clearpath Robotics UGVs as negligible delay is present in our system.

Environment Variable: `ENABLE_DELAY_COMPENSATION` (Default: `false`)

Use the `CONTROLLER_DELAY` environment variable to modify the amount of delay to be compensated (in milliseconds). | - -## Advanced Configuration - -The following section provides a list of environment variables that can -be modified in order to tune both the sensor systems as well as tuning -the navigation software. All of the environment variables listed below -can be modified in the -`/home/administrator/cpr_outdoornav_launch/outdoornav_tuning.env` file. - -### Sensor Tuning - -The following table lists the sensors that are useable with the -OutdoorNav software. These sensor drivers can be turned on/off using -these environment variables, however, the sensor will always remain -powered on. - -| Environment Variable | Description | Data Type -|--------------------------------|-------------------------------------------|-------------- -| **SWIFTNAV_ENABLE_DRIVER** | Enable/disable the Swiftnav Piksi/Duro ROS driver, if integrated. | bool | -| **UBLOX_ENABLE_DRIVER** | Enable/disable the UBlox ROS driver, if integrated. | bool | -| **MICROSTRAIN_ENABLE_DRIVER** | Enable/disable the Microstrain GX5/CV5 ROS driver, if integrated. | bool | -| **XSENS_ENABLE_DRIVER** | Enable/disable the XSens MTI ROS driver, if integrated. | bool | -| **VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (front unit if more than one). | bool | -| **REAR_VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (rear unit if more than one). | bool | -| **LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (front unit if more than one). | bool | -| **REAR_LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (rear unit if more than one). | bool | -| **HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (front unit if more than one). | bool | -| **REAR_HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (rear unit if more than one). | bool | -| **D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (front unit if more than one). | bool | -| **REAR_D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (rear unit if more than one). | bool | - - -### Sensor Tuning (Advanced) - -The following list of environment variables can be used to filter the -sensor data in order to modify/improve the sensory input to the -OutdoorNav autonomy. It is recommended that you first consult the -following links before attempting to modify these parameters. - -- [PCL Filters](http://wiki.ros.org/pcl_ros/Tutorials/filters) -- [PointCloud to LaserScan Filter](http://wiki.ros.org/pointcloud_to_laserscan) -- [DepthImage to LaserScan Filter](http://wiki.ros.org/depthimage_to_laserscan) - -#### Voxel Grid Filter - -| Environment Variable | Description | Data Type (Default) | -|----------------------|------------------------------------------|---------------------| -| **_ENABLE_FILTER_VOXEL** | Enable/disable the PCL voxel filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | -| **PCL_FIL_FILTER_VOXEL_LEAF_SIZE** | The size of a leaf (on x,y,z), in meters, used for downsampling. Range: 0.0 to 1.0. | double (0.01) | - -#### Cropbox Filter - -| Environment Variable | Description | Data Type (Default) | -|----------------------|------------------------------------------|---------------------| -| **_ENABLE_FILTER_CROPBOX** | Enable/disable the PCL cropbox filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | -| **PCL_FILTER_CROPBOX_MIN_X** | The lower bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(0.01) | -| **PCL_FILTER_CROPBOX_MAX_X** | The upper bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(2.0) | -| **PCL_FILTER_CROPBOX_MIN_Y** | The lower bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-10.0) | -| **PCL_FILTER_CROPBOX_MAX_Y** | The upper bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | -| **PCL_FILTER_CROPBOX_MIN_Z** | The lower bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-0.5) | -| **PCL_FILTER_CROPBOX_MAX_Z** | The upper bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | - -#### Radius Outlier Filter - -| Environment Variable | Description | Data Type (Default) | -|----------------------|------------------------------------------|---------------------| -| **_ENABLE_FILTER_RADIUS_OUTLIER** | Enable/disable the PCL radius outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | -| **PCL_FILTER_ROR_RADIUS_SEARCH** | The number of points within this distance, in meters, from the query point will need to be equal or greater than PCL_FILTER_ROR_MIN_NEIGHBORS in order to be classified as an inlier point (i.e. will not be filtered). | double
(0.05) | -| **PCL_FILTER_ROR_MIN_NEIGHBORS** | The number of points within PCL_FILTER_ROR_RADIUS_SEARCH from the query point will need to be equal or greater than this number in order to be classified as an inlier point (i.e. will not be filtered). | int
(10) | - -#### Statistical Outlier Filter - -| Environment Variable | Description | Data Type (Default) | -|----------------------|------------------------------------------|---------------------| -| **_ENABLE_FILTER_STATISTICAL_OUTLIER** | Enable/disable the PCL statistical outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | -| **PCL_FILTER_SOR_MEAN_K** | The number of points (k) to use for mean distance estimation Range: 2 to 100. | double
(5.0) | -| **PCL_FILTER_SOR_STD_DEV** | The standard deviation multiplier threshold. All points outside the mean +- sigma * std_mul will be considered outliers. Range: 0.0 to 5.0. | double
(0.3) | - -#### PointCloud to LaserScan Filter - -| Environment Variable | Description | Data Type (Default) | -|----------------------|------------------------------------------|---------------------| -| **_ENABLE_POINTCLOUD_TO_LASERSCAN** | Enable/disable the pointcloud to laserscan outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | -| **PCL_TO_SCAN_MIN_HEIGHT** | The minimum height to sample in the point cloud, in meters. | double
(0.2) | -| **PCL_TO_SCAN_MAX_HEIGHT** | The maximum height to sample in the point cloud, in meters. | double
(1.2) | -| **PCL_TO_SCAN_MIN_ANGLE** | The minimum scan angle, in radians. | double
(3.14) | -| **PCL_TO_SCAN_MAX_ANGLE** | The maximum scan angle, in radians. | double
(3.14) | -| **PCL_TO_SCAN_ANGLE_INCREMENT** | Resolution of laser scan, in radians, per ray. | double
(0.00218) | -| **PCL_TO_SCAN_TIME** | The scan rate in seconds. | double
(0.3333) | -| **PCL_TO_SCAN_MIN_RANGE** | The minimum ranges to return, in meters. | double
(0.3) | -| **PCL_TO_SCAN_MAX_RANGE** | The maximum ranges to return, in meters. | double
(100.0) | - - -#### DepthImage to LaserScan Filter - -| Environment Variable | Description | Data Type (Default) | -|----------------------|------------------------------------------|---------------------| -| **_ENABLE_DEPTH_TO_LASERSCAN** | Enable/disable the depth image to laserscan outlier filter for the sensor of type .

type = {D435, REAR_D435} | bool
(false) | -| **DEPTH_TO_SCAN_HEIGHT** | The number of pixel rows to use to generate the laserscan. For each column, the scan will return the minimum value for those pixels centered vertically in the image. | int | -| **DEPTH_TO_SCAN_TIME** | Time between scans (seconds). Typically, 1.0/frame_rate. This value is not easily calculated from consecutive messages, and is thus left to the user to set correctly. | double | -| **DEPTH_TO_SCAN_MIN_RANGE** | The minimum ranges to return in meters. Ranges less than this will be output as -Inf. | double | -| **DEPTH_TO_SCAN_MAX_RANGE** | The maximum ranges to return in meters. Ranges greater than this will be output as +Inf. | double | - -### Navigation Tuning - -The following table lists the environment variables that can be used to -enable/disable which sensor is used as part of the collision avoidance -feature of OutdoorNav. - -| Environment Variable | Description | Data Type | -|----------------------|------------------------------------------|-----------| -| **VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | -| **REAR_VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | -| **LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | -| **REAR_LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | -| **HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | -| **REAR_HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | -| **D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | -| **REAR_D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | - -### Navigation Tuning (Advanced) - -The following list of environment variables can be used to modify some -of the navigation inputs of to the OutdoorNav autonomy. It is -recommended that you first consult the following link(s) before -attempting to modify these parameters. - -- [Costmap2D/ObstacleLayer](http://wiki.ros.org/costmap_2d/hydro/obstacles) - -| Environment Variable | Description | Data Type | -|----------------------|------------------------------------------|-----------| -| **COSTMAP\_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | -| **COSTMAP\_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | -| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (rear unit if more than one). | double | -| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | - -## Command Line Operation - -By default the OutdoorNav Software, including the Navigation component, -begins automatically when the system is powered on. This section -outlines the commands that can be used by developers who are debugging -the system or who want more precise control for managing the Navigation -component. - -### Connecting to the OutdoorNav Computer {#connecting-to-outdoornav-computer} - -To connect to your UGV, consult its corresponding user manual. - -If you are using a Clearpath Robotics UGV with an OutdoorNav computer, -first `ssh` to the UGV using the details provided in the UGV user -manual. If you have a wired connection to the Clearpath Robotics UGV, -use the following command. If using wifi, you can replace the IP address -with the wifi-assigned IP address or the hostname of the UGV. - -``` bash -ssh administrator@192.168.131.1 -``` - -Then, connect to the OutdoorNav Computer: - -``` bash -ssh administrator@192.168.131.100 -``` - -### Starting the Navigation Software {#starting-outdoornav} - -Begin by connecting to the OutdoorNav Computer as outlined above. - -On UGV startup, all the sensors, the user interface, as well as the -Navigation software are set to start automatically through a Docker -container. You can check the Docker container's status by running -`docker compose ps` and checking for: - -- onav-web (Docker image containing the web interface) -- onav-web-ros (Docker image containing the ROS web bridge nodes) -- onav-sensors (Docker image containing that launches the ROS sensor - drivers) -- onav-autonomy (Docker image containing the ROS nodes related to the - autonomy) - -If the Docker containers are not running, they can be started with: - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav up -d -``` - -### Stopping/Restarting all of OutdoorNav - -To use the UGV without the OutdoorNav software, use these commands to -stop the software and prevent it from automatic startup: - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav stop -``` - -If the OutdoorNav software is currently running or has been stopped, it -can be restarted by running: - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav start -``` - -### Stopping/Restarting the Autonomy - -To use the UGV without the autonomy core of OutdoorNav, use these -commands to stop the nodes and prevent them from automatic startup: - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile autonomy stop -``` - -The autonomy core can be restarted by running: - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav start -``` - -### Stopping/Restarting the Sensors - -To use the UGV without the sensors, use these commands to disable the -nodes and prevent them from automatic startup: - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose stop -``` - -### Accessing the Shell in Docker Container - -To access the shell in a Docker container for debugging (optionally -replace `onav-autonomy` with `onav-web` in the following command): - -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose exec -it onav-autonomy bash -``` - -### Accessing the Navigation Software Logs - -To check the logs of the Navigation software: - -``` bash -cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml -docker compose logs -f -``` - -### Validating TF Setup - -:::note - -Sensor TF validation should only be required if the performance is -noticeably poor, such as when the UGV drifts off of the planned path or -oscillations occur around the path). - -::: - -The coordinate transformation of the two GPS antennas, the IMU, the 2D -and 3D Lidars to the base_link of the UGV should have already been set -prior to receiving the UGV. However, ensure that they are set correctly. - -The ROS coordinate frame base_link, shown in the figure below, is -located at the center of the bottom plate of the UGV. The environment -variables below should be taken with respect to this coordinate frame. -The X axis is in red (and pointing towards the front of the UGV), Y in -green (pointing towards the left of the UGV) and Z in blue (pointing -towards the sky). - -You can check the current value of the environment variables by running -the following (and setting to the names listed in the -table below). - -``` bash -printenv | grep -``` - -The environment variables for the position and orientation of each -sensor are provided in the table below. - -_GPS Navigation sensor position and orientation environment variables_ - -| Environment Variable | Function | -|----------------------|---------------------------------------| -| POSITION_GPS_XYZ | [X,Y,Z] position, in meters, of the position (rear) GPS antenna with respect to the base_link coordinate frame. | -| POSITION_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the position (rear) GPS antenna with respect to the base_link coordinate frame. | -| HEADING_GPS_XYZ | [X,Y,Z] position, in meters, of the heading (front) GPS antenna with respect to the base_link coordinate frame. | -| HEADING_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the heading (front) GPS antenna with respect to the base_link coordinate frame. | -| MICROSTRAIN_XYZ | [X,Y,Z] position, in meters, of the IMU with respect to the base_link coordinate frame. | -| MICROSTRAIN_RPY | [Roll,Pitch,Yaw], in radians, of the IMU with respect to the base_link coordinate frame. | -| LIDAR_XYZ | [X,Y,Z] position, in meters, of the 3D Lidar with respect to the base_link coordinate frame. | -| LIDAR_RPY | [Roll,Pitch,Yaw], in radians, of the 3D Lidar with respect to the base_link coordinate frame. | -| LASER_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | -| LASER_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | - -:::note - -When the printed Y axis on the IMU is pointing towards the front of the -robot (i.e., aligned to X axis of base_link), MICROSTRAIN_RPY = [0, 0, 0]. - -::: - -:::warning - -If you decide to move any of these sensors, you must modify these -variables accordingly. - -
-
- -
base_link coordinate frame
-
-
- -::: +--- +title: Collision Avoidance +sidebar_label: Collision Avoidance +sidebar_position: 2 +toc_min_heading_level: 2 +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. + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + +The collision avoidance feature of OutdoorNav allows our platforms to detect, +replan and then navigate around any obstacles that may be present in the UGV's +path. The workflow of this feature can be seen in the figure below. + + +
+
+ +
Collision avoidance workflow
+
+
+ +The detection sensors available on the UGV will have their data filtered, if necessary into data +that can be fed into the costmap(s). The costmap will then use this filtered data +to generate two costmaps (local and global). + +- **global costmap**: A large costmap (whose size gets set relative to the +Waypoints of the desired mission) the replanned paths around detected obstacles. +- **local costmap**: A smaller costmap that is used solely for detecting potential +collisions and triggering the path replanner. + +Therefore, there are two components in which we can tune the behaviour of the collision +avoidance feature: the sensor filters or the costmap generation. We will expand on these below. + +## Sensor Tuning + +The following table lists the sensors that are useable with the +OutdoorNav software. The sensor drivers can be turned on/off using +these environment variables, however, the sensor will always remain +powered on. The environment variables, should be added to the +`~/cpr_outdoornav_launch/env/sensors_customization.env` file. + +| Environment Variable | Description | Data Type +|--------------------------------|-------------------------------------------|-------------- +| **SWIFTNAV_ENABLE_DRIVER** | Enable/disable the Swiftnav Piksi/Duro ROS driver, if integrated. | bool | +| **UBLOX_ENABLE_DRIVER** | Enable/disable the UBlox ROS driver, if integrated. | bool | +| **MICROSTRAIN_ENABLE_DRIVER** | Enable/disable the Microstrain GX5/CV5 ROS driver, if integrated. | bool | +| **XSENS_ENABLE_DRIVER** | Enable/disable the XSens MTI ROS driver, if integrated. | bool | +| **VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (rear unit if more than one). | bool | +| **LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (rear unit if more than one). | bool | +| **HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (rear unit if more than one). | bool | +| **D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (rear unit if more than one). | bool | + + +### Sensor Filters + +:::info + +It is currently only possible to use one filter of the 3D LiDAR filters (voxel, cropbox, radius, or statistical outlier) at a +time on any source of data. In future releases we plan on expanding this to work as a filter chain. + +::: + +The following list of environment variables can be used to filter the +sensor data in order to modify/improve the sensory input to the +OutdoorNav autonomy. It is recommended that you first consult the +following links before attempting to modify these parameters. + +- [PCL Filters](http://wiki.ros.org/pcl_ros/Tutorials/filters) +- [PointCloud to LaserScan Filter](http://wiki.ros.org/pointcloud_to_laserscan) +- [DepthImage to LaserScan Filter](http://wiki.ros.org/depthimage_to_laserscan) + +#### Voxel Grid Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_VOXEL** | Enable/disable the PCL voxel filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FIL_FILTER_VOXEL_LEAF_SIZE** | The size of a leaf (on x,y,z), in meters, used for downsampling. Range: 0.0 to 1.0. | double (0.01) | + +#### Cropbox Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_CROPBOX** | Enable/disable the PCL cropbox filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_CROPBOX_MIN_X** | The lower bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(0.01) | +| **PCL_FILTER_CROPBOX_MAX_X** | The upper bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(2.0) | +| **PCL_FILTER_CROPBOX_MIN_Y** | The lower bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-10.0) | +| **PCL_FILTER_CROPBOX_MAX_Y** | The upper bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | +| **PCL_FILTER_CROPBOX_MIN_Z** | The lower bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-0.5) | +| **PCL_FILTER_CROPBOX_MAX_Z** | The upper bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | + +#### Radius Outlier Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_RADIUS_OUTLIER** | Enable/disable the PCL radius outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_ROR_RADIUS_SEARCH** | The number of points within this distance, in meters, from the query point will need to be equal or greater than PCL_FILTER_ROR_MIN_NEIGHBORS in order to be classified as an inlier point (i.e. will not be filtered). | double
(0.05) | +| **PCL_FILTER_ROR_MIN_NEIGHBORS** | The number of points within PCL_FILTER_ROR_RADIUS_SEARCH from the query point will need to be equal or greater than this number in order to be classified as an inlier point (i.e. will not be filtered). | int
(10) | + +#### Statistical Outlier Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_STATISTICAL_OUTLIER** | Enable/disable the PCL statistical outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_SOR_MEAN_K** | The number of points (k) to use for mean distance estimation Range: 2 to 100. | double
(5.0) | +| **PCL_FILTER_SOR_STD_DEV** | The standard deviation multiplier threshold. All points outside the mean +- sigma * std_mul will be considered outliers. Range: 0.0 to 5.0. | double
(0.3) | + +#### PointCloud to LaserScan Filter + +The following filter is enabled by default and is applied after any 3D LiDAR filtering has occured. It projects the final pointcloud topic onto the 2D plane that is then used to generate the costmap. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_POINTCLOUD_TO_LASERSCAN** | Enable/disable the pointcloud to laserscan outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_TO_SCAN_MIN_HEIGHT** | The minimum height to sample in the point cloud, in meters. | double
(0.2) | +| **PCL_TO_SCAN_MAX_HEIGHT** | The maximum height to sample in the point cloud, in meters. | double
(1.2) | +| **PCL_TO_SCAN_MIN_ANGLE** | The minimum scan angle, in radians. | double
(3.14) | +| **PCL_TO_SCAN_MAX_ANGLE** | The maximum scan angle, in radians. | double
(3.14) | +| **PCL_TO_SCAN_ANGLE_INCREMENT** | Resolution of laser scan, in radians, per ray. | double
(0.00218) | +| **PCL_TO_SCAN_TIME** | The scan rate in seconds. | double
(0.3333) | +| **PCL_TO_SCAN_MIN_RANGE** | The minimum ranges to return, in meters. | double
(0.3) | +| **PCL_TO_SCAN_MAX_RANGE** | The maximum ranges to return, in meters. | double
(100.0) | + + +#### DepthImage to LaserScan Filter + +Applicable for depth image data published on the `../depth/image_rect_raw` topic. + +Eg. Realsense [`DepthImage`](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/Image.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_DEPTH_TO_LASERSCAN** | Enable/disable the depth image to laserscan outlier filter for the sensor of type .

type = {D435, REAR_D435} | bool
(false) | +| **DEPTH_TO_SCAN_HEIGHT** | The number of pixel rows to use to generate the laserscan. For each column, the scan will return the minimum value for those pixels centered vertically in the image. | int | +| **DEPTH_TO_SCAN_TIME** | Time between scans (seconds). Typically, 1.0/frame_rate. This value is not easily calculated from consecutive messages, and is thus left to the user to set correctly. | double | +| **DEPTH_TO_SCAN_MIN_RANGE** | The minimum ranges to return in meters. Ranges less than this will be output as -Inf. | double | +| **DEPTH_TO_SCAN_MAX_RANGE** | The maximum ranges to return in meters. Ranges greater than this will be output as +Inf. | double | + + +## Costmap Tuning + +The following section provides a list of environment variables that can +be modified in order to tune OutdoorNav. All of the environment variables listed below +can be modified in the `~/cpr_outdoornav_launch/env/autonomy_customization.env` file. + +### Costmap Inputs + +The following table lists the environment variables that can be used to +enable/disable which sensor is used as part of the collision avoidance +feature of OutdoorNav. + +| Environment Variable | Description | Data Type | +|----------------------|------------------------------------------|-----------| +| **VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | + +### Costmap Generation + +The following list of environment variables can be used to modify some +of the navigation inputs of to the OutdoorNav autonomy. It is +recommended that you first consult the following link(s) before +attempting to modify these parameters. + +- [Costmap2D/ObstacleLayer](http://wiki.ros.org/costmap_2d/hydro/obstacles) + +| Environment Variable | Description | Data Type | +|----------------------|------------------------------------------|-----------| +| **COSTMAP\_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | +| **COSTMAP\_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | +| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (rear unit if more than one). | double | +| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | + + +## Limitations + +The collision avoidance feature as it currently stands, does come with some limitations. These are listed listed below: + +#### Detection range limits + +The maximum collision avoidance range for the OutdoorNav Software is +UGV-dependent and is related to the maximum speed of the UGV. These +ranges for Clearpath Robotics UGVs are: + +- Jackal UGV: 4.5 meters +- Husky UGV: 4.5 meters +- Warthog UGV: 15.0 meters + +While the sensors are able to detect objects at further distances, the +OutdoorNav Software only considers obstacles detected within these +distances for collision avoidance. That is, the UGV will only begin to +decelerate as it detects obstacles within this range. + +The detection itself is also related to the horizontal size +(width/diameter) of the obstacle. The limitations in detecting objects +with small horizontal size are described in the table below. + +_Maximum Reliable Obstacle Detection Distance from UGV, according to Obstacle Horizontal Size_ + +| Object Size (Horizontal) | Starter Sensor Kit | Standard/(CUstom w/ VLP) Sensor Kit | +|--------------------------|----------------------------------------------------------------|----------------------------------------------------------------| +| Less than 0.6 cm | No reliable detection | No reliable detection | +| 0.6 to 1.0 cm | 0.8 m | No reliable detection | +| 1.0 to 3.0 cm | 2.0 m | 1.75 m | +| Greater than 3.0 cm | Maximum collision avoidance distance (UGV-specific; see above) | Maximum collision avoidance distance (UGV-specific; see above) | + +Finally, the OutdoorNav Software bounds the obstacle detection to +prevent ground hits and to remove detections above the UGV body. The +following bounds are relative to the ground, assuming a flat surface. +Obstacles that are entirely below the lower bound or entirely above the +upper bound are not considered obstacles and will not be avoided. + +_Obstacle Detection Vertical Bounds_ + +| Vertical Bound | Jackal UGV | Husky UGV | Warthog UGV | +|-----------------------|------------|-----------|-------------| +| Lower Detection Bound | 0.3 m | 0.3 m | 0.3 m | +| Upper Detection Bound | 0.8 m | 1.3 m | 1.8 m | + +:::note + +The vertical detection bounds above are for the Standard Sensor Kit or a +custom sensor configuration that includes a Velodyne. The vertical +detection bounds for the Starter Sensor Kit have yet to be determined. + +::: + +#### Tall grass + +**Description**: Grass that is taller than 15cm may occasionally be detected as the robot is driving. + +**Workaround Available?**: Yes (Mitigation) + +**Mitigating Solution**: There are a couple of ways to reduce the amount of detections of long blades of grass. + +1) Apply either a radial filter or a statistical outlier filter on the pointcloud data to filter out the stray detections. + +- File: `~/cpr_outdoornav_launch/env/sensors_customization.env` +- Environment variable(s): `_ENABLE_FILTER_RADIUS_OUTLIER`, `_ENABLE_FILTER_STATISTICAL_OUTLIER` + +2) Increase the pointcloud to laserscan conversion filter minimum height parameter. The environment variable + +- File: `~/cpr_outdoornav_launch/env/sensors_customization.env` +- Environment variable(s): `PCL_TO_SCAN_MIN_HEIGHT` + +#### Pitch changes + +**Description**: Pitch changes along the UGVs planned path may cause the ground to be detected and +unwanted replanning may occur. This occurs because since we do not track change in pitch of the robot, +and since we filter the sensor data such that essentially chop off the lower portion of the data. +With the change in pitch this lower plane will then cause ground detections. + +**Workaround Available?**: Yes (Mitigation) + +**Mitigating Solution**: Limit the range from the `base_link` that the costmap generates lethal +obstacles, for a specific sensor. Eg. If your UGV has both a 3D and a 2D LiDAR. We want to limit +the range at which the 2D LiDAR will generate obstacles since the 3D LiDAR will cover a majority +of the detections. You would be able to reduce the range that the 2D LiDAR generates obstacles, +so that it does not overlap with the detection field of the 3D LiDAR. + +- File: `~/cpr_outdoornav_launch/env/autonomy_customization.env` +- Environment variable(s): `COSTMAP_LIDAR_2D_OBSTACLE_RANGE` and/or `COSTMAP_REAR_LIDAR_2D_OBSTACLE_RANGE` + +#### Branches across narrow path + +**Description**: If there are overhanging branches across a path (ie. not coming from the ground), +the navigation may not be able to maneuver through them. + +**Workaround Available?**: Limited to None + +**Mitigating Solution**: Reduction of the global costmap `inflation_radius` and/or `costmap_scaling_factor` +parameters may provide sufficient space for the navigation to replan though the branches. + +- File: `~/cpr_outdoornav_launch/env/onav_robots/params//navigation/costmap_global.yaml` +- Environment variable(s): `/navigation/global_costmap/inflation/inflation_radius` and/or `/navigation/global_costmap/inflation/cost_scaling_factor` + +:::info + +See the bottom of [this](http://wiki.ros.org/costmap_2d/hydro/inflation) page for information on how the +costmap inflation layer costs are computed based on the above two parameters. + +::: + +#### Reflective surfaces + +**Description**: Reflective surfaces on or around the robot can cause false positive obstacle placement +at incorrect locations on the costmap. + +**Workaround Available?**: No software workaround available. + +**Mitigating Solution**: Remove/cover/re-position all reflective surfaces on the robot. diff --git a/docs_outdoornav_user_manual/features/custom_tasks.mdx b/docs_outdoornav_user_manual/features/custom_tasks.mdx new file mode 100644 index 00000000..32c3115e --- /dev/null +++ b/docs_outdoornav_user_manual/features/custom_tasks.mdx @@ -0,0 +1,203 @@ +--- +title: Custom Tasks +sidebar_label: Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Users can create their custom tasks for their application following a specific template. When creating these tasks, the user should begin by creating a python file in the **~/cpr_outdoornav_launch/custom_tasks** directory. The file should be written following +the instructions provided below: + +1. Import the `custom_task_base` package. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * +``` + +2. The user should then create a class name to replace `CustomTask` and initialize it with the +`CustomTaskBase`'s __init__ function and the action server name for the task. + +```python +class CustomTask(CustomTaskBase): + def __init__(self): + # The derived class must always call the super() and provide the action server name. + # This name will need to be unique among custom tasks and must match what is in the + # UI. + super().__init__("custom_task_name") +``` + +:::note + +The `CustomTaskBase` exposes a `SimpleActionServer` (see here +for further details) object as `_as`, a `UITaskFeedback` object as `_feedback` and a `UITaskResults` object as `_result` to be used as part of +the tasks functionality. + +::: + +3. The last requirement is that the `CustomTask` needs to have the `run_task(self, goal)` function be defined, +which takes in the UITaskGoal. + +```python + def run_task(self, goal): +``` + +:::note + +When running the task users may handle errors through the action servers `set_aborted()` function. When this function is called the entire mission +will be aborted. + +::: + +4. Restarting the UGV will trigger the system to load the custom task that was created, making it available for mission use. +If a custom task is not configured properly the custom task manager will ignore the task and proceed loading in the next task while logging an error with ROS. + + +## Sample Custom Tasks + +### Input Looper + +Below is a sample template file named "input_looper.py" which iterates throught the two data variables and publishes them to the feedback +topic. If neither of the variables have any data in them the task is aborted. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * + +class InputLooperTask(CustomTaskBase): + def __init__(self): + # The derived class must always call the super() and provide the action server name. + # This name will need to be unique among custom tasks and must match what is in the + # UI. + super().__init__("input_looper") + + def run_task(self, goal): + if len(goal.strings) == 0 and len(goal.floats) == 0: + # Task and running mission will be aborted in this case + self._as.set_aborted() + return False + + # Loop through the strings and float values and publish them each to the /input_looper/feedback topic + for string in goal.strings: + self._feedback.state = string + self._as.publish_feedback(self._feedback) + + for num in goal.floats: + self._feedback.state = str(num) + self._as.publish_feedback(self._feedback) + + # Returning True or False will not currently impact the mission but will write the current state to the + # /task/result topic accordingly. + return True +``` + +### Record GNSS Data + +Below is a sample custom task file named "record_gnss.py" which outputs the current GNSS data to the console. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * +from sensor_msgs.msg import NavSatFix +from threading import Lock +import rospy + +class RecorGNSSTask(CustomTaskBase): + def __init__(self): + super().__init__("record_gnss") + self._sub = rospy.Subscriber("/sensors/gps_0/fix", NavSatFix, self.gpsSubscriberCallback) + self.gps_lat = 0.0 + self.gps_lon = 0.0 + self._gps_coordinates_lock = Lock() + + def run_task(self, goal): + feedback = UITaskFeedback() + feedback.state = 'Recording GNSS lat/lon' + self._as.publish_feedback(feedback) + msg = "" + with self._gps_coordinates_lock: + msg = "ID: %f Name: %s Latitude: %f Longitude: %f" % ( + goal.floats[0], goal.strings[0], self.gps_lat, self.gps_lon) + rospy.loginfo(msg) + return True + + def gpsSubscriberCallback(self, msg): + with self._gps_coordinates_lock: + self.gps_lat = msg.latitude + self.gps_lon = msg.longitude +``` + + +### Move PTZ camera to a Lat/Lon + +Below is a more advanced custom task. The file is "move_ptz_lat_lon.py" which pans a PTZ camera to point to a specific lat/lon coordinate. + +```python +from onav_tasks.custom_task_base import * +import actionlib +from clearpath_localization_msgs.srv import * +from clearpath_navigation_msgs.msg import * +from nav_msgs.msg import Odometry +from ptz_action_server_msgs.msg import PtzAction +import ptz_action_server_msgs.msg +import math +from math import remainder, tau +import rospy +from sensor_msgs import * +from tf.transformations import euler_from_quaternion, quaternion_from_euler + + + +class MovePtzLatLon(CustomTaskBase): + def __init__(self): + super().__init__("move_ptz_lat_lon") + self.localization_subscriber_ = rospy.Subscriber("/localization/odom", Odometry, self.localizationCallback) + self.move_ptz_client_ = actionlib.SimpleActionClient('/sensors/camera_0/move_ptz', PtzAction) + self.service_ = rospy.ServiceProxy('/localization/lat_lon_to_xy', ConvertLatLonToCartesian) + self.current_pose = Odometry() + + def localizationCallback(self, odom_msg): + self.current_pose = odom_msg + + def run_task(self, goal): + if len(goal.strings) == 0 and len(goal.floats) == 0: + rospy.logwarn('Warning') + self._as.set_aborted() + return False + goal_latitude = goal.floats[0] + goal_longitude = goal.floats[1] + goal_zoom = goal.floats[2] + str2 = 'Received goal latitude: ' + str(goal_latitude) + ', goal longitude: ' + str(goal_longitude) + ', zoom: ' + str(goal_zoom) + feedback = UITaskFeedback() + feedback.state = 'Aiming camera at lat-lon (' + str(goal_latitude) + ', ' + str(goal_longitude)+')' + self._as.publish_feedback(feedback) + orientation_q = self.current_pose.pose.pose.orientation + orientation_list = [orientation_q.x, orientation_q.y, orientation_q.z, orientation_q.w] + (roll, pitch, yaw) = euler_from_quaternion (orientation_list) + + gps_msg = sensor_msgs.msg.NavSatFix() + gps_msg.latitude = goal_latitude + gps_msg.longitude = goal_longitude + goal_utm = self.service_(gps_msg) + + goal_x = goal_utm.pose.pose.position.x + goal_y = goal_utm.pose.pose.position.y + + goal_angle = math.atan2(goal_y - self.current_pose.pose.pose.position.y, goal_x - self.current_pose.pose.pose.position.x) + pan_angle = math.remainder(goal_angle - yaw, math.tau) + print(pan_angle) + + self.move_ptz_client_.wait_for_server() + goal = ptz_action_server_msgs.msg.PtzGoal() + goal.pan=pan_angle + goal.tilt=0 + goal.zoom=goal_zoom + self.move_ptz_client_.send_goal(goal) + self.move_ptz_client_.wait_for_result() + print(self.move_ptz_client_.get_result()) + return True +``` diff --git a/docs_outdoornav_user_manual/features/foxglove_visualization.mdx b/docs_outdoornav_user_manual/features/foxglove_visualization.mdx new file mode 100644 index 00000000..7a36a4fc --- /dev/null +++ b/docs_outdoornav_user_manual/features/foxglove_visualization.mdx @@ -0,0 +1,27 @@ +--- +title: Foxglove Visualization +sidebar_label: Foxglove Visualization +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +We have enabled Foxglove visualization as part of OutdoornNav, for improved debugging and data visualization and analysis. +To access the Foxglove visualization interface for standard OutdoorNav configurations, navigate to the following +[URL](http://192.168.132.1/_/foxglove). + +For UGVs running OutdoorNav that are not equipped with a base station, you must first connect the UGV's computer to a network over the 192.168.131.xxx +subnet. You will then be able to access the platform at (`platform_pc_ip_address`/\_/foxglove), where the __ is +the IP address of the host (UGV) computer, typically 192.168.131.1. + +
+
+ +
Foxglove layout
+
+
+ +For more information on the available Foxglove panels and how to more thoroughly us it, please consult the [Foxglove documentation](https://foxglove.dev/docs/studio). \ No newline at end of file diff --git a/docs_outdoornav_user_manual/features/mission_scheduler.mdx b/docs_outdoornav_user_manual/features/mission_scheduler.mdx new file mode 100644 index 00000000..95c87061 --- /dev/null +++ b/docs_outdoornav_user_manual/features/mission_scheduler.mdx @@ -0,0 +1,43 @@ +--- +title: Mission Scheduler +sidebar_label: Mission Scheduler +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +### Scheduling missions + +By selecting the "SCHEDULER" option from the upper left hand menu, the user can open the Mission Scheduler interface. This interface +allows users to schedule groups of missions to run at a later time. These schedules can be set to run only once or to be looped over a period of time. +For example, a user could create a schedule that will run 3 missions starting at 9 AM and run every hour 8 times. Once the last iteration is run, the +schedule will disable itself and can be re-enabled to run again later. The view itself can be found in the image below and is elaborated further afterwards. + +
+
+ +
Mission Scheduler View
+
+
+ +#### Adding/Updating a Schedule + +The user can either create a new schedule by filling in the appropriate fields or edit a schedule by selecting the pencil icon for that schedule +in the bottom table. The input fields are outlined as follows: + +- Name: The name of the schedule. +- Start Time: The browser's local time that the schedule will start. This is stored as UTC time on the robot. +- Enabled: Enables/Disables the schedule. When schedules are completed they will disable themselves. +- Missions: The list of missions that will run. The schedule will run the missions in the order that they are added. +- Schedule Mode: Sets the kind of schedule mode to be either "Run Once" or "Looped". If it is set to run once, the next 2 inputs will be disabled. +- Loops: The number of iterations the schedule should run for. If for example it is set to Loop 5 times then the schedule will run 5 times (instead of run once and then re-runs 5 times). +- Loop Interval: The amount of time between the start of successive loop iterations. This is independent of the mission duration. +- Minimum Battery Charge: The minimum battery percentage that the UGV should be at to run the schedule. +- Timeout: The maximum amount of time to spend on running a single loop of the schedule. If a loop exceeds this timeout value the schedule is assumed to have failed and alerts the user + accordingly. This can be set to 0 to disable the timeout feature. + +#### Schedule Table + +Schedules found in the database are displayed in a simple table at the bottom of the screen. Schedules can be enabled, edited or deleted from this table through the +icons on the right hand side. The schedules can also be sorted by name or start time in ascending/descending order. The next schedule to run (if one is available) will have +a small information icon next to it's name and will also be reported at the top of the screen. \ No newline at end of file diff --git a/docs_outdoornav_user_manual/features/navigation.mdx b/docs_outdoornav_user_manual/features/navigation.mdx new file mode 100644 index 00000000..39e6dea1 --- /dev/null +++ b/docs_outdoornav_user_manual/features/navigation.mdx @@ -0,0 +1,38 @@ +--- +title: Navigation Features +sidebar_label: Navigation Features +sidebar_position: 1 +toc_min_heading_level: 2 +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. + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + +The OutdoorNav Software contains a set of features that can be enabled +or disabled according to your required application requirements. These +features can be enabled or disabled through the use of environment +variables, which should be added to the +`~/cpr_outdoornav_launch/env/autonomy_customization.env` file. The +following table describes the available features, their default state +and any additional parameters that we expose that may also be included +to tune the feature. + +| Feature | Description | +|-----------------------------|----------------------------------------| +| **Collision Avoidance** | Collision avoidance is the UGV's ability to detect obstacles and stop/maneuver around the obstacle without any collisions. If `true`, the UGV will detect obstacles and if `false` no obstacles will be detected. Setting to `false` is not recommended and may cause harm to property or to individuals.

Environment Variable: `ENABLE_COLLISION_AVOIDANCE` (Default: `true`). | +| **Constrained Planning** | The constrained replanning feature, which is always enabled, restricts the area in which the UGV can plan paths. For example, if the default `PATH_CONSTRAINT` of 3.0 m is used, the UGV will not be allowed to 1) produce paths that drives it more than 3.0 meters from the initial path, and 2) fail to compute paths if the UGV is further than 3.0 meters from the any of the Waypoints. This allowable planning/navigation area can be shown on the map over the connecting lines between Waypoints. See [Constrained Replanning](../web_user_interface/ui_autonomous_mode#constrained_path) for further details.

Use the `PATH_CONSTRAINT` environment variable to modify the path constraint (in meters). | +| **Path Smoothing** | Generate paths according to a specified turning radius.

Environment Variable: `ENABLE_DUBINS_PATH_SMOOTHER` (Default: `false`).

Use the `TURN_RADIUS` environment variable to modify the radius of the planned paths (in meters). | +| **Stop Distance** | The stop distance feature allows the UGV to stop a predefined distance away from obstacles. This is useful if a UGV cannot drive in reverse and needs the required room in front of it to replan around an obstacle.

Environment Variable: `ENABLE_STOP_DISTANCE` (Default: `false`)

Use the `STOP_DISTANCE` environment variable to modify the stop distance (in meters). Note that if the stop distance is larger than 4.5 meters for the Clearpath Robotics Jackal and Husky UGVs, or 10.0 meters for the Clearpath Robotics Warthog UGV, the computational load will increase and may cause a decrease in performance in the navigation. | +| **Delay Compensation** | The delay compensation feature is able to compensate for mechanical delay on UGVs where either the accelerator introduces delay into the linear velocity or the steering introduces delay in the angular velocity. This feature is not required for Clearpath Robotics UGVs as negligible delay is present in our system.

Environment Variable: `ENABLE_DELAY_COMPENSATION` (Default: `false`)

Use the `CONTROLLER_DELAY` environment variable to modify the amount of delay to be compensated (in milliseconds). | +| **Docking** | If purchased, autonomous docking will allow the user to autonomously dock/undock their UGV. If not purchased, enabling this environment variable will do nothing.

Environment Variable: `OUTDORRNAV_ENABLE_DOCKING` (Default: `false`).| diff --git a/docs_outdoornav_user_manual/features/rosbag_recorder.mdx b/docs_outdoornav_user_manual/features/rosbag_recorder.mdx new file mode 100644 index 00000000..503d94ae --- /dev/null +++ b/docs_outdoornav_user_manual/features/rosbag_recorder.mdx @@ -0,0 +1,34 @@ +--- +title: ROSbag Recorder +sidebar_label: ROSbag Recorder +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +If you need to perform a quick rosbag recording from the UI you can do +so by navigating to the Settings dropdown in the upper left hand menu and +select **Start rosbag recording**. This will record a rosbag of the +following topics (or all the topics in the namespace if followed by a +`/*`): + +- '/rosout(.*)' +- '/twist_marker_server/(.*)' +- '/dock/(.*)' +- '/laser_target_tracker/(.*)' +- '/localization/(.*)' +- '/localization_core/(.*)' +- '/localization_helper/(.*)' +- '/mission/(.*)' +- '/navigation/(.*)' +- '/onboard_systems/(.*)' +- '/platform/(.*)' +- '/swiftnav/(.*)' +- '/sensors/gps(.*)' +- '/sensors/imu(.*)' +- '/target/(.*)' +- '/tf(.*)' + +To stop the recording navigate to the Settings drop down and select +**Stop rosbag recording**. This will save the rosbag with the date and +time as its file name in the `~/clearpath_files/rosbag_data` folder. diff --git a/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx b/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx index 8c6dad6b..ed7b5ace 100644 --- a/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx +++ b/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx @@ -12,13 +12,13 @@ toc_max_heading_level: 4 Ensure that the Base Station has been set up approximately 5 meters away from any buildings and is currently powered on. See -[System Startup](/docs_outdoornav_user_manual/getting_started/system_setup) for further +[System Startup](./system_setup) for further instructions related to setting up the Base Station. ### ☐ Is the UGV connected to the Base Station? Check to see that the UGV can be pinged from the Base Station network. -See [Connecting to Web UI](/docs_outdoornav_user_manual/getting_started/system_setup#connecting_to_web_ui) for further +See [Connecting to Web UI](./system_setup#connecting_to_web_ui) for further details. ## Software Setup @@ -28,26 +28,24 @@ details. SSH into the UGV and run `rostopic list` to generate a list of the rostopics that are currently available. The list is generally fairly long so if you are looking for any specific topic please refer to -[API Endpoints](/docs_outdoornav_user_manual/api/api_endpoints). You can also check the -ROS status through the OutdoorNAV UI by selecting the ROS icon next to -the POS/DIR icons. - -![](/img/outdoornav_images/rosNavBarIcon.png) +[API Endpoints](../api/api_endpoints). You can also check the +ROS status through the OutdoorNAV UI by referring to the diagnostics section +on the Status page. ### ☐ Is the OutdoorNAV software running? Check to see if the relevant dockers are running (ssh into the UGV and -run `docker ps` which should show 4 separate docker containers -running.) +run `docker ps` which should show at least 5 separate docker containers +running). ### ☐ Is the computer using the UI connected to the Base Station network? This can be confirmed by following the steps found in -[Connecting to Web UI](/docs_outdoornav_user_manual/getting_started/system_setup#connecting_to_web_ui). +[Connecting to Web UI](./system_setup#connecting_to_web_ui). ### ☐ Have you surveyed the Base Station? -See [RTK Survey Positioning](/docs_outdoornav_user_manual/cpr_hardware#base-station-survey) for +See [RTK Survey Positioning](../cpr_hardware#base-station-survey) for information on how and when to survey the Base station. ### ☐ Do you have a strong GPS signal? @@ -55,25 +53,25 @@ information on how and when to survey the Base station. After surveying the Base Station check the upper right hand corner of the UI to confirm that you have a strong GPS signal (the POS and DIR icons should be green). If either of these icons are not green refer -to [Checking GPS RTK Fix](/docs_outdoornav_user_manual/getting_started/system_setup#checking-gpt-rtk-fix) for further +to [Checking GPS RTK Fix](../cpr_hardware#base-station-survey) for further troubleshooting information. ### ☐ Is the map loading correctly? Currently the map requires internet access to load. Refer to -[Loading Map Tiles](/docs_outdoornav_user_manual/getting_started/system_setup#loading_map_tiles) for more details +[Loading Map Tiles](./system_setup#loading_map_tiles) for more details related to setting up the map. ### ☐ Has the Datum been set? -See [Set Datum](/docs_outdoornav_user_manual/getting_started/system_setup#set-datum) for information on how +See [Set Datum](./system_setup#set-datum) for information on how to set the Datum variables. ### ☐ If docking is enabled has the location been set? If the Clearpath Robotics autonomous docking package was purchased the docking location will need to be set. See -[Set Dock Location](/docs_outdoornav_user_manual/getting_started/system_setup#set-dock-location) for information on +[Set Dock Location](./system_setup#set-dock-location) for information on how to set the docking location. ### ☐ Is the Navbar status icon functioning? @@ -92,25 +90,25 @@ properly. ### ☐ Can the virtual joystick drive the UGV? -See [Web UI Manual Mode](/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode) for further details +See [Web UI Manual Mode](../web_user_interface/ui_manual_mode) for further details related to this. ### ☐ Can you create a new mission? Select the mission list and then click on `Add Mission` to create a new mission. To add new waypoints for the mission refer to -[Mission Creation](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#mission-creation). +[Mission Creation](../web_user_interface/ui_autonomous_mode#mission-creation). ### ☐ After creating a new mission, can you execute the mission? -To execute a mission refer to [Mission Execution](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#mission-execution). +To execute a mission refer to [Mission Execution](../web_user_interface/ui_autonomous_mode#mission-execution). ### ☐ Are the cameras (if present) active in the view bar section when running the mission? For more information related to camera views see -[Camera Views](/docs_outdoornav_user_manual/web_user_interface/ui_overview#camera-views). +[Camera Views](../web_user_interface/ui_overview#camera-views). ### ☐ Can you select a camera and save an image after it loads on the main screen? -See [Pan-Tilt-Zoom (PTZ) View ](/docs_outdoornav_user_manual/web_user_interface/ui_overview#ptz-view) for more details related +See [Pan-Tilt-Zoom (PTZ) View ](../web_user_interface/ui_overview#ptz-view) for more details related to saving images. \ No newline at end of file diff --git a/docs_outdoornav_user_manual/getting_started/system_setup.mdx b/docs_outdoornav_user_manual/getting_started/system_setup.mdx index c702e5f9..95480fcd 100644 --- a/docs_outdoornav_user_manual/getting_started/system_setup.mdx +++ b/docs_outdoornav_user_manual/getting_started/system_setup.mdx @@ -8,7 +8,7 @@ toc_max_heading_level: 4 This section outlines how to set up your OutdoorNav system for some preliminary testing with the OutdoorNav Software on a UGV. For details -on simulation, refer to [Simulation](/docs_outdoornav_user_manual/simulation). +on simulation, refer to [Simulation](../simulation). These instructions assume that the UGV is already powered ON. @@ -49,8 +49,9 @@ Follow the steps below to connect to the Web UI. :::note For Clearpath Robotics OutdoorNav Hardware, this will be - **192.168.131.1/** for normal use cases and **192.168.131.100/** for - systems with a separate OutdoorNav computer. + **192.168.131.1/** for normal use cases and **192.168.131.5/** for + systems with a separate OutdoorNav computer (including the + OutdoorNav Starter Kit and the OutdoorNav Backpack. ::: @@ -158,29 +159,7 @@ and orientation. Wibotic receiver on the UGV should be centered longitudinally and laterally with the circle on the Wibotic transmitter (TR-300). -3. Measure a distance of 2 meters from the center panel of the dock - target (see figure below). Lock a measuring tape to a distance of 2 - meters and then lay it down beside the charge dock so that one end - is even with the center panel. - -
-
- -
Dock target location setup, using Husky as the reference UGV
-
-
- -4. Reduce the joystick scale on the Web UI to 20%. - -5. Reverse the UGV slowly so that its heading remains as perpendicular - as possible to the center panel. Reverse the UGV until the front of - the UGV (furthest front part) is 2 meters from the center panel (see - figure above for a visual description of what the final position - should look like). Centimeter precision is expected and the user - should aim to get this front piece within 1-2 centimeters of the - measured position (step 3). - -6. Let the UGV sit in this position for 2 minutes to acquire an RTK GPS +3. Let the UGV sit in this position for 2 minutes to acquire an RTK GPS fix. The POS (position) and DIR (heading) GPS status indicators on the UI should read as follows: . @@ -188,7 +167,7 @@ and orientation. location of the dock is NOT appropriate. Please change the dock location such that the GPS antennas have a clearer visibility.** -7. On the UI, access the drop down menu on the top-left of the page, +4. On the UI, access the drop down menu on the top-left of the page, select **Settings** and click the **Add New Dock Location** button. The dock location will be stored in 5 - 10 seconds as data is collected. @@ -196,7 +175,7 @@ If the Base Station has been moved (and therefore been resurveyed), or if the dock has been moved to a new location, the user will need to reset the location of the dock. This is done in the following manner: -1. Repeat the previous set of instructions from step 1 to 6. +1. Repeat the previous set of instructions from step 1 to 4. 2. While in **Edit Mode** select the dock on the UI. A drop down should appear with the option to reset the dock location. Select that option. @@ -221,24 +200,7 @@ the RTK GPS fix is acquired. ## Recording a Rosbag -If you need to perform a quick rosbag recording from the UI you can do -so by navigating to the Settings dropdown in the hamburger menu and -select **Start rosbag recording**. This will record a rosbag of the -following topics (or all the topics in the namespace if followed by a -`/*`): - -- rosout_agg/* -- rosout -- twist_marker_server/* -- localization_helper/* -- localization_core/* -- navigation/* -- piksi_position/* -- piksi_heading/* - -To stop the recording navigate to the Settings drop down and select -**Stop rosbag recording**. This will save the rosbag with the date and -time as its file name in the onav_log/rosbag_data folder. +See the [ROSbag Recorder](../features/rosbag_recorder) section for details on recording ROS data either. ## Subsequent Sections @@ -259,7 +221,7 @@ different tasks that can be accomplished while operating the UGV. > - Creating missions > - Viewing and updating missions > - Adding task to missions, such as **Move PTZ** camera, - > **Save Image**, **Dock/Undock** UGV, and **Wait**. + > **Save Image**, **Dock/Undock** UGV, **Wait**, etc.... > - Start/Stop/Pause missions - Description of the docking procedures allowing the user to dock @@ -267,8 +229,8 @@ different tasks that can be accomplished while operating the UGV. described. 2. **Application Programming Interface:** Details on how to control the UGV programmatically. -3. **Navigation** Details on the software used for autonomous - navigation. +3. **OutdoorNav Features** Details on the features available as part of the + navigation software. 4. **Simulation:** Details on how to simulate autonomous operation of the UGV. 5. **FAQs:** A list of frequently asked questions. diff --git a/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx b/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx new file mode 100644 index 00000000..43e9dedc --- /dev/null +++ b/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx @@ -0,0 +1,141 @@ +--- +title: Terminal Interface +sidebar_label: Terminal Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Command Line Operation + +By default the OutdoorNav Software, including the Navigation component, +begins automatically when the system is powered on. This section +outlines the commands that can be used by developers who are debugging +the system or who want more precise control for managing the Navigation +component. + +### Connecting to the OutdoorNav Computer {#connecting-to-outdoornav-computer} + +To connect to your UGV, consult its corresponding user manual. + +If you are using a Clearpath Robotics UGV with a seperate OutdoorNav computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. If you have a wired connection to the Clearpath Robotics UGV, +use the following command. If using wifi, you can replace the IP address +with the wifi-assigned IP address or the hostname of the UGV. + +``` bash +ssh administrator@192.168.131.1 +``` + +Then, connect to the OutdoorNav Computer: + +``` bash +ssh administrator@192.168.131.5 +``` + +### Starting the Navigation Software {#starting-outdoornav} + +Begin by connecting to the OutdoorNav Computer as outlined above. + +On UGV startup, all the sensors, the user interface, as well as the +Navigation software are set to start automatically through a Docker +container. You can check the Docker container's status by running +`docker ps` and checking for: + +- onav-web (Docker image containing the web interface) +- onav-web-ros (Docker image containing the ROS web bridge nodes) +- onav-sensors (Docker image that launches the ROS sensor drivers) +- onav-power (Docker image that launches the ROS nodes related to + the power system of the UGV) +- onav-autonomy (Docker image that launches the ROS nodes related + to the autonomy) + +The docker compose file located at `~/cpr_outdoornav_launch/docker-compose.yml` +provides the description for each the docker images that are being generated +on startup. In here, you can find that there are profiles set up as part of the +docker compose structure. They are: + +- ui: starts the onav-web and onav-web-ros containers +- sensors: starts the onav-sensors container +- power: starts the onav-power container +- autonomy: starts the onav-autonomy container +- outdoornav: starts all of the containers +- teleop: start only the ui and sensor related containers (no autonomy) + +If the Docker containers are not running, they can all be started with: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav up -d +``` + +### Stopping/Restarting all of OutdoorNav + +Each individual profile can also be brought down. For example to use the UGV without +the OutdoorNav software. The following command brings down OutdoorNav and is persistent +accross reboots/power cylces. + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav down +``` + +If the OutdoorNav software has been brought down, it can be restarted by running: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav up -d +``` + +### Stopping/Restarting the Autonomy + +To use the UGV without the autonomy core of OutdoorNav, use these +commands to stop the nodes and prevent them from automatic startup: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile autonomy down +``` + +The autonomy core can be restarted by running: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile autonomy up -d +``` + +### Stopping/Restarting the Sensors + +To use the UGV without the sensors, use these commands to disable the +nodes and prevent them from automatic startup: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile sensors down +``` + +::: note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNv software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars) + +::: + +### Accessing the Navigation Software Logs + +To check the logs of the Navigation software: + +``` bash +cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml +docker compose logs -f +``` + +Optionally, specify the specific container you would like to view logs for: + +``` bash +cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml +docker compose logs -f onav-autonomy +``` \ No newline at end of file diff --git a/docs_outdoornav_user_manual/getting_started/tf_validation.mdx b/docs_outdoornav_user_manual/getting_started/tf_validation.mdx new file mode 100644 index 00000000..5ba3bab4 --- /dev/null +++ b/docs_outdoornav_user_manual/getting_started/tf_validation.mdx @@ -0,0 +1,80 @@ +--- +title: TF Validation +sidebar_label: TF Validation +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Sensor transform (TF) validation should only be required if the performance +is noticeably poor, such as when the UGV drifts off of the planned path or +oscillations occur around the path). + +::: + +The coordinate transformation of the two GPS antennas, the IMU, the 2D +and 3D Lidars to the base_link of the UGV should have already been set +prior to receiving the UGV. However, ensure that they are set correctly. + +The ROS coordinate frame base_link, shown in the figure below, is +located at the center of the bottom plate of the UGV. The environment +variables below should be taken with respect to this coordinate frame. +The X axis is in red (and pointing towards the front of the UGV), Y in +green (pointing towards the left of the UGV) and Z in blue (pointing +towards the sky). + +You can check the current value of the environment variables by running +the following on the robot (host) computer (and setting +to the names listed in the table below). + +``` bash +printenv | grep +``` + +The environment variables for the position and orientation of each +sensor are provided in the table below. + +_OutdoorNav sensor position and orientation environment variables_ + +| Environment Variable | Function | +|----------------------|---------------------------------------| +| POSITION_GPS_XYZ | [X,Y,Z] position, in meters, of the position GNSS antenna with respect to the base_link coordinate frame. | +| POSITION_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the position GNSS antenna with respect to the base_link coordinate frame. | +| HEADING_GPS_XYZ | [X,Y,Z] position, in meters, of the heading GNSS antenna with respect to the base_link coordinate frame. | +| HEADING_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the heading GNSS antenna with respect to the base_link coordinate frame. | +| MICROSTRAIN_XYZ | [X,Y,Z] position, in meters, of the IMU with respect to the base_link coordinate frame. | +| MICROSTRAIN_RPY | [Roll,Pitch,Yaw], in radians, of the IMU with respect to the base_link coordinate frame. | +| VLP_XYZ | [X,Y,Z] position, in meters, of the 3D Lidar with respect to the base_link coordinate frame. | +| VLP_RPY | [Roll,Pitch,Yaw], in radians, of the 3D Lidar with respect to the base_link coordinate frame. | +| LMS1XX_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| LMS1XX_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | +| HOKUYO_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| HOKUYO_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | +| D435_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| D435_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | + +There may also be 2 of each of these detection sensors. The corresponding environment +variable is prefixed with `REAR_`. + +:::note + +When the printed Y axis on the IMU is pointing towards the front of the +robot (i.e., aligned to X axis of base_link), MICROSTRAIN_RPY = [0, 0, 0]. + +::: + +:::warning + +If you decide to move any of these sensors, you must modify these +variables accordingly in the `/opt/onav/outdoornav_host_setup.sh` file (on the host). + +
+
+ +
base_link coordinate frame
+
+
+ +::: diff --git a/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx b/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx index c0bf0dbc..4231afc9 100644 --- a/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx +++ b/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx @@ -14,6 +14,6 @@ software. | | All sensors have been mounted to the UGV with fixed brackets. Ie. the sensor should not move or rotate relative to the UGVs `base_link`. | | | Spacing between the GNSS antennas is greater than 0.7 m. | | | SwitfNav Piksi/Duro GNSS units, 2D/3D LiDAR units (Velodyne, Sick, Hokuyo) and Axis cameras have been configured to communicate over ethernet (IP). IP sensors are assigned within the following ranges on the `192.168.131.XXX` subnet and recorded in the table below.
**Cameras**: 192.168.131.10-19, **LiDARs**: 192.168.131.20-29, **GNSS**: 192.168.131.30-39, **Wireless**: 192.168.131.50-59

SensorSensor IPSensorSensor IP
| -| | For each sensor that is to be integrated, measure the XYZ position, in metres, and RPY (roll/pitch/yaw) orientation, in radians, relative to the robot's [base_link frame](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements#base-link-frame). Record the XYZ and RPY values in the table below.

SensorXYZRPY
| +| | For each sensor that is to be integrated, measure the XYZ position, in metres, and RPY (roll/pitch/yaw) orientation, in radians, relative to the robot's [base_link frame](./#base-link-frame). Record the XYZ and RPY values in the table below.

SensorXYZRPY
| Signature: Date: diff --git a/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx b/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx index 134848c2..5b803fd0 100644 --- a/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx +++ b/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx @@ -9,13 +9,13 @@ toc_max_heading_level: 4 Several hardware configurations are compatible with OutdoorNav Autonomy Software. Select the checklist below that corresponds to your hardware kit. -- [OutdoorNav Standard Kit Hardware Checklist](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist) -- [OutdoorNav Starter Kit Hardware Checklist](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist) -- [OutdoorNav Custom Kit Hardware Checklist](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist) +- [OutdoorNav Standard Kit Hardware Checklist](./standard_kit_hardware_checklist) +- [OutdoorNav Starter Kit Hardware Checklist](./starter_kit_hardware_checklist) +- [OutdoorNav Custom Kit Hardware Checklist](./custom_kit_hardware_checklist) In addition, if the OutdoorNav software is not running on the UGV computer itself, which is the case with the Starter Kit and some custom integrations, ensure that the UGV computer is configured correctly by reviewing the following checklist. -- [UGV Computer Checklist](/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist) +- [UGV Computer Checklist](../platform_computer_checklist) ## Notes on Measuring Frame Relationships diff --git a/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx b/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx index 639f9169..6508097f 100644 --- a/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx +++ b/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx @@ -31,7 +31,7 @@ To integrate this kit onto your robot, ensure that all of the requirements below | | Requirement | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The Starter Kit should be rigidly fixed to the UGV. Ie. It should not move or rotate relative to the UGVs base_link. | -| | Once mounted, the XYZ position of the [Starter Kit frame](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements#start-kit-frame) relative to the [base_link frame](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements#base-link-frame) has been noted here:
X: , Y: , Z: | +| | Once mounted, the XYZ position of the [Starter Kit frame](./#starter-kit-frame) relative to the [base_link frame](./#base-link-frame) has been noted here:
X: , Y: , Z: | | | The Starter Kit is connected to the base robot computer via a gigabit ethernet cable (Cat6(a) minimum). | | | The Starter Kit is power by an **18 - 75 V** source supplied by the UGV. | @@ -40,7 +40,7 @@ Should any of the external sensors positions need to be moved, the following con - The GNSS antenna is to be placed upright, on an unobstructed part of the UGV with clear visibility. - The RealSense D435f cameras should be placed with a minimal amount of their field of view (FoV) obstructed by the UGV body. - The new XYZ position of the GNSS antenna and/or the Realsense D435f cameras relative to the [Starter Kit Frame](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements#starter-kit-frame) are noted below: + The new XYZ position of the GNSS antenna and/or the Realsense D435f cameras relative to the [Starter Kit Frame](./#starter-kit-frame) are noted below: | Sensor | X | Y | Z | R | P | Y | | ----------------------- | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | diff --git a/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements.mdx b/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements.mdx index 39be4429..e22530ca 100644 --- a/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements.mdx +++ b/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements.mdx @@ -33,7 +33,7 @@ are satisfied for a smooth installation and tuning process. :::note -Consult the [Platform API](/docs_outdoornav_user_manual/api/api_endpoints##topics-platform-api) for +Consult the [Platform API](../api/api_endpoints/platform_api#topics-published-by-platform) for detailed information on the published/subscribed platform topics. ::: diff --git a/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist.mdx b/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist.mdx index a704b1df..343a813d 100644 --- a/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist.mdx +++ b/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist.mdx @@ -6,7 +6,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 5 --- -The following instructions are only required if intending to install the OutdoorNav software on a secondary or Starter Kit computer, henceforth named the **hardware kit**. If installed on the platform computer, please proceed to the [Interface Control Checklist](/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements). +The following instructions are only required if intending to install the OutdoorNav software on a secondary or Starter Kit computer, henceforth named the **hardware kit**. If installed on the platform computer, please proceed to the [Interface Control Checklist](./interface_control_requirements). In addition to the electromechanical installation of the hardware kit, software updates are required to the platform computer, as outlined below. @@ -19,6 +19,6 @@ In addition to the electromechanical installation of the hardware kit, software | | On the platform computer, [Install ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu) if not already installed (the `ros-noetic-ros-base` version is sufficient). | | | On the platform computer, configure ROS Noetic so it is running with the `ROS_MASTER_URI` set to the base platform computer. Note that `localhost:11311` is acceptable only if the primary subnet on the platform computer is the `192.168.131.XXX` subnet. | | | Restart both the platform computer and the hardware kit, then run `rostopic list` on the platform computer and confirm that it includes the OutdoorNav topics. | -| | On the platform computer, complete all checks in [Interface Control Checklist](/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements) and confirm that all listed ROS topics are publishing as expected. | +| | On the platform computer, complete all checks in [Interface Control Checklist](./interface_control_requirements) and confirm that all listed ROS topics are publishing as expected. | Signature: Date: diff --git a/docs_outdoornav_user_manual/integration_requirements/software_integration_instructions.mdx b/docs_outdoornav_user_manual/integration_requirements/software_integration_instructions.mdx index e41d3ec0..29431e38 100644 --- a/docs_outdoornav_user_manual/integration_requirements/software_integration_instructions.mdx +++ b/docs_outdoornav_user_manual/integration_requirements/software_integration_instructions.mdx @@ -8,8 +8,8 @@ toc_max_heading_level: 4 import versions from "@site/static/versions.js" -Prior to installing the OutdoorNav software, ensure that you have completed the relevant [Hardware Kit Checklist](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: -- [Interface Control Checklist](/docs_outdoornav_user_manual/integration_requirements/interface_control_requirements) +Prior to installing the OutdoorNav software, ensure that you have completed the relevant [Hardware Kit Checklist](./hardware_integration_requirements). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](./interface_control_requirements) All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. @@ -35,7 +35,7 @@ cd ~/cpr_outdoornav_launch/scripts/ ### Configure OutdoorNav Sensors {#configure-outdoornav-sensors} -Prior to configuring the sensors, ensure that you have measured the position (XYZ) and orientation (RPY) of each of your sensors with respect to the `base_link`. See your results from the [Integration Requirements](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements). +Prior to configuring the sensors, ensure that you have measured the position (XYZ) and orientation (RPY) of each of your sensors with respect to the `base_link`. See your results from the [Integration Requirements](./hardware_integration_requirements). ``` bash cd ~/cpr_outdoornav_launch/scripts/ @@ -71,7 +71,7 @@ docker compose --profile outdoornav pull ``` :::note -If you are installing the OutdoorNav software on a secondary or Starter Kit computer, you must also complete the [UGV Computer Checklist](/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist) +If you are installing the OutdoorNav software on a secondary or Starter Kit computer, you must also complete the [UGV Computer Checklist](./platform_computer_checklist) ::: ### Configure UGV Footprint {#configure-platform-footprint} @@ -103,7 +103,7 @@ nano outdoornav_tuning.env ``` bash cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav up -d +docker compose --profile outdoornav up -d --build ``` ### Test OutdoorNav Installation @@ -115,31 +115,31 @@ docker compose --profile outdoornav up -d ``` bash rostopic echo -n 1 /platform/odom rostopic echo -n 1 /platform/cmd_vel - + # IMU 1 (if included) -rostopic echo -n 1 /sensors/imu/0/data +rostopic echo -n 1 /sensors/imu_0/data rostopic echo -n 1 /localization/odom -# Velodyne 1 (if included) -rostopic echo /sensors/lidar/0/pointcloud - -# Velodyne 2 (if included) -rostopic echo -n 1 /sensors/lidar/1/pointcloud - -# Laser Scan Front (if included) -rostopic echo -n 1 /sensors/lidar/0/scan - -# Laser Scan Rear (if included) -rostopic echo -n 1 /sensors/lidar/1/scan +# Velodyne/Ouster/LMS1XX/Hokuyo/OutdoorScan (if included) +rostopic echo /sensors/lidar_/pointcloud +rostopic echo /sensors/lidar_/scan # Realsense D435 Front (if included) -rostopic echo -n 1 /sensors/stereo/0/pointcloud -rostopic echo -n 1 /sensors/stereo/0/depth/image_rect_raw +rostopic echo -n 1 /sensors/stereo_0/pointcloud +rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw # Realsense D435 Rear (if included) -rostopic echo -n 1 /sensors/stereo/1/pointcloud -rostopic echo -n 1 /sensors/stereo/1/depth/image_rect_raw +rostopic echo -n 1 /sensors/stereo_1/pointcloud +rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw ``` -Once installation is complete, you can proceed to [Getting Started](/docs_outdoornav_user_manual/getting_started/system_setup) to start using the software. + will be the number of the sensor as it was loaded into the software. Eg. If you have a VLP and an LMS1XX, then the VLP will be lidar_0, and the LMS1XX will be lidar_1. If we only have an LMS1XX, then it would be lidar_0. Ie. the 3D lidars have a higher "priority" and therefore will be loaded first. + +:::note + +The 2D LiDARs (LMS1XX, Hokuyo) will not have a pointcloud topic. + +::: + +Once installation is complete, you can proceed to [Getting Started](../getting_started/system_setup) to start using the software. diff --git a/docs_outdoornav_user_manual/overview/overview_hardware_requirements.mdx b/docs_outdoornav_user_manual/overview/overview_hardware_requirements.mdx index e12de552..02c52263 100644 --- a/docs_outdoornav_user_manual/overview/overview_hardware_requirements.mdx +++ b/docs_outdoornav_user_manual/overview/overview_hardware_requirements.mdx @@ -9,7 +9,7 @@ toc_max_heading_level: 4 OutdoorNav Software works with compatible UGVs, either from Clearpath Robotics or third parties. High level requirements for compatible UGVs are outlined below. Detailed qualification requirements are outlined in -[UGV Integration Requirements](/docs_outdoornav_user_manual/integration_requirements/integration_overview). +[UGV Integration Requirements](../integration_requirements/integration_overview). ## Requirements @@ -28,8 +28,8 @@ format. More detailed requirements are outlined in the following table. | 2 | The UGV must have velocity control of the wheels and provide kinematic control of the platform | | | 3 | The UGV shall provide odometry feedback of the wheel direction and velocities and/or steering position | Recommended encoder resolution of 500 ticks per revolution or greater | | 4 | The UGV should have an emergency stop system with status feedback | | -| 5 | The UGV must accept ROS 1 Twist Commands on the `/cmd_vel` topic | See: [API Endpoints](/docs_outdoornav_user_manual/api/api_endpoints); ROS 2 interface available in future release | -| 6 | The UGV must provide odometry and status feedback through ROS topics | See: [API Endpoints](/docs_outdoornav_user_manual/api/api_endpoints) | +| 5 | The UGV must accept ROS 1 Twist Commands on the `/cmd_vel` topic | See [API Endpoints](../api/api_endpoints); ROS 2 interface available in future release | +| 6 | The UGV must provide odometry and status feedback through ROS topics | See [API Endpoints](../api/api_endpoints) | ## Typical Hardware diff --git a/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx b/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx index 2911ec1e..c02228aa 100644 --- a/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx +++ b/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx @@ -172,7 +172,6 @@ _Obstacle Detection Vertical Bounds_ The vertical detection bounds above are for the Standard Sensor Kit or a custom sensor configuration that includes a Velodyne. The vertical -detection bounds for the Starter Sensor Kit have yet to be determined -for release 0.5.0. +detection bounds for the Starter Sensor Kit have yet to be determined. ::: \ No newline at end of file diff --git a/docs_outdoornav_user_manual/release_notes.mdx b/docs_outdoornav_user_manual/release_notes.mdx index 4e433095..75bef2a4 100644 --- a/docs_outdoornav_user_manual/release_notes.mdx +++ b/docs_outdoornav_user_manual/release_notes.mdx @@ -6,13 +6,50 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler)) +- Added in support for BulletCat12 Microhard WiFi and Cellular connections +- Allow Audio recording as both tasks and manual operations if UGV has Microphones +- Create custom tasks that can be run during missions (see [Custom Tasks](./features/custom_tasks)) +- If installed with PDU, UGV can be set to Low Power mode to better conserve power +- New navigation topics added to ROS Autonomy API (see [API Endpoints](./api/api_endpoints/autonomy_api)): + - /navigation/progress + - /navigation/motion_state + - /navigation/metrics +- Improved precision of docking +- Improved autonomy feedback when something goes wrong in the mission to increase the diagnosability of the error +- Updated Navigation features available to the customer: + - Continuous Replanning renamed to Continuous Planning and is always enabled. + - Constrained Planning is always enabled. Environment Variable to update the path constraint has been modified + (see [Navigation](./features/navigation)) + - Removed Obstacle Avoidance Mode. The UGV will always attempt to avoid obstacles. + - Removed Path Smoothing. This is always enabled. + - Docking feature added for customers who have purchased a dock. + +### Bug Fixes + +- 1324: Allow single Waypoint missions and/or tasks on first waypoint (required for undocking through tasks). +- 1340: Undocking not working through tasks +- 1607: Fixed MovePTZ task failures + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint. +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location. + ## 0.8.0 ### New Features - Inertial Measurement Units (IMUs) integrated into localization. -- Added localization status topic (see see [API Endpoints](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api)). -- Added re-localization service (see [API Endpoints](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api)). +- Added localization status topic (see [API Endpoints](./api/api_endpoints/autonomy_api#localizationstatus)). +- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions#srv-reset-localization)). - Additional diagnostic information in the status view. - Docking improvements including: multiple docks, visual representation of docks on map, local docking/undocking through teleop view. Docking only functional with 2D LiDARs. @@ -42,7 +79,7 @@ toc_max_heading_level: 4 ### New Features - Goal terminology has been removed from the mission generation nomenclature (see - [Definitions](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#definitions)) + [Definitions](./web_user_interface/ui_autonomous_mode#definitions)) Users can now add tasks, apply final headings, and set navigation tolerances to any Waypoint in a Mission. - Drag and Drop of Waypoints now available in Edit Mode. @@ -70,7 +107,7 @@ toc_max_heading_level: 4 ### New Features - OutdoorNav ROS API updated. API now divided into Platform and - Autonomy sections. See [API Overview](/docs_outdoornav_user_manual/api/api_overview) + Autonomy sections. See [API Overview](./api/api_overview) for more details. - Simulation environment created with charge dock, base station and camera plugins. diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx index 8ffdeed6..66bd7d4d 100644 --- a/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx +++ b/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx @@ -8,7 +8,7 @@ toc_max_heading_level: 4 ![](/img/outdoornav_images/gps_danger.png) -Ensure that the [Safety](/docs_outdoornav_user_manual/safety) document has been +Ensure that the [Safety](../safety) document has been read and the user is aware of possible hazards when using this product as well as the safety methods that can be used to stop the moving UGV. @@ -75,7 +75,7 @@ Waypoints with the exception of the first waypoint (green) and the last waypoint :::note -**The first Waypoint in the mission must be within 1.5 meters of the UGV's current position.** +**The first Waypoint in the mission must be within 3.0 meters of the UGV's current position.** ::: @@ -84,28 +84,6 @@ Waypoints and can be dragged to a new spot to insert a real Waypoint between them. Waypoints can also be dragged and dropped on the map to modify their positions. -## Constrained Replanning {#constrained_path} - -If constrained replanning is enabled the user can show on the path -deviation distance by navigating to the General settings in the -hamburger menu. Once enabled the area of possible deviation will show -over the planned route as can be seen in the following figure. - -
-
- -
Route with deviation
-
-
- -:::note - -If the UGV is manually driven outside of the constrained replanning area -while a Mission is running, the Mission will need to be restarted as the UGV -will no longer be able to find it's way back onto the path. - -::: - ### Waypoint Panel
@@ -171,19 +149,19 @@ To add a Task to the end of a Mission: in the task settings. Settings: Select the camera position. See - [Pan-Tilt-Zoom (PTZ) View](#ptz-view) for details on how to + [Pan-Tilt-Zoom (PTZ) View](./ui_overview#ptz-view) for details on how to save camera positions. - Save Image: Will save an image using one of the UGV camera(s) - to the **/onav_log** folder and can be retrieved using a tool + to the **~/clearpath_files** folder and can be retrieved using a tool such as Filezilla. Settings: Select which camera the image will be saved from. - Start/Stop Video Recording: Will start/stop recording video using one of the - UGV camera(s) to the **/onav_log** folder and can be retrieved + UGV camera(s) to the **~/clearpath_files** folder and can be retrieved using a tool such as Filezilla. Settings: Select which camera the recording will come from. @@ -193,9 +171,7 @@ To add a Task to the end of a Mission: completed, the UGV can be sent on autonomous missions. It is often recommended to place the undock task first in the list of Waypoints; that way, the UGV will automatically continue towards its next - Waypoint once undocked. See Section - [Autonomous Docking](#autonomous-docking) for more - information on the autonomous docking feature. + Waypoint once undocked. - Wait: Will pause and wait for the specified number of @@ -204,9 +180,7 @@ To add a Task to the end of a Mission: Settings: Enter the amount of time to wait, in seconds. - New Custom Task: - Creates a new custom task that is defined by the user. Users specify a task name along with an absolute path to the custom tasks - action server. Custom tasks can take two optional comma separated lists, one of floating point values the other of standard text strings. - + Creates a new custom task that is defined by the user.
@@ -214,9 +188,13 @@ To add a Task to the end of a Mission:
- - See [Custom Tasks](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#custom-task) - for more details on creating custom tasks. + - Task Name: Task name that will show up in the list of available tasks on the UI. + - Action Server Name: The namespace of the custom task action server. + - Float CSV: A list of comma seperated float values that consist of the numerical inputs to the custom task. + - String CSV: A list of comma seperated string values that consist of the semantic inputs to the custom task. + + See the [Custom Tasks](../features/custom_tasks) section + for details on how to develop custom tasks for your application. 4. Click the Gear icon next to the selected Task to add the required Settings. @@ -228,98 +206,6 @@ To add a Task to the end of a Mission: ::: -### Custom Tasks {#custom-task} - -Users can create their own tasks following a specific template and place them within the **~/cpr_outdoornav_launch/custom_tasks** directory. -Restarting the UGV will trigger the system to load the custom task that was created, making it available for mission use. -Below is a sample template file named "input_looper.py" which iterates throught the two data variables and publishes them to the feedback -topics. The purpose of this task is to simply outline what is available to the user when they decide to create their own tasks. - -#### Sample Custom Task - -This sample custom task iterates through the two available data variables and outputs them to the feedback topic. If neither of the -variables have any data in them the task is aborted. Each section will be elaborated further in the document. - -```py -#!/usr/bin/python3 - -from onav_tasks.custom_task_base import * - -class InputLooperTask(CustomTaskBase): - def __init__(self): - # The derived class must always call the super() and provide the action server name. - # This name will need to be unique among custom tasks and must match what is in the - # UI. - super().__init__("input_looper") - - def run_task(self, goal): - if len(goal.strings) == 0 and len(goal.floats) == 0: - # Task and running mission will be aborted in this case - self._as.set_aborted() - return False - - # Loop through the strings and float values and publish them each to the /input_looper/feedback topic - for string in goal.strings: - self._feedback.state = string - self._as.publish_feedback(self._feedback) - - for num in goal.floats: - self._feedback.state = str(num) - self._as.publish_feedback(self._feedback) - - # Returning True or False will not currently impact the mission but will write the current state to the - # /task/result topic accordingly. - return True -``` - -##### Custom Task Class - -To leverage custom tasks, users will need to create a new file that defines a new class which inherits from `CustomTaskBase`. The `CustomTaskBase` class is -found in the `onav_tasks.custom_task_base` package. It exposes a `SimpleActionServer` (see here -for further details) object as `_as`, a `UITaskFeedback` object as `_feedback` and a `UITaskResults` object as `_result` to be used as part of -the tasks functionality. The custom task manager requires the user to also define a `run_task` method that takes a `UITaskGoal` object as a parameter. - -```py -from onav_tasks.custom_task_base import * - -class CustomTask(CustomTaskBase): - def __init__(self): - super().__init__("input_looper") - - def run_task(self, goal): -``` - -##### Aborting Tasks - -When running the task users may handle errors through the action servers `set_aborted()` function. When this function is called the entire mission -will be aborted. In this sample the task is aborted if neither of the lists have any values. - -```py -if len(goal.strings) == 0 and len(goal.floats) == 0: - # Task and running mission will be aborted in this case - self._as.set_aborted() - return False -``` - -##### Setting feedback - -Users can set the feedback state using the `SimpleActionServer` class's standard methods. In this case the task iterates through the comma delimited -strings and floats and writes them to the feedback state before publishing them. Upon success the `run_task` method returns True. - -```py -for string in goal.strings: - self._feedback.state = string - self._as.publish_feedback(self._feedback) - -for num in goal.floats: - self._feedback.state = str(num) - self._as.publish_feedback(self._feedback) - - return True -``` - -If a custom task is not configured properly the custom task manager will ignore the task and proceed loading in the next task while logging an error with ROS. - ### Advanced Settings @@ -367,6 +253,38 @@ the "Gear" icon. To set the Waypoint's tolerance, the user will need to check the "Waypoint Tolerance Enabled" checkbox and enter the position and orientation values, in meters and degrees, respectively. +### Constrained Replanning {#constrained_path} + +To enable the visualization of the contrained area of traversal (defined by +the path contraint around the reference path), navigate to the General settings +in the hamburger menu. Enable/disable the visualization of the path ui_route_deviation +distance using the switch button (see image below). + +
+
+ +
General settings
+
+
+ +Once enabled the area of possible deviation will show +over the planned route as can be seen in the following figure. + +
+
+ +
Route with maximum path deviation
+
+
+ +:::note + +If the UGV is manually driven outside of the constrained replanning area +while a Mission is running, the Mission will not be able to be resumed until the +UGV is returned within the navigable area defined by the path contraint. + +::: + ## Mission Execution ### Start Mission diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx index 109c47ed..a18672dc 100644 --- a/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx +++ b/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx @@ -12,7 +12,7 @@ environment and by using a joystick to control the motion of the UGV. ![](/img/outdoornav_images/teleop_danger.png) -Ensure that you have read [Safety](/docs_outdoornav_user_manual/safety) and are +Ensure that you have read [Safety](../safety) and are aware of possible hazards when using this product as well as the safety methods that can be used to stop the moving UGV. diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx index fe0de529..aafe45f2 100644 --- a/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx +++ b/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx @@ -22,22 +22,28 @@ mode.
1. **Menu:** A dropdown menu allowing the user to access the Dashboard - (ie. Home), Settings, Status or Help pages. + (ie. Home), Settings, Status, Scheduler and Help pages. The Operator + can also run the UI Virtual Tour from this menu. -2. **Path Progress Meter:** A meter indicating the percentage complete +2. **Feedback Bar:** The feedback bar will display information + regarding the execution state of the navigation and of any Tasks + being executed. + +3. **Path Progress Meter:** A meter indicating the percentage complete of a Mission. -3. **UGV Position:** The UGV's X and Y position in the world frame - relative to the Datum. +4. **UGV Position:** The UGV's X and Y position in the world frame + relative to the Datum. Can also be shown in Lat/Lon coordinates -4. **UGV Heading:** The UGV's heading in the world frame. +5. **UGV Heading:** The UGV's heading in the world frame. 0 degrees is North, 90 degrees is East, 180 degrees is South and 270 degrees is West. -5. **Status Indicator:** The status indicator will display information +6. **Status Indicator:** The status indicator will display information regarding various UGV status monitors such as the Emergency Stop, Surveying, etc. When the UGV is fully operational, the indicator - will be green. + will be green. Operators can click on the status indicator to see more details + pertaining to the current state as well as past messages. -6. **GPS Status Indicator:** The GPS status indicators will display GPS +7. **GPS Status Indicator:** The GPS status indicators will display GPS signal accuracy for position (POS indicator) and heading (DIR indicator). Green indicators represent RTK accuracy and are currently required for accurate autonomous navigation. Yellow and orange @@ -45,12 +51,6 @@ mode. oscillations may occur in such cases. Red indicators mean no GPS signal and autonomous navigation missions should not be started. -7. **ROS Status Indicator:** The ROS status indicator is used to give a - quick overview of the current status of the watched ROS topics. If - green it means that all topics are being received correctly while yellow - indicates that one or more topics is not being recieved. Further information - can be found in the status page by clicking on the ROS status indicator. - 8. **Battery Life Indicator:** The UGV's battery life indicator. :::note @@ -63,19 +63,24 @@ mode. 9. **Wireless Connection Indicator:** The wireless connection indicator represents the signal strength between the wifi access point - (typically the Base Station) and the UGV. + (typically the Base Station) and the UGV. If the system can support + cellular connections a cellular indicator will appear next to the + wifi icon with the currently active connection being highlighted in green. -10. **Views List:** A dropdown list of available views, detailed later +10. **Views List:** A dropdown list of available views, detailed later in this section. Some of the available views are Map, Camera and 3D views, etc. -11. **Mission List:** View the list of Missions that Operator(s) have +11. **Record Audio:** If the UGV is equipped with a microphone the user + can start/stop recording manually by clicking this icon. + +12. **Mission List:** View the list of Missions that Operator(s) have created. -12. **Edit Mission Toggle:** This toggle allows the user to start - creating Waypoints for the current Mission. The user will also be able to +13. **Edit Mission Toggle:** This toggle allows the Operator to start + creating Waypoints for the current Mission. The Operator will also be able to drag and drop Waypoints in this mode. Once this button is enabled, - the Waypoint Mode will now be available for selection. When a Mission is + the Waypoint Mode will be available for selection. When a Mission is started this toggle will be disabled (ie. the Operator will not be able to modify/add Waypoints). @@ -86,23 +91,20 @@ mode. ::: -13. **Waypoint Panel Toggle:** View list of Waypoints in the current Mission. +14. **Waypoint Panel Toggle:** View list of Waypoints in the current Mission. -14. **Waypoint Drop Button:** The Waypoint indicator marker on the - bottom bar allows the user to place a Waypoint at the location of the UGV. +15. **Waypoint Drop Button:** The Waypoint indicator marker on the + bottom bar allows the Operator to place a Waypoint at the location of the UGV. -15. **Start Button:** Start the current Mission. +16. **Start Button:** Start the current Mission. -16. **Pause Button:** Pause the current Mission. Pressing the start button +17. **Pause Button:** Pause the current Mission. Pressing the start button while paused will continue the current Mission. -17. **Stop Button:** Cancel the Mission or Task that is currently being +18. **Stop Button:** Cancel the Mission or Task that is currently being executed. Pressing the start button while when stopped will restart the list of steps in the current Mission. -18. **Feedback Bar:** The feedback bar will display information - regarding the execution state of the navigation and of any Tasks - being executed. By opening the dropdown list "Views", on the right side of the UI, the Operator can access the following views: @@ -226,6 +228,43 @@ acquired by the VLP-16 LiDAR. ## System Configuration +### General Settings + +The General settings section can be found in through the upper left hand menu and allows the Operator to modify +general features of the UGV. + +
+
+ +
General Settings Page
+
+
+ +#### Coordinates + +The Operator can change the coordinate space from X/Y relative to the Datum to Latitude/Longitude. + +#### Save Image Location + +The Operator can choose to store images saved manually to the robot directly or to download them onto their computer. This +feature only affects the manual save image option found on each relevant camera view. + +#### Robot Internet Connection Type + +If the UGV is equipped with SIM card and can switch between Cellular and WiFi connections, the Operator can manually trigger this +change through the general settings page. This switchover will take approximately 30 seconds and will require a refresh on the UI. + +#### Show Path Deviation Distance + +When a mission is running the UGV will have a maximum path deviation distance that it shouldn't cross if it needs to replan. If this +toggle is set to true, while in edit mode this buffer is shown over top of the path as the Operator creates/edits the mission. This +toggle does not disable the path deviation distance feature. + +#### Low Power Mode + +If the UGV is equipped with a Low Power Module this toggle allows the user to switch the UGV into a low power state that will drastically +limit functionality but help conserve power. This mode is best used to help better facilitate charging while the UGV is not in use. + ### Map Source Configuration The Web UI ships with access to free diff --git a/docs_versioned_docs/version-ros1noetic/robots/accessories/_category_.json b/docs_versioned_docs/version-ros1noetic/robots/accessories/_category_.json index a3bd73f0..78c643b7 100644 --- a/docs_versioned_docs/version-ros1noetic/robots/accessories/_category_.json +++ b/docs_versioned_docs/version-ros1noetic/robots/accessories/_category_.json @@ -1,4 +1,4 @@ { "label": "Accessories", - "position": 5 + "position": 6 } diff --git a/docs_versioned_docs/version-ros1noetic/robots/accessories/manipulators/kinova_gen3_lite.mdx b/docs_versioned_docs/version-ros1noetic/robots/accessories/manipulators/kinova_gen3_lite.mdx index 89c82b29..e1da8230 100644 --- a/docs_versioned_docs/version-ros1noetic/robots/accessories/manipulators/kinova_gen3_lite.mdx +++ b/docs_versioned_docs/version-ros1noetic/robots/accessories/manipulators/kinova_gen3_lite.mdx @@ -18,7 +18,7 @@ import TabItem from "@theme/TabItem"; | Description | CPR Item | | :------------------------- | :------------------------------------------------------: | -| Kinova Gen3 lite Bundle | [022586](/assets/pdf/clearpath_robotics_015822-TDS1.pdf) | +| Kinova Gen3 lite Bundle | [022586](/assets/pdf/clearpath_robotics_022586-TDS2.pdf) | | Kinova Gen3 lite, PACS™ kit | 027219 | --- diff --git a/docs_versioned_docs/version-ros1noetic/robots/common/_category_.json b/docs_versioned_docs/version-ros1noetic/robots/common/_category_.json index 4b52dda0..44fea45e 100644 --- a/docs_versioned_docs/version-ros1noetic/robots/common/_category_.json +++ b/docs_versioned_docs/version-ros1noetic/robots/common/_category_.json @@ -1,4 +1,4 @@ { "label": "Common", - "position": 5 + "position": 7 } diff --git a/docs_versioned_docs/version-ros1noetic/robots/legacy/_category_.json b/docs_versioned_docs/version-ros1noetic/robots/legacy/_category_.json index 158ad32d..2db18d85 100644 --- a/docs_versioned_docs/version-ros1noetic/robots/legacy/_category_.json +++ b/docs_versioned_docs/version-ros1noetic/robots/legacy/_category_.json @@ -1,4 +1,4 @@ { "label": "Legacy", - "position": 4 + "position": 5 } diff --git a/docs_versioned_docs/version-ros1noetic/robots/outdoor_robots/husky/tutorials_husky.mdx b/docs_versioned_docs/version-ros1noetic/robots/outdoor_robots/husky/tutorials_husky.mdx index 2fc8c6f4..cbab07e6 100644 --- a/docs_versioned_docs/version-ros1noetic/robots/outdoor_robots/husky/tutorials_husky.mdx +++ b/docs_versioned_docs/version-ros1noetic/robots/outdoor_robots/husky/tutorials_husky.mdx @@ -52,14 +52,14 @@ to upgrade the robot OS environment to Ubuntu 20.04 with ROS Noetic. [Husky Software Setup](#husky-software-setup) outlines the steps for setting up the software on your Husky robot and optionally on a remote computer. -[Using Husky](#using-husky) describes how to simulate and drive your Husky. [Simuation](#simulating-husky) +[Using Husky](#using-husky) describes how to simulate and drive your Husky. [Simulation](#simulating-husky) is a great way for most users to learn more about their Husky; understanding how to effectively operate Husky in simulation is valuable whether you are in the testing phase with software you intend to ultimately deploy on a physical Husky, or you do not have one and are simply exploring the platform's capabilities. [Driving Husky](#driving-husky) covers how to teleoperate Husky using the remote control, as well as safety procedures for operating the physical robot. Anyone working with a physical robot should be familiar with this section. -[Navigating Husky](#navigating-husky) is a follow-on to what is learned in the [Simuation](#simulating-husky) +[Navigating Husky](#navigating-husky) is a follow-on to what is learned in the [Simulation](#simulating-husky) tutorial, as navigation and map-making may be run in the simulated environment. However, this content is applicable to both the simulator and the real platform, if your Husky is equipped with a laser scanner. @@ -426,7 +426,7 @@ Then create your customized URDF file, for example `$HOME/Desktop/realsense.urdf RGB8 - + 0.01 50.0 diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/_category_.json b/docs_versioned_docs/version-ros1noetic/robots/solutions/_category_.json new file mode 100644 index 00000000..883cb910 --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Solutions", + "position": 4 +} diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/_category_.json b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/_category_.json new file mode 100644 index 00000000..90d538fc --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Husky Observer", + "position": 1 +} diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/integration_husky_observer.mdx b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/integration_husky_observer.mdx new file mode 100644 index 00000000..7fe83aed --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/integration_husky_observer.mdx @@ -0,0 +1,117 @@ +--- +title: Husky Observer Integration +sidebar_label: Integration +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Support from "/components/support.mdx"; +import ComponentCommonSoftwareIntegration from "/components/common_software_integration.mdx"; + +To attach custom hardware to Husky Observer, you will have to take care of mechanical mounting, electrical +supply, and software integration. This guide aims to equip you with respect to these challenges. + +## Mechanical Mounting + +Husky Observer has two PACS™-compatible mount points on the top of the robot, one at the front +and one at the rear, as outlined in the figures below. Each of the two mount points can support +a payload up to 5 kg. + +
+
+ + +
Husky Observer exterior, front view
+
+
+ +[PACS™](../../accessories/pacs) is a Clearpath Robotics standard. +We add a grid of M5x0.8 holes onto the top plate of the robot. +This grid of holes has a 80 mm X 80 mm spacing. +You can create your own brackets to interface with these holes, or can use an existing Clearpath Robotics designed bracket. + +:::note + +Our [Sensors](../../accessories/sensors) and [Accessories](../../accessories/add-ons) pages indicate the required bracket for the particular attachment. + +::: + +:::note + +When using the front and rear mount point, be careful to avoid blocking the field of view of +the 3D LiDAR. If you have any related questions, please contact [Support](#support). + +::: + +--- + +## Electrical Integration + +Except for bus-powered USB cameras, most payloads have separate leads for power and data. + +### Maintenance and Debugging Connections + +On the Husky Observer lid, there are three data interfaces that can be used for system maintenance +and debugging: + +- One 1 Gbps Ethernet (RJ45 connector), connected to the Main Computer +- One USB 3.0 (Type A connector), connected to the Main Computer +- One HDMI, connected to the Main Computer + +### Custom Payload Connections + +On the Husky Observer lid, there is an Icotek KEL-FG-ER-E3 connector with three cable glands that will allow the user to +create and route power cables from custom payloads on the lid to power sources inside the Husky Observer +while still maintaining the IP rating of the robot. (See +[this video](https://www.youtube.com/watch?v=xVLlroSRH7E&t=1s&ab_channel=icotek) +for more details on using the Icotek cable glands system.) + +Inside the Husky Observer, power is available from terminal blocks as outlined in the table below. +For each power source, 18 AWG wires with ferrules (DigiKey P/N 277-2156-ND) are recommended for power cables +at the end that gets inserted into the terminal blocks. Note that positive and negative wires are connected +to separate terminal blocks. + +| Power Source | Maximum Current | Terminal Blocks | +| :-------------------- | :-------------- | :--------------------------------- | +| VBAT (24.0 V minimum) | 3.75 A | Brown (positive), Black (negative) | +| 24 V | 2.5 A | Grey (positive), Black (negative) | +| 12 V | 3.5 A | White (positive), Black (negative) | + +
+
+ +
Power distribution terminal blocks
+
+
+ +In addition to the power connections, the cable glands can be used to make data connections to +available ports on the Ethernet switch or to available USB ports on the Main Computer. When +connecting a device to the Ethernet switch, the device should be configured with a static IP +address in the 192.168.131.80 to 192.168.131.89 range. + +--- + +## Software Integration + + + +Refer to the following for more details: + +- [Sensors](../../accessories/sensors) +- [Accessories](../../accessories/add-ons) + +--- + +## Support {#support} + + diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/maintenance_husky_observer.mdx b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/maintenance_husky_observer.mdx new file mode 100644 index 00000000..c7ab1a26 --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/maintenance_husky_observer.mdx @@ -0,0 +1,326 @@ +--- +title: Husky Observer Maintenance +sidebar_label: Maintenance +sidebar_position: 4 +--- + +import GettingNewPackages from "/components/maintenance/getting_new_packages.mdx"; +import ComponentUpdatingPumaFirmware from "/components/maintenance/firmware_update_puma.mdx"; +import Support from "/components/support.mdx"; + +## Hardware Maintenance + +### Charging the Robot {#charging} + +The robot can be charged wirelessly with the Autocharge Dock or with a wired +connection with the Manual Charger. + +#### Autocharge Dock + +The operator can start charging the robot using the autocharge dock in two ways, +noting that the robot will only charge on the dock when the disconnect is in the +"ON" position. + +- Manually drive the robot to its position at the dock. The receiver on + the robot should be properly aligned with the circle on the dock transmitter. +- Use the OutdoorNav UI to dock the robot autonomously. Please consult + [Autonomous Missions](#autonomous-missions) for further details. + This method requires that the [base station has been surveyed](#survey-base-station), + the [Datum has been set to the coordinates of the test site](#set-datum), + and that the [dock location has been set](#set-dock-location). + +:::note + +At ambient temperatures above 35 °C, there may be some automatic throttling +of the charge rate when using the autocharge dock. No user intervention is +required as the system will charge at the maximum possible rate based on +the internal temperatures in the robot. + +::: + +:::note + +By default, the autocharge dock is configured to disable charging at ambient temperatures below +0 °C. It is possible to perform charging at ambient temperatures as low as -10 °C +in some cases. Contact [Support](#support) for details. + +::: + +#### Manual Charger + +The Manual Charger may be used when the robot is far from its wireless +charger or when a faster charge rate is desired. For fastest charging, +turn off the robot while charging. + +- Plug the manual charger into an AC outlet and wait for the power + light to turn solid **BLUE**. +- Remove the cap from the manual charging port (rear of robot) by + squeezing the two cap sides and lifting. +- Connect the manual charger plug into port. + +After a moment the **ORANGE** +"lightning bolt" will illuminate on the charger indicating that charging +has begun. The **GREEN** battery level +indicator on the charger will also flash. When both segments of this +indicator turn solid, charging is complete. + +Be sure to replace the charge port cap when charging is complete. This +will protect the connectors from environmental conditions. + +### Balancing Batteries + +The robot's batteries must be balanced on a regular basis to ensure accurate +feedback, consistent performance, and long life. If the batteries are +allowed to fall out of balance, they will become unevenly loaded. This can +lead to back-feeding between batteries, reduced charge-holding capacity +for the system as a whole, and increased stress on both batteries. +If the imbalance becomes severe enough, one of the system batteries +will enter a protective state and disconnect itself from the system. +Once the battery enters this state there is a limited time window to +recover it. If that window expires the battery will become irreversibly +damaged with no possibility of recovery. + +Battery balancing is a slow process that will occur automatically when +the fully-charged batteries are held at their float voltage. Because the +automatic charger will shut off when it determines that the batteries are +fully charged, the system cannot be balanced using the autocharge dock. +The manual charger must be used. + +To perform a "quick" balance, leave the robot plugged into the manual +charger overnight. A quick balance is recommended at least once per week. +A full balance of 24+ hours is recommended at least once per month. + +Contact Clearpath Robotics for assistance with recovering a battery that +has entered a protective state. + +### Checking Battery Health + +A regularly-balanced battery system can be recharged thousands of times +before degrading. Eventually, however, the batteries will degrade (their +usable capacity will decrease). This translates to reduced run-time and +range. The robot will need to be recharged more frequently and overall +system availability will be reduced. + +It is recommended that the system operator review runtime performance +once per year to determine whether battery replacement is required. +Runtime measurements should be taken immediately after a full balancing +operation. Battery replacement is performed by Clearpath Robotics and +is subject to battery availability. Replacement batteries may be +purchased in advance and warehoused at Clearpath for future use. + +### Checking Drivetrain Health + +Depending on the environment in which the robot is used in and duty cycle, +the robot drivetrain may require maintenance during its life. Maintenance +activities can include gearhead replacement, tire tread replacement, motor +brush replacement, belt replacement, bearing replacement, etc. + +It is recommended that the user perform an auditory inspection of the +robot drivetrain once per month. Take note of any clicking, grinding or +irregular skipping sounds while the robot is moving. Note that some clicking +in the gearheads is normal during stops and starts, due to backlash between +the gears. + +### Checking Wheels + +Tire pressure may change with temperature and should be checked monthly +with a pressure gauge. Inspecting tires, releasing pressure, and inflating +tires are completed through the tire's inflation stem. Tire pressure should +not exceed 138 kPa ( 20 psi ), and lower pressure may be desired based on +terrain requirements. + +A monthly visual inspection of the tire treads is also recommended. +Replacement wheel assemblies can be purchased from Clearpath Robotics and +can be installed by the user. + +If a tire must be removed, first unfasten the four +M5 Socket Head Cap Screws that join the wheel to the axle hub, then slide +the wheel off the axle. When replacing the wheel, screws should be +lubricated with Loctite® 243 and then tightened to 5 N·m ( 3.7 ft-lb ) +torque. + +### Cleaning LiDARs + +The lenses of both the 2D and 3D LiDARs must +be cleaned on a regular basis. Contamination of the 3D LiDAR +can result in a "stuck" robot and sub-optimal navigation performance. +Contamination of the 2D LiDAR can result in poor docking +performance and inability to automatically maintain battery charge. + +Once per week or as required, visually inspect the lenses for dust or +dirt. Use a clean microfiber cloth to gently wipe away any contaminants. +Do not use cleaners or chemicals on the LiDAR lenses, as they may damage +the optical coating. + +### Cleaning Cameras + +The robot's camera lenses should be cleaned at least once per month. +The cleaning procedure is the same as that for the LiDAR lenses. + +### Cleaning Dock Target + +During the autonomous docking process, the white material of the dock +target provides high remission from the Sick LMS-111 laser scanner. +Over time, as the material is exposed to the elements dust/particles +may build up on the white plastic part of the dock target and will +require some maintenance. + +This maintenance simply consists of cleaning the white plastic panels +with a microfiber cloth. Ensure that the surfaces are clear of any dust, +dirt and/or any other particulate matter. + +### Cleaning or Replacing Fan Filters + +#### Bottom Fan Filters + +The fans between the Husky Observer wheels are intake fans with filters. +These filters require periodic maintenance to clean or replace the filters. +In very dusty off-road environments, these filters should be inspected +after every 20 hours of use and replaced as needed. In typical environments, +the fan filters should be inspected after every 50 hours of use and replaced +as needed. + +To replace the filters: + +1. Remove the four screws holding the fan cover panel in place as shown in the image below. +
+
+ +
Bottom fan cover panel screws
+
+
+1. For each of the two fans, remove the 4 screws holding the fan filter in place. +1. Remove the fan filters and replace with new filters. (See Mouser P/N 562-09250-F/100) +1. Install the screws holding the fan filters in place. +1. Install the screws hold the fan cover panel in place. + +#### Top Fan Filters + +The top fans on the front side of Husky Observer are intake fans with filters. +These filters require periodic maintenance to clean or replace the filters. +In very dusty off-road environments, these filters should be inspected +after every 50 hours of use and replaced as needed. In typical environments, +the fan filters should be inspected after every 100 hours of use and replaced +as needed. + +To replace the filters (repeat the steps below for each fan): + +1. Remove the four screws holding the fan cover screen in place as shown in the image below. +
+
+ +
Top fan cover panel screws
+
+
+1. Remove the fan cover screen. +1. Open the top lid of Husky Observer and pull out the fan assembly from the inside. +1. Remove the fan filter and replace with new filter. (See DigiKey P/N 1570-1461-ND) +1. Install the fan assembly from the inside. +1. Put the fan cover screen in place. +1. Install the four screws holding the assembly together. + +The top fans on the rear side of Husky Observer are exhaust fans and, as such, +the filters on those fans do not require regular maintenance. + +--- + +## Software Maintenance {#software_maintenance} + + + +### MCU Firmware Update + +Customer updates of Husky firmware are not supported at this time. Contact [Support](#support) if +Husky firmware updates are needed. + +### Motor Controller Firmware Update {#maintenance_husky_motor_controller_firmware} + + + +--- + +## Storage, Shipping, and Disposal + +### Storing Husky Observer for Extended Periods + +All batteries self-discharge over time. To minimise the risk of battery +state-of-charge dropping to a dangerously low leve while in storage, the +robot should be fully-charged and fully-balanced before being put into storage. +In addition, batteries in long-term storage will need to be recharged +every 6 months. + +The rate of discharge should also be minimised by disconnecting the batteries +from the rest of the system. This is achieved by means of a disconnect switch +in the robot's rear panel. Turn this switch to "OFF" prior to storing the +robot for long periods. + +### Preparing Husky Observer for Shipping + +The following should be considered when preparing to ship the robot and its +associated equipment: + +- Risk of equipment damage due to shock, vibration and impact +- Risk of equipment damage due to extreme temperatures +- Risk of equipment damage due to contamination, including liquid ingress +- Risk of equipment damage and injury due to over-charged or over-discharged lithium-ion batteries +- Risk of injury as a result of imbalanced or shifting loads +- Risk of environmental damage due to invasive species and/or hazardous material release + +Note the shipping temperature ranges and ingress protection ratings in the +[System Specifications](user_manual_husky_observer#system-specifications). +Secure all equipment using appropriately-rated rigging. +Protect the equipment from mechanical damage, liquid ingress and exposure to +caustic environments (including sea air). If lumber is used, ensure that it +has been appropriately treated to prevent the spread of invasive species. + +Lithium-ion batteries (which includes the robot's integrated lithium iron +nanophosphate batteries) are considered dangerous goods in many jurisdictions. +Ensure that the appropriate dangerous goods signage and paperwork is in place +prior to shipping the robot (as applicable). Note that the wireless motion-stop +system includes two small stand-alone lithium-ion batteries, and the remote +control gamepad includes an integrated lithium-ion battery. + +Some jurisdictions require battery states of charge to remain within a certain +band during transport. Consult local regulations. + +For short-duration transports lasting up to several days, it is recommended +that all batteries be charged to the maximum state of charge permitted by +applicable regulations. Disconnection of the robot's internal batteries is not +required. + +For longer-duration transports more than several days, the guidelines for +extended storage should be followed (to the degree allowable by applicable +regulation). + +### Disposing of Husky Observer + +
+ +
+ +The robot and associated equipment contain materials that should not be +disposed of in a landfill. These include lithium-ion batteries and leaded +solder, and may include cadmium, toxic lubricants and adhesives, and +other materials that can be harmful to people, animals and ecosystems. + +All printed circuit board assemblies, wiring harnesses and other +electronics components such as sensors, computers, human-machine +interface components, lights and motors should be treated as "e-waste" +and disposed of in accordance with local regulations. Lithium-ion +batteries should be treated as hazardous goods and disposed of in +accordance with local battery disposal regulations. + +--- + +## Support {#support} + + diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/troubleshooting_husky_observer.mdx b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/troubleshooting_husky_observer.mdx new file mode 100644 index 00000000..49bfa920 --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/troubleshooting_husky_observer.mdx @@ -0,0 +1,33 @@ +--- +title: Husky Observer Troubleshooting +sidebar_label: Troubleshooting +sidebar_position: 5 +--- + +import Support from "/components/support.mdx"; + +Refer to [Husky Troubleshooting](../../../robots/outdoor_robots/husky/troubleshooting_husky) and +[OutdoorNav Frequently Asked Questions](/docs_outdoornav_user_manual/faq) for +troubleshooting tips related to the base Husky and to the OutdoorNav software. +Additional topics related to Husky Observer are outlined below. + +## System + +1. **The E-stop light is illuminated. How do I resolve this?** + + This light indicates that one of the E-stop sources (4 on the robot, one + remote) is activated. Once all sources have been deactivated, the light + will turn off. + +1. **The joystick does not seem to work well. How do I resolve this?** + + The joystick is intended for operation and debugging when in close proximity + to the robot. It should be functional at a range of up to 10 meters, when there is direct + line of sight from the joystick to the robot. Note that the OutdoorNav UI virtual joystick is + intended to be the primary way to perform teleoperation of the robot for larger ranges. + +--- + +## Support {#support} + + diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/tutorials_husky_observer.mdx b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/tutorials_husky_observer.mdx new file mode 100644 index 00000000..e247cff4 --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/tutorials_husky_observer.mdx @@ -0,0 +1,47 @@ +--- +title: Husky Observer Tutorials +sidebar_label: Tutorials +sidebar_position: 3 +--- + +import ComponentIntroductionHuskyObserver from "/components/introduction_husky_observer.mdx"; +import Support from "/components/support.mdx"; + + + +## Husky Observer Overview + +### Introduction + +Husky Observer is a fully integrated system that enables robotics developers to accelerate inspection solutions. +It is built on top of the versatile [Husky](../../../robots/outdoor_robots/husky/user_manual_husky) base platform +The tutorial topics are listed in the right column and presented in the suggested reading order. + +For more information or to receive a quote, please [visit us online](http://clearpathrobotics.com/husky). + +:::note + +These tutorials assume that you are comfortable working with ROS. We recommend starting with our +[ROS tutorial](https://www.clearpathrobotics.com/assets/guides/noetic/ros/index.html) if you are not familiar with ROS already. + +::: + +:::note + +The Husky Observer is built on the the Husky platform. See also the [Husky Tutorials](../../../robots/outdoor_robots/husky/tutorials_husky#husky-ros-packages). + +::: + +--- + +## Using Husky Observer {#using-husky-observer} + +### Simulating Husky Observer {#simulating-husky-observer} + +To simulate the Husky Observer, including its full navigation stack, contact [Support](#support). + +--- + +## Support {#support} + + diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx new file mode 100644 index 00000000..cfe4e3fb --- /dev/null +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx @@ -0,0 +1,1649 @@ +--- +title: Husky Observer User Manual +sidebar_label: User Manual +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import ComponentIntroductionHuskyObserver from "/components/introduction_husky_observer.mdx"; +import Support from "/components/support.mdx"; +import ComponentUsingRos from "/components/using_ros.mdx"; +import ComponentCommonSafeWorkProcedures from "/components/common_safe_work_procedures.mdx"; +import ComponentSafetyWarning from "/components/safety_warning.mdx"; +import ComponentPs4ControllerPairing from "/docs_versioned_docs/version-ros1noetic/components/_ps4_controller_pairing.mdx"; +import ComponentChangingDefaultPassword from "/docs_versioned_docs/version-ros1noetic/components/_changing_default_password.mdx"; +import ComponentWiredRobotConnection from "/docs_versioned_docs/version-ros1noetic/components/_wired_robot_connection.mdx"; +import ComponentPerformingABackup from "/docs_versioned_docs/version-ros1noetic/components/_performing_a_backup.mdx"; +import ComponentInstallingRemoteComputerSoftware from "/docs_versioned_docs/version-ros1noetic/components/_installing_remote_computer_software.mdx"; + + + +## Introduction + +Husky Observer is a fully integrated system that enables robotics developers to accelerate inspection solutions. +Built on top of the versatile [Husky](../../../robots/outdoor_robots/husky/user_manual_husky) base platform, +Husky Observer enables robotics developers to fast-track their system development. With it, you can get your test +application running faster without worrying about autonomous navigation and sensor integration. + + + +### Shipment Contents + +Your Husky Observer shipment contains the following: + +- Husky Observer robot +- Lockout keys (2X) +- Wireless charging transmitter and dock +- Wired charging adapter +- PS4 controller (for manual operation) +- Tablet (optional) +- Base Station (optional) + power supply + +If you purchased standard payload modules or custom integration services with Husky Observer, then additional equipment will +be included per your specific configuration, plus further documentation as required. + +### Hardware Overview + +#### System Architecture + +Husky Observer is built around a computer running Ubuntu, paired with a 32-bit microcontroller MCU. +The MCU handles power supply monitoring and motor control, with all remaining processing handled by the computer. +The communication channel between the MCU and computer is a serial connection. + +#### Exterior Features {#exterior-features} + +The Husky Observer exterior is shown below and includes: + +- Pan-tilt-zoom (PTZ) camera +- Thermal camera (optional) +- Shotgun microphone (optional) +- Antennas (cellular, wifi, GPS, safety) +- Stack lights +- 3-D LiDAR +- Expansion connectors (power, ethernet, USB) +- Front and rear expansion mount points +- Front (standard) and rear (optional) 2-D LiDARs +- Front and rear depth cameras +- Motion stop buttons and lockout +- Omnidirectional microphone +- Front and rear driving lights +- Wireless charging receiver +- Wired charge connector +- Main power switch +- Status panel + +
+
+ +
Husky Observer exterior, front view
+
+
+ +
+
+ +
Husky Observer exterior, rear view
+
+
+ +#### Stack Lights {#stack-lights} + +The stack lights are composed of two lights, the details of which are described below. + +- The bottom is an orange strobe light that is enabled when the robot is in motion or may soon be in motion; + personnel near the robot should exercise caution when this light is strobing. +- The top is a multi-colour light that indicates the system status. + +| Strobe Light (bottom) | Status Light (top) | Robot State | +| --------------------- | ------------------ | ---------------------------------------------------------------------------------------------- | +| Off | Red | Motion stop engaged; robot prevented from moving. | +| Off | Purple | A system error/warning exists; see the [OutdoorNav UI](#monitoring-system-status) for details. | +| Off | Cyan/White | Battery charging in progress and battery over 98% charged (as reported in OutdoorNav UI). | +| Off | Cyan/Green | Battery charging in progress and battery 58% to 98% charged (as reported in OutdoorNav UI). | +| Off | Cyan/Yellow | Battery charging in progress and battery 16% to 58% charged (as reported in OutdoorNav UI). | +| Off | Cyan/Red | Battery charging in progress and battery less than 16% charged (as reported in OutdoorNav UI). | +| On | Yellow | Low battery (battery less than 16% charged). | +| On | Green | Robot is driving (teleop mode). | +| On | Blue | Robot is driving (autonomous mode). | +| On | White | Robot is ready to drive, but currently idle. | + +The Stack Lights can also be visible in the UI in both the upper right hand corner and as a widget in the status page. + +
+
+ +
Stack Light Widget (1) found in the Status Page and Stack Light Icon (2) found in the Navigation Bar
+
+
+ +See also additional status as reported in the [Status Panel](#status-panel). + +#### Status Panel {#status-panel} + +The status panel, which complements the [Stack Lights](#stack-lights), is a display of LED indicators located on the rear of +the chassis that provides information about the current status of Husky Observer. The indicators are described in the table below. + +| Icon | Description | +| :----------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | **Battery Status** This is not used on Husky Observer. Refer to the battery state indicator in the OutdoorNav UI or on the stack light instead. | +| | **Communication Status** When green, Husky Observer is receiving a stream of correctly-formatted motion commands, and is ready to drive. When yellow, Husky Observer is receiving commands, but will not drive due to motion stop or another error. When red, serial communications are currently timed-out. | +| | **General Error Status** Illuminates red when Husky Observer will not drive due to an error state. Such states include motion stop, insufficient battery power, or an unspecified software error. | +| | **Motion Stop Status** Illuminates red when Husky Observer will not drive due to the motion stop being activated, either onboard or wireless (if available). | +| | **Charge Indicator** Illuminates red when Husky user power is being supplied externally. | + +#### Switches and Buttons + +##### Main Power Switch + +On the rear of the robot, the main power switch can be used to turn the entire system OFF and ON. + +
+
+ +
Husky Observer ON/OFF switch
+
+
+ +##### Motion-stop Buttons + +There are four motion-stop buttons on the robot, one at each of the four corners. Depressing any +of these four buttons will engage motion-stop and remove power from the robot motors. Refer +to the [Safety](#safety) section for further details. + +##### Motion-stop Override Key Switch + +In addition to the motion-stop buttons on the robot, if your Husky Observer is equipped with a wireless motion-stop function, +it is possible to disable this function with the override key switch. Refer to the [Safety](#safety) section for further details. + +#### Payloads + +Additional payloads can be integrated with Husky Observer, either as part of your purchase or installed after receiving your Husky Observer. +Refer to [Husky Observer Integration](integration_husky_observer) for details on how to integrate your own payload or how to integrate a payload kit from Clearpath Robotics. +Each payload kit that ships from Clearpath Robotics comes with a custom mounting bracket and cabling for easy attachment to Husky Observer. + +#### Orientation References + +The reference frame used by all Clearpath Robotics ground robots is based on ISO 8855, and is shown in the figure below. +Husky Observer's front is shown. +When commanded with a positive translational velocity (forward), wheels travel in the positive X-direction. +The direction of the axes differs from those used for roll, pitch, and yaw in aircraft, and care should be taken to ensure that data is interpreted correctly. + +
+
+ +
Husky Observer orientation references
+
+
+ +### System Specifications + +| Specification | Measurement | +| :---------------------------- | :--------------------------------------------------------------------------------------------- | +| Dimensions | 1061 mm (length) X 854 mm (width) X 1224 mm (height) | +| Track Width | 550 mm | +| Wheelbase Length | 512 mm | +| Ground Clearance | 130 mm | +| Mass | 98.5 kg | +| Maximum Payload | 10.0 kg | +| Speed, Maximum | 1.0 m/s | +| Climb Grade | 15 ° | +| Traversal Grade / Sideslope | 15 ° | +| Ambient Operating Temperature | -10 to + 40 °C | +| Environmental | Designed for IP55 | +| Operating Time, Typical | 2.5 to 3.25 hours | +| Operating Time, Standby | 4.0 hours | +| Battery | 35 Ah @ 24 V, LiFePO4 | +| Wireless charging | Up to 300 W (approximately 4 hours to charge from 10 to 85% when powered on in low power mode) | +| Wired charging | 650 W (approximately 1 hour to charge from 10 to 85% when powered off) | +| Expansion | 2.5 A @ 24 V, 3.5 A @ 12 V, 3.75 A @ VBAT, USB 3.0, Ethernet (data only, 1 Gbps), HDMI | + +
+ +
+ +--- + +## Safety {#safety} + +### General Safety Notices + +#### Important Safety Information + +
+ +
+ +#### General Hazard Labels + +Review the following to learn more about the labels that may be used on Clearpath Robotics products. Hazards +can also apply to attachments and accessories used in conjunction with a Clearpath Robotics product. + +| **Label** | **Label Title** | **Label Description** | +| :----------------------------------------------------------------------------------: | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| | Automatic Motion Hazard | Clearpath Robotics robots may suddenly begin moving autonomously or when being driven manually. Always be aware of Clearpath Robotics products and their potential for movement. | +| | Crushing Risk | Objects or personnel can be crushed between the Clearpath Robotics robot and another object. Keep hands and other objects clear of crush points at all times. Keep clear of all docking Clearpath Robotics robots. | +| | Electrical Shock Risk | Clearpath Robotics robots contain circuitry and batteries that may cause electrical shock if not properly insulated. | +| | Entanglement Risk | Clearpath Robotics robots as well as their sensors can lead to entanglement for hair or dangling materials during their rotation. Keep dangling materials/hair away from Clearpath Robotics robots during motion. | +| | Environmental Hazard | Clearpath Robotics robots contain batteries and materials that may require special disposal methods. Consult local regulations. | +| | Falling Object Risk | Beware of objects that may have shifted in any Clearpath Robotics robot crate as they pose a risk of falling when opened. | +| | High Surface Temperature Risk | Robot PC heat sinks and robot motors can become extremely hot during operation. | +| | Impact Risk | Clearpath Robotics robots travelling through a facility can potentially impact objects and personnel. Keep clear of all docking Clearpath Robotics robots. | +| | Laser Radiation Risk | Clearpath Robotics robots may use Class 1 laser products. These provide no hazard during normal use, however it is not recommended to stare directly into the beam(s). | +| | Material Hazard - Lithium | Robot batteries contain harmful material. Always use proper handling procedures when handling robot batteries. | +| | Manual Load Lifting Risk | Always use ergonomic techniques when manually lifting loads. | +| | Pinching Risk | Keep hands and other objects clear of pinch points at all times. Keep clear of all docking Clearpath Robotics robots. | +| | Radio Frequency Risk | Clearpath Robotics robots and/or accesories may use radio frequency (RF) radiating antennas. These provide no hazard during normal use, however prolonged exposure around the antenna is not recommended. | +| | Tripping Hazard | Clearpath Robotics products may pose a tripping hazard. | + +#### Safety Awareness + +Personnel present during the operation of a Clearpath Robotics robot need to be made aware or be accompanied by personnel who +are familiar with the specific risks and hazards associated with automated mobile robots (AMR). +The following checklist identifies basic topics that should be addressed by site-specific worker and visitor +safety orientation training. + +
+ +
+ +- Proper PPE must be worn, including safety footwear (ie. steel toe). +- Crossing into the path of a moving Clearpath Robotics robot should be avoided, as well as placing or throwing obstacles into the path of a moving Clearpath Robotics robot. + +
+ +
+ +- Be aware that a Clearpath Robotics robot can be anywhere in the operating area of the facility at any time, and may pose a tripping hazard even when not in motion. +- Personnel need to be aware of the Clearpath Robotics robot docking and charging areas, where detection fields are reduced. +- Personnel should be aware that Clearpath Robotics robot LiDAR safety scanners use a class 1 laser and high intensity LEDs. +- Personnel should keep all loose clothing and body parts away from Clearpath Robotics robots, accessories, attachments, and payloads, while they are in autonomous operation. Using a Motion Stop button is the only acceptable manner of interacting with a Clearpath Robotics robot or attachment while it is being operated autonomously. + +In addition to the preceding basic items for all workers and visitors, the following should be considered for facility personnel, including drivers of other robots: + +- When required to move a product manually, personnel must ensure it is in an Motion Stop state or shut down completely and should not push manually for prolonged periods. +- Alert personnel that while operating a Clearpath Robotics robot outside of the Autonomy State, they are solely responsible for obstacle and collision avoidance. +- Maintenance not outlined in either this document or the operations and maintenance manual can only be performed by a Clearpath Robotics Authorized Personnel. + +##### Operating Environment and Intended Use + +The autonomous mobile robot system is intended for use in: + +- indoor and outdoor industrial and commercial environments; +- environments free of vertical drops greater than 200 mm; +- environments free of fast-moving people or vehicles; +- environments free of glass or transparent plastic floors or walls; +- temperatures between -10 °C and +40 °C; +- environments free of open water or other liquids deeper than 20 mm; +- environments free of grades greater than 12%. + +The system is intended to be operated by trained personnel familiar with autonomous mobile robotic technology. +It is intended to be monitored constantly by those personnel during operation. + +The system is intended to be operated around trained personnel familiar with the hazards that the system presents. + +The system is intended to be operated in the as-furnished condition, without additional equipment, payload or passengers. + +#### Disclaimer + +It is the responsibility of the user to be familiar with all applicable safety standards and ensure that the hardware, +software, and/or services delivered by Clearpath Robotics (collectively referred to as the "Product") are maintained +and operated in a safe manner, in a suitable environment, and in accordance with the recommended maintenance requirements +prescribed by Clearpath Robotics. + +Without limiting the foregoing, it is the user's responsibility to ensure that personnel operating the Product are +adequately trained and comply with all laws, regulations, codes, and safe practices, including health and safety and +workers' compensation laws, applicable to the user's activities and its ownership, possession, and use of the Product. +Modification, removal or addition of components, or changes to the functionality or operation of the Product in any way, +except as expressly authorized by Clearpath Robotics, may jeopardize the safety of the Product. + +The robot system and its associated equipment, including all safety functions, are provided "as-is". Clearpath Robotics +makes no claim that the achieved residual risk to persons, property or animals is tolerable, or meets any generally-accepted +threshold. Residual risk is user- and use-specific. Evaluation of tolerable residual risk is subjective. + +Clearpath makes no claim that the degree of safety function reliability is commensurate with the degree of risk reduction +those safety functions ostensibly provide. The system operator is responsible for the safe use of the robot system and +associated equipment. Clearpath disclaims all responsibility for injury to persons or animals, or damage to property +resulting from the use of the robot system and its associated equipment. + +Additional review by local Authorities-Having-Jurisdiction, Nationally-Recognised Testing Laboratories, Notified Bodies, +or others may be required to establish that the system as-used achieves tolerable residual risk. The operator is responsible +for additions or modifications to the system that may be mandated or recommended by third-parties. Clearpath may provide +system documentation to support a third-party review, but shall not be held responsible for meeting third-party expectations +for content, completeness, style or conformance to any standard. + +If at any time you have any questions or concerns regarding the safe operation of your Clearpath Robotics product, +contact [Support](#support). + +#### Recommended Safe Work Procedures + + + +### Husky Observer Safety Notices + +
+ +
+ +#### Unexpected Motion + +Autonomous and teleoperated robots may begin moving, stop, or change direction unexpectedly. They may move in +an unintuitive way. Always maintain physical separation from the robot when it is in motion or capable of starting +motion. + +#### Sensor and Response Limitations + +The sensors that the mobile robot uses to navigate within its environment and avoid obstacles have limited performance. +Examples of common limitations include range, fidelity, response speed, and refresh rate. Some sensors, such as the +LiDARs used for collision avoidance, may be unable to detect some materials, such as glass. Always treat the robot +as a collision hazard. Proper maintenance/cleaning should be undertaken on the sensors to ensure their optimal performance. + +#### Stability, Traction, and Stopping Distance Limitations + +The robot's ability to take action in response to sensor input is also limited. The amount of traction the robot can +generate on different surfaces is limited, and may not be sufficient to maintain its position. For example, a robot +on an icy grade may slide uncontrollably. The reaction time and stopping rate of the robot is limited. The robot may +not have enough time to stop if an obstacle appears suddenly in the robot's path. Never run or jump into a moving +robot's path. Never operate the robot in environments other than those for which it is intended. + +#### Electrical Subsystem + +Husky Observer is powered by two 12 V Lithium-Iron-Phosphate (LiFePO4) batteries in series to make a 24 V pack. +These batteries are similar to the type found in electric wheelchairs, golf carts, fork trucks, and other devices. +Husky Observer's battery pack is capable of delivering 5565 W, three times the power of a standard wall outlet. +This gives Husky Observer's motors their great performance, however, it is also enough power to cause severe bodily harm. + +Note that the Husky Observer PDU has a 50 A fuse that limits the continuous power output to 1325 W. + +Please observe the following precautions: + +- Turn the Main Power Switch to "OFF" when working on Husky Observer's hardware. +- The Main Power Switch isolates the energy from the switch to the rest of the robot. + This potential energy is still present at the battery terminals, and the cable connecting the switch to the batteries. +- Do not tamper with the battery packs. +- Charge the battery only with the charger provided by Clearpath Robotics. +- Please dispose of the batteries properly according to local regulations. + +#### Lifting and Transport + +For the safety of users and to maximize the lifetime of Husky Observer, please observe the following when manually transporting the robot: + +- Husky Observer should be lifted by two persons, firmly gripping the front and rear bumper-bars. +- Ensure that Husky Observer is in Motion-Stop mode when transporting short distances and powered off when transporting longer distances. +- It is not advised to push Husky Observer, as this can cause damage to the motors. + +#### Performance Considerations + +Included in Husky Observer are native software checks and limits to protect the robot. +However, it is recommended to monitor the system's status during usage with the `/status` and `/diagnostics` topics +or through the OutdoorNav UI as described in [Monitoring System Status](#monitoring-system-status). +These topics provide useful information regarding voltages, currents, temperatures and general health of the system. + +The total current draw does not include the motors drivers; it is the current consumed by the MCU and user power ports. +Husky Observer's motors are rated to draw 10.7 A continuous, but they will spike to several times higher than this, +particularly when traversing rough terrain and when turning on the spot. +To reduce current draw, consider commanding wider-radius turns from your control software. + +The temperature is measured in the motor drivers and on the motor casings; the coils inside the motor casings cannot be measured. +Therefore, it is important to note that the temperature measured on the motor casings is a lagging indicator of the temperature of the coils inside the casing. +Be aware of the delay in heat propagation on the motors during heavy use. +The thermal limit of the system is 50 °C, and components of the system will begin to throttle or shut down if internal temperatures exceed this limit. +Monitoring these fields over longer periods of operation will allow you to ensure that you are not putting excessive wear on +Husky Observer's motors. + +### Husky Observer Safety Features + +#### Onboard Motion-Stop Function + +The mobile robot includes an onboard motion-stop function that allows a person in the physical vicinity of the robot to +halt its motion and prevent re-initiation of motion. This function can be asserted by pressing any one or more of the +four red stop actuators present around the periphery of the mobile robot as shown in the figure below. + +
+
+ +
Husky Observer motion-stop buttons
+
+
+ +The motion-stop function can be reset by twisting all depressed actuators until they return to an extended position. +**There is no second "start" action required to reset the stop function. The robot may begin moving again immediately +after the final stop actuator has returned to its extended position.** + +The onboard motion-stop system is intended for use in emergency situations. The motion-stop system should not be used +as the means of controlling robot motion during regular operation. + +#### Wireless Motion-Stop Function + +In addition to the onboard motion-stop function, the system includes a wireless motion-stop function. This function +allows a person who is physically separated from the robot to halt its motion and prevent re-initiation of motion. + +
+
+ +
Wireless motion-stop controller
+
+
+ +
Wireless motion-stop override
+
+
+ +To assert the stop function: + +- depress the red push-button actuator on the side of the provided controller. + +To reset the stop function: + +- twist the depressed actuator until it returns to its extended position; +- depress and hold for 1 second the black start button on the side of the controller. + +The wireless motion-stop function is automatically asserted if the robot is not able to communicate wirelessly +with the controller. This is to ensure that the stop function does not become unexpectedly non-operational as +a result of robot or operator motion, interference, atmospheric conditions, depleted battery, etc. The +controller must be powered and within range of the mobile robot to communicate. + +The wireless motion stop system is intended for use in emergency situations. The motion stop system should +not be used as the means of controlling robot motion during regular operation. + +The wireless motion-stop function (but not the on-board motion-stop function) may be overridden by means of +a key switch as shown in the figure above. This is to allow the robot to be operated **at higher risk** while, +for example, the controller battery is dead, out of range or not accessible. + +Operation of the mobile robot while the wireless motion-stop function is overridden **is not recommended**. +The system deployer/operator assumes all responsibility for injury to persons or animals, or damage to property, +arising from the inability to remotely stop the motion of the vehicle due to the use of this override. + +#### Motion Buzzer + +When Husky Observer is in motion in any direction, both in manual and autonomous modes, a buzzer will sound +to provide an audible warning to personnel in the nearby area. No configuration or operator action +is required to enable this feature. + +#### OutdoorNav Autonomous Obstacle Avoidance Function + +During and **only** during OutdoorNav missions (not during OutdoorNav Manual Mode), +the 3-dimensional LiDAR is used to perform obstacle avoidance to reduce the risk of the robot colliding with stationary or dynamic obstacles +in its environment. The navigation uses the robot's 3D LiDAR scanner to detect obstacles within a certain range. A gradual speed reduction +is asserted as the distance to the obstacle decreases and the robot will attempt to move around any obstacle it detects. This may happen +several times if the robot has navigated itself into a tight space surrounded by walls. No intervention from the user is required. + +The 3D LiDAR scanner used for obstacle detection has a 360° field-of-view in the horizontal plane, and a ±15° field-of-view in all +vertical planes with respect to the center of the lens as shown in the figure below. However, some regions of the scanned +envelope may be occluded by the robot itself. The LiDAR is unable to detect objects in these regions (and all regions outside the scanned +envelope). The obstacle avoidance feature will not respond if obstacles are within those regions. + +
+
+ +
3-D LiDAR field of view, plan, and elevation
+
+
+ +There are also gaps in LiDAR coverage due to the divergence of the laser beams in the vertical direction, and discrete sampling +in the horizontal direction. The divergence angle is 2° vertically between beams and 0.1 - 0.4° horizontally between samples +(depending on configuration). As a result the LiDAR may fail to detect the approach of slender or pointed objects. + +The LiDAR data is filtered to reduce false-positives. It is possible that this filtering could reduce the detectability of +certain objects. + +--- + +## Getting Started + +### Hardware Setup + +This section describes how to unpack the system and complete the hardware setup. + +#### Base Station Setup + +:::note + +The Base Station is an optional component. Skip this step if your system does +not include a Base Station. + +::: + +
+ +
+ +##### Base Station Location + +The location of the Base Station, particularly its antenna, will play a critical +role in the performance of the outdoor navigation software, especially at long +range. + +Below is a set of criteria in order of priority, for the location of the Base +Station, such that the performance of the networking/software is not degraded: + +- The Base Station should be secured as high as possible so that the GPS + antenna can accurately obtain a GPS signal and so that the network antenna can + propagate its radio waves without interference from nearby obstructions. + For example, a good location could be on the roof of a building or trailer. + +- A location on the ground (if no elevated location is available/accessible) + where the Base Station can be secured using the tripod that has been shipped with + the robot. If this location is selected, ensure that the tripod is secured a + minimum of 10 meters from any buildings or obstructions so that the GPS + antenna has a clear view of the sky. Recommended minimum height is 1.75 + meters from the bottom of the antenna to the ground. + +- A location where an Ethernet cable can be fed to to connect the Base + Station to the WAN (if WAN available). + +##### Base Station Orientation + +The robot and Base Station are both shipped with an omnidirectional antennas. +As such, there is no need to orient the Base Station to face the robot's +area of operation. + +##### Base Station Power + +The Base Station is powered by an internal battery. The Base Station also +includes a power supply that, when connected, will charge the battery. +When connected, the power supply can provide sufficient power both to +charge the battery and to operate the Base Station. + +To power on the Base Station, press the recessed silver power button on the +side of the enclosure. When powered, the button will illuminate blue. + +##### Internet over Base Station Network + +If a wired internet connection is available at the user facility, an +Ethernet cable can be run from an access point to the Ethernet port on the side +of the Base Station case. This will provide internet access for the robot +and the tablet. Note that there are two network ports on the side of the +Base Station; use the bottommost port for connecting the cable that provides +internet access. The other network port provides a local network connection +for debugging purposes only. + +Note that the connector on the Base Station is an M12 connector (Digikey +P/N 1754-1180-ND) and an Ethernet cable with a mating connector must be used +for providing internet access. + +#### Autocharge Dock Setup + +
+ +
+ +The Autonomous Docking software enables the robot to navigate toward the dock target +and autonomously approach the target to begin charging the robot's batteries. +The complete dock consisting of the target, the WiBotic charging unit (transmitter) +and the enclosing material can be seen in the figure below. + +
+
+ +
Autocharge Dock
+
+
+ +The robot requires open, flat, level ground in front of the dock to manoeuvre. +It must have GPS signal visibility (ie. not too close to any tall buildings or +trees) and clear line-of-sight to the dock target from all points in this +pre-dock region. Allow at least 8 meters from the "pointed" end of the dock and +a width of at least 4 meters, as shown in the figure below. + +
+
+ +
Dock Space Requirements
+
+
+ +The charge dock, including WiBotic wireless transmitter, ships pre-assembled. +Remove it from the crate and position it at the desired location. The concave +portion of the target points toward the robot when docked. + +The dock may be secured to the ground if desired. If the attachment points +are near the transmitter box, non-metallic fasteners and anchors should be +used to avoid magnetic interference with the charge system. + +##### Wireless Transmitter + +The WiBotic wireless transmitter ships pre-installed in the dock. To +complete the installation of the wireless transmitter: + +- Plug the wireless transmitter into a power terminal using the provided + power cord (an extension cord may be required). The transmitter requires + 90 - 264 V AC, 50 - 60 Hz. +- Power ON the wireless transmitter by pressing the switch on the side + of the transmitter. The **GREEN** + LED will light up when powered ON, flashing once every three seconds to + indicate idle mode. + +##### Wireless Receiver + +The WiBotic wireless receiver ships pre-installed on the Husky Observer robot +and does not require any customer assembly. + +#### Robot Setup + +##### Unpacking the System + +The total mass of the crated system is approximately 300 kg. + +
+
+ +
+
+ +It is recommended that the crate be loaded, unloaded, and transported +by fork truck or manual pump truck. The crate is not designed for lifting +by crane. + +
+
+ +
+
+ +The crate is assembled using 9/16" hex head screws. Both the front and rear +panels are held in place with 12 screws. They can be removed with a wrench or +impact driver with an appropriate 9/16" socket. + +The robot is held in place using ratcheting tie-down straps. Loosen the straps +on either side of the robot, and remove them from the crate. In the accessories +crate, there is a shelf which may be removed and used as a ramp. Place it behind +the robot, bridging the drop between the crate floor and the ground. The robot +may then be rolled out by pulling on the rear bumper. Make sure that the ramp +does not shift during this process. + +##### Installation of SIM Card (Optional) {#installation-of-sim-card} + +An LTE SIM card can optionally be installed into the robot to provide network +access when out of range of WiFi networks. A SIM card is not required if +Husky Observer is always being operated within range of WiFi networks. +Note that the SIM card (and corresponding data plan) is provided by the end user, +not by Clearpath Robotics. + +1. Open the lid on Husky Observer. +1. Locate the "Microhard" component, near the rear-left corner. +1. Insert the SIM card into the Microhard port labelled "SIM 1". +1. Refer to [Enabling LTE (Cellular) Networking on Robot](#lte-setup) for details on the software setup. + +#### Robot Startup + +
+
+ +
Robot main power switch
+
+
+ +When powering up the robot for the first time, follow these steps: + +1. Turn the Main Power Switch to the "ON" position. Note that this + switch is set to "OFF" prior to shipping to prevent battery drain during + shipping. +1. Wait 10-15 seconds for the startup checks to complete, at which point + LEDs on the Status Panel should illuminate and the system will begin booting. +1. Wait one to two minutes for the system to boot fully before proceeding. + The external light indicators on the rear of the robot will illuminate once + the system is powered. The "COMM" light will notify the user about the + status of the computer. The possibilities are: + + 1. **GREEN:** Communication with the computer is active/stable and robot is ready to drive. + 1. **YELLOW:** Communication with the computer is active/stable but Motion-Stop is engaged. Release the Motion-Stop. + 1. **RED:** No communication with the robot computer or ROS error. + +##### Charge State + +
+
+ +
+
+ +Use the OutdoorNav UI to determine the charge state of the robot batteries. + +##### Motion-stop State + +The state of the robot motion-stop function can be determined in two ways: +via the [Stack Lights](#stack-lights) and via the [Status Panel](#status-panel). + +The status stack light illuminates solid red when the motion-stop is engaged +and is off or a different color when motion-stop is not engaged. + +The second way to determine the motion-stop state of the robot is to inspect +the status panel on the rear side of the base Husky. +This panel includes "COMM" and "STOP" indicators. When a +motion-stop is asserted, the "COMM" indicator will illuminate +**YELLOW** and the "STOP" indicator +will illuminate **RED**. When the robot is +powered off the indicators will be off. When the robot is powered on and a +motion stop is not asserted, the "COMM" indicator will be illuminated +**GREEN** and the "STOP" indicator will +be off. + +#### Charging the Robot + +See [Maintenance](maintenance_husky_observer#charging) for details on charging the robot. + +#### Robot Expansion and Debug Ports + +As outlined in [Exterior Features](#exterior-features), the robot comes equipped with +additional ports (power, USB, Ethernet) that can be used for both +system expansion (eg. extra sensors) or for system debugging. All data connectivity is +to the main computer. See [Husky Observer Integration](integration_husky_observer) +for further details. + +### Base Husky Software Setup + +#### Wired Network Connection {#wired-network-connection} + +During setup or debugging, it may be desirable to connect to Husky Observer through a wired Ethernet connection. +After connecting an Ethernet cable from your laptop to the debug/expansion port as shown in the +[Exterior Features](#exterior-features), +follow the steps below to establish a network connection to the main computer. It is also possible +to access other components on the system using the appropriate IP address (refer to the +[Networking Configuration](#networking-configuration) for a full list). + + + +#### Changing the Default Password {#changing-default-password} + + + +#### Installing Remote Computer Software {#remote-computer-software} + +:::note + +This step is optional. + +::: + +:::note + +This step assumes that your laptop (ie. "remote computer") is already present +on the same subnet as the robot. See [System Networking Setup](#networking-setup) +and [Appendix A](#networking-configuration) for networking details. + +::: + + + +#### Connecting and Using the Controller {#controller} + +To use your controller, it must be paired with your Husky Observer and powered on. +Note that your controller is already paired with your Husky Observer when it ships. +If your controller has become unpaired or if you wish to pair a new controller, following the instructions in the +[Husky Tutorials](../../../robots/outdoor_robots/husky/tutorials_husky#pairing-the-controller). + +To teleoperate Husky Observer, first release the motion stop. Then, referring to the following image, press the +enable button (either slow or turbo mode) and use the left thumbstick to drive Husky Observer. + +
+
+ +
PS4 Controls Layout
+
+
+ +#### Using ROS + + + +### System Networking Setup {#networking-setup} + +#### Network Requirements + +To monitor and control Husky Observer, it must be integrated into a communication network. The main +requirements are: + +1. The user control device (tablet or laptop) must have network connectivity to the Husky Observer, + either over a local Wi-Fi network or over the internet (eg. cellular connection to the robot). +1. The user control device (tablet or laptop) must have access to the internet to be able to download + map tiles. (In advanced modes, it is possible to create your own map to avoid this requirement.) + +#### Network Modes {#network-modes} + +While there are many ways to meet the Network Requirements listed above, there are three common network +modes for deploying Husky Observer, which are outlined below. + +| Network Mode | Description | Base Station Setup | Robot Setup | Tablet Setup | OutdoorNav URL via Local WiFi | OutdoorNav URL via Internet/Cellular | +| --------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------- | +| Base Station | Base Station with WiFi for near-range operations; optional LTE also available on robot for long-range operations | Pre-configured at factory | Pre-configured at factory; see also [Enabling LTE (Cellular) Networking on Robot](#lte-setup) for optional setup | Pre-configured at factory | http://192.168.132.1:8080 | See [Remote Access Setup](#remote-access) | +| Customer WiFi Network | Customer WiFi for near-range operations; optional LTE also available on robot for long-range operations | N/A | See [Updating the WiFi SSID or Password on Robot](#robot-wifi-setup); see also [Enabling LTE (Cellular) Networking on Robot](#lte-setup) for optional setup | See [Windows 10 instructions](https://support.microsoft.com/en-us/windows/connect-to-a-wi-fi-network-in-windows-1f881677-b569-0cd5-010d-e3cd3579d263) for connecting to Customer WiFi network | http://:8080 | See [Remote Access Setup](#remote-access) | +| Cellular Only | Uses cellular in robot + separate cellular in Tablet | N/A | See [Enabling LTE (Cellular) Networking on Robot](#lte-setup) for setup | Pre-configured at factory or use USB-tethering to a cell phone | N/A | See [Remote Access Setup](#remote-access) | + +
+
+ +
Base Station Mode
+
+
+ +
Customer Network Mode
+
+
+ +
+ Cellular Only Mode +
( + Some icons created by Freepik - Flaticon + ) +
+
+
+ +#### Network Access Point Advanced Configuration + +Both the robot and Base Station (if present) are equipped with a network access point +that supports cellular, WiFi, and wired ethernet connections. These devices are +pre-configured before shipping, but there are a small number of settings that the +user may wish to adjust. + +##### Configuring WAN/Internet Port on Base Station + +To switch between DHCP and Static modes for the WAN/Internet port on the Base Station: + +1. Configure a wired Ethernet port on your laptop to `192.168.132.101/24`. + See [Wired Network Connection](#wired-network-connection) for details. +1. Open the front panel of the Base Station and connect an Ethernet cable from + the configured port on your laptop to one of the available LAN ports on the + Microhard in the Base Station. +1. Open the following in your Chrome browser: https://192.168.132.50/cgi-bin/webif/network-wan.sh
+ This should bring you to the "Network → WAN" menu. + Note: Refer [Appendix A](#networking-configuration) for default credentials. +1. Update the "WAN2 Port Configuration" as desired. +1. Click "Submit" in the bottom-right corner to apply the settings. +1. Disconnect the Ethernet cable and close the Base Station. + +##### Updating the WiFi SSID or Password on Base Station + +The Base Station, if present, serves as a WiFi Access Point. +Follow the steps below to change the default WiFi SSID or password of this access point. + +1. Configure a wired Ethernet port on your laptop to `192.168.132.101/24`. + See [Wired Network Connection](#wired-network-connection) for details. +1. Open the front panel of the Base Station and connect an Ethernet cable from + the configured port on your laptop to one of the available LAN ports on the + Microhard in the Base Station. +1. Open the following in your Chrome browser: https://192.168.132.50/cgi-bin/webif/wireless-wlan0.sh
+ This should bring you to the "Wireless → Radio1" menu. + Note: Refer [Appendix A](#networking-configuration) for default credentials. +1. Update the "Radio1 Virtual Interface 1" to set the new SSID or password as desired. +1. Click "Submit" in the bottom-right corner to apply the settings. +1. Disconnect the Ethernet cable and close the Base Station. +1. Apply the corresponding changes to the robot (see below). + +##### Updating the WiFi SSID or Password on Robot {#robot-wifi-setup} + +Using WiFi, the robot can connect to the Base Station, if present, or to a customer +WiFi network. If the SSID or password on the Base Station has changed or if connecting +the robot to a customer WiFi network, follow the steps below to match those of the +WiFi access point. + +1. Configure a wired Ethernet port on your laptop to `192.168.131.101/24`. + See [Wired Network Connection](#wired-network-connection) for details. +1. Connect an ethernet cable from the configured port on your laptop to the + debug/expansion port on the top of the robot. +1. Open the following in your Chrome browser: https://192.168.131.51/cgi-bin/webif/wireless-wlan0.sh
+ This should bring you to the "Wireless → Radio1" menu. + Note: Refer [Appendix A](#networking-configuration) for default credentials. +1. Update the "Radio1 Virtual Interface 1" to set the new SSID or password to match + that of the access point. +1. Click "Submit" in the bottom-right corner to apply the settings. +1. Disconnect the Ethernet cable. + +##### Enabling LTE (Cellular) Networking on Robot {#lte-setup} + +Where WiFi access is not available or when the robot will be travelling out of +WiFi range, it is necessary to enable LTE (cellular) networking on the robot. +Follow the steps below to enable LTE. + +1. Complete the physical [Installation of SIM Card](#installation-of-sim-card). +1. Configure a wired Ethernet port on your laptop to `192.168.131.101/24`. + See [Wired Network Connection](#wired-network-connection) for details. +1. Connect an ethernet cable from the configured port on your laptop to the + debug/expansion port on the top of the robot. +1. Open the following in your Chrome browser: https://192.168.131.51/cgi-bin/webif/carrier.sh
+ This should bring you to the "WWAN → Settings" menu. + Note: Refer [Appendix A](#networking-configuration) for default credentials. +1. Apply the following settings as shown in the image below: + - Carrier status: `Enable` + - IP-Passthrough: `Disable` + - MTU Size: (blank) + - SIM Selection: `SIM Card-1 Only` + - Data Roaming: `Disable` + - Carrier Operator: `Auto` + - Technologies Mode: `AUTO` + - APN: (carrier-specific) + - SIM Type: `Auto Detect` + - Advanced+: (not checked) + - Network+: (not checked) + - IoT Sockets available: `None` + - RSSI Threshold: `90` +1. After a couple minutes, check the WWAN status in your Chrome browser: https://192.168.131.51/cgi-bin/webif/carrier-status.sh
+ Ensure that "Activity Status" is `Connected` and that a "WWAN IP Address" has been assigned. +1. Open the following in your Chrome browser: https://192.168.131.51/cgi-bin/webif/mwan.sh
+ This should bring you to the "Network → LoadBalancer" menu. +1. Confirm that the settings are as outlined in the figure below. +1. Disconnect the Ethernet cable. + +
+
+ +
Microhard SIM Card Settings
+
+
+ +
Microhard Load Balancer Settings
+
+
+ +:::info + +In some cases, it may be desirable to monitor the daily use on the WWAN interface, +especially when there are monthly data limits for your SIM card. It is possible to +review your daily and monthly usage on the WWAN interface from the Microhard +"WWAN → DataUsage" menu: +https://192.168.131.51/cgi-bin/webif/carrier-datausage.sh + +::: + +:::info + +It is possible to apply a bandwidth throttle, either to the WWAN or WiFi interface (or both). +For OutdoorNav, any bandwidth limits would likely be applied to the upload direction to +limit the amount of video data being sent from the robot; very little download data is +used by the robot. To configure bandwidth throttling, use the Microhard "Network → Bandwidth" menu: +https://192.168.131.51/cgi-bin/webif/thruputcontrol.sh + +::: + +:::info + +When cellular support is enabled on the robot, the system will automatically switch from WiFi to +cellular if the WiFi connection has gone down for two minutes or more. This allows remote +recovery of the robot if it has been driven beyond WiFi range. + +::: + +:::info + +When switching between WiFi and cellular modes, the switchover normally occurs within 30 seconds +but may take up to 120 seconds to complete. In some cases, it may be necessary to refresh the +OutdoorNav UI manually after the switchover. + +::: + +:::note + +Refer to the [OutdoorNav User Manual](/docs_outdoornav_user_manual/web_user_interface/ui_overview#general-settings) +for details on switching between WiFi and cellular modes. + +::: + +#### Remote Access Setup {#remote-access} + +:::note + +This step is optional. It is only for users attempting to access Husky Observer over the internet. + +::: + +When attempting to access Husky Observer over the internet, it can sometimes be difficult to determine the +IP address of the robot and to expose the necessary ports for access. Various services are available to simplify +this remote access task. Once such service, [ngrok](https://ngrok.com/), is described in detail below. + +##### Remote Access via Ngrok + +[ngrok](https://ngrok.com/) is an application that enables developers to expose a local development server to +the internet with minimal effort. It can be leveraged to make the OutdoorNav User Interface (hosted on the +Husky Observer robot) appear to be hosted on a subdomain of ngrok.com, meaning that no public IP or domain +name on Husky Observer is needed. While the ngrok tools are pre-installed on Husky Observer, a small amount +of configuration is required to use them. + +1. [Sign up for ngrok](https://dashboard.ngrok.com/signup) if you don't yet have an account. The "Pro" tier is recommended. +1. Configure a wired Ethernet port on your laptop to `192.168.131.101/24`. + See [Wired Network Connection](#wired-network-connection) for details. +1. Connect an Ethernet cable from the configured port on your laptop to the + debug/expansion port on the top of the robot. +1. SSH to the robot: `ssh administrator@192.168.131.1`. (See [Appendix A](#network-setup) for credentials.) +1. Ensure that the robot has internet access (eg. `ping 8.8.8.8`). +1. Register your ngrok auth token (shown [here](https://dashboard.ngrok.com/get-started/setup)) with the ngrok agent:
+ e.g., `ngrok config add-authtoken (your_auth_token)` +1. Optional: Run a simple test to verify ngrok is working: + - Terminal 1: `python3 -m http.server` + - Terminal 2: `ngrok http 8000` + - The ngrok terminal will display a remote address that you can enter, which should display the python3 HTTP server. +1. Select a subdomain name that will be used to access the OutdoorNav UI at https://your_subdomain.ngrok.io. +1. Run `ngrok config edit` to set up a tunnel for your subdomain to port 80 on Husky Observer, where the + OutdoorNav UI is running. These updates will be saved to: `~/.config/ngrok/ngrok.yaml`. Note that the example below + includes a basic username/password authentication. Different authorization mechanisms are available. Refer to + ngrok documentation for details. + ```yaml + version: "2" + authtoken: your_auth_token + region: us + tunnels: + first: + addr: 80 + proto: http + subdomain: your_subdomain + basic_auth: ["your_username:your_password"] + ``` +1. Check if ngrok is up and running by checking the [ngrok agent page](https://dashboard.ngrok.com/tunnels/agents). +1. Try to access the OutdoorNav UI at https://your_subdomain.ngrok.io. + +:::note + +While the example above shows how to forward port 80, it is possible to use ngrok +to forward other ports as well, such as port 22 for SSH access. Simply add +additional tunnels to the example above. + +::: + +### OutdoorNav Software Setup + +#### Tablet Startup + +The Husky Observer optionally ships with a Getac ruggedized tablet as shown in below. + +
+
+ +
Getac ruggedized tablet
+
+
+ +Power on the Getac ruggedized tablet by pressing the +**GREEN** power button on the right side of +the tablet. The tablet is running Windows 10 which will startup on power-up. +If prompted for a password, enter: **`clearpath`**. + +##### Connecting to OutdoorNav Web User Interface + +In order to connect to the Outdoor Nav User Interface, ensure that the tablet +has network connectivity to the Husky Observer as described in +[Networking Setup](#networking-setup) and note the URL for accessing the OutdoorNav UI. + +1. Open the Chrome browser. +1. Enter the OutdoorNav UI URL in the search bar (see [Network Modes](#network-modes) for URLs). +1. Optional: Add a bookmark to Chrome. + +These steps will open the OutdoorNav UI, which will allow you to +teleoperate and autonomously control the robot. + +##### Loading Map Tiles + +The OutdoorNav UI does not cache map tiles on the browser so you +will need to connect to an internet source to load the map tiles. Ensure +that your networking setup conforms to one of the supported +[Network Modes](#network-modes), to ensure that the tablet has network +connectivity to both the robot and the internet. + +#### RTK Correction Setup + +:::note + +This step is optional, but highly recommended. + +::: + +RTK corrections are used to minimize errors related to GPS-based localization and +are strongly recommended when attempting to operate Husky Observer autonomously. +If a Base Station is present, RTK corrections will be acquired from the Base Station, +once it has been surveyed. Alternatively, RTK corrections can be acquired over +the internet using the NTRIP protocol from various service providers, such as +through the [SwiftNav Skylark](https://www.swiftnav.com/skylark) +service. Both the Base Station and Skylark setup instructions are outlined below. + +##### Survey Base Station {#survey-base-station} + +If a Base Station is present, it must be surveyed to be able to +operate the robot autonomously. Follow the instructions in the +[OutdoorNav User Manual](/docs_outdoornav_user_manual/getting_started/system_setup#survey_base_station) +for details on how to survey the Base Station. + +##### RTK Corrections via the Skylark Service + +If a Base Station is not present, RTK corrections can be acquired over +the internet using the NTRIP protocol. While various services are available for providing RTK corrections, +Husky Observer has been validated with the [SwiftNav Skylark](https://www.swiftnav.com/skylark) +service. Follow the steps below to set up the Skylark service. + +1. [Sign up for a Skylark account](https://account.swiftnav.com/sign-up) if you do not have one. (Note that Clearpath does not provide a Skylark account.) +1. Create a Skylark subscription (https://{your_account_name}.account.swiftnav.com/subscriptions) from the subscriptions tab. +1. Create a new Device in the "Devices" tab corresponding to the robot that will be receiving the corrections. +1. Configure the "position" SwiftNav Duro to communicate with the Skylark service. + 1. Ensure that the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001903699-installing-swift-console) + is installed on your laptop. + 1. Configure a wired Ethernet port on your laptop to `192.168.131.101/24`. + See [Wired Network Connection](#wired-network-connection) for details. + 1. Connect an ethernet cable from the configured port on your laptop to the + debug/expansion port on the top of the robot. + 1. Confirm that you can `ping 192.168.131.31`, which validates network connectivity to the "position" Duro. + 1. Open the Swift Console. + 1. "Connect to Device" using "TCP/IP" with "Host" `192.168.131.31` and port `55555`. + + 1. In the "Settings" tab: + 1. Under "ethernet", set the "interface mode" to `Config`. + 1. Under "ethernet", set the "gateway" to `192.168.131.51`, which + is the IP address of network access point on the robot.
+ + 1. Under "ntrip", set "enable" to `True` and then fill in the remaining fields using + the credentials from the Skylark web portal.
+ + 1. Click "Save to Device" to save the settings. + 1. In the "Settings" tab, under "ethernet", set the "interface mode" to `Active`. + 1. Click "Save to Device" to save the settings. + 1. In the "Observations" tab, confirm that RTK corrections from Skylark are being received.
+ + 1. Disconnect the ethernet cable between your laptop and the robot. + +#### Set Datum {#set-datum} + +Before being able to operate the robot autonomously, you will need to set +the datum (ie. the reference point in the world coordinate frame). +Follow the instructions in the +[OutdoorNav User Manual](/docs_outdoornav_user_manual/getting_started/system_setup#set-datum) +for details on how to set the datum. + +#### Set Dock Location {#set-dock-location} + +Before being able to perform docking operations, you will need to set +the dock location. Follow the instructions in the +[OutdoorNav User Manual](/docs_outdoornav_user_manual/getting_started/system_setup#set-dock-location) +for details on how to set the dock location. + +If the Base Station has been moved (and therefore been resurveyed), or if +the dock has been moved to a new location, you will need to set +the location of the dock by repeating the above instructions. + +--- + +## OutdoorNav Operation + +This section outlines how to operate the system through teleoperation as +well as how to operate the system for autonomous missions, +controlled by the OutdoorNav User Interface. Refer to the +[Outdoor Nav User Manual](/docs_outdoornav_user_manual/web_user_interface/ui_overview) +for details on the User Interface including: Main Components, Map View, Camera Views, and 3D View. + +:::note + +While this section outlines how to operate the robot using the User Interface, +all functionality is also available through the Application Programming Interface (API). +Refer to the [Outdoor Nav User Manual](/docs_outdoornav_user_manual/api/api_overview) +for details on the API, including both an overview and a detailed listing. + +::: + +### Manual Mode (Teleoperation) + +
+
+ +
+
+ +Ensure that you have read [Safety](#safety) and are aware of possible +hazards when using this product as well as the safety methods that can be +used to stop the moving robot. + +Teleoperation allows the user to operate the robot remotely, using the built-in +cameras. Refer to the [Outdoor Nav User Manual](/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode) +for details on the Manual Mode (Teleoperation). + +### Autonomous Mode + +
+
+ +
+
+ +Ensure that you have read [Safety](#safety) and are aware of possible +hazards when using this product as well as the safety methods that can be +used to stop the moving robot. + +In autonomous mode, the user is able to create missions and then command +the robot to execute those missions, without requiring user intervention +during the execution of the mission. + +#### Autonomous Missions {#autonomous-missions} + +Refer to the Outdoor Nav User Manual for details on the +[Autonomous Mode](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode), +including details on [Autonomous Docking](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#autonomous-docking). + +#### Retrieving Results from Autonomous Missions + +During an autonomous mission, images, videos, audio, and other collateral may be +captured and stored on the robot. +At the end of the mission, these can be downloaded using an SFTP client that has +network access to the robot. This connectivity could be from a device on the +Base Station network (if present) or over the internet (where configured, +see [Remote Access Setup](#remote-access)). + +The IP address, username, and password for connecting to +the robot are provided in [Appendix A: Networking Configuration](#networking-configuration). +The output files from the +autonomous missions are available to be downloaded from: `/home/administrator/clearpath_files/media`. + +Key notes: + +- In the above directory, there will be a subdirectory for each of the sensors. + Each of the sensor subdirectories will contain images, videos, or audio whose filenames + are based on the time at which the image was captured or the time at which the audio/video + recording was started. For example, a video that was + started on May 17, 2022 at 13:25:08 would correspond to a filename of: + `2022-05-17_13-25-08.avi` +- The operator is responsible for deleting image, video, and audio files after they have been downloaded + and archived. Failure to do so may result in the robot storage becoming full, which + could prevent new mission data from being saved. +- Any SFTP-compatible client can be used to download the data. FileZilla, + with details below, is the recommended SFTP client. + +##### Using FileZilla for Downloading Data + +FileZilla, [available for free download](https://filezilla-project.org/download.php?type=client), +has a graphical user interface and is the recommended SFTP client. + +:::note + +The example below shows how to download files using the Base Station network. +If downloading via the internet instead, update the `host` below based on the +[Remote Access Setup](#remote-access). For example, if using ngrok with a tunnel +set up on port 22 with a subdomain of `customer1-sftp`, then the `host` would +be `customer1-sftp.ngrok.io` and the port would be the one specified by +the ngrok mapping. + +::: + +To use FileZilla on a laptop or tablet connected to the Base Station network, +open FileZilla, use its menu to select File → Site Manager, +and enter the settings as illustrated in the figure below and click +"Connect". + +- **protocol:** SFTP +- **host:** 192.168.132.1 +- **username:** administrator +- **password:** clearpath +- **port:** 2222 + +
+
+ +
FileZilla Connection Details
+
+
+ +To transfer files, use the local (left) and remote (right) file browsers as shown +in the figure below. You can copy files off of the robot by selecting +them on the right and dragging them to a folder on the left. + +Once you are finished, close the connection with Server → Disconnect. + +
+
+ +
FileZilla Full View
+
+
+ +#### Monitoring System Status {#monitoring-system-status} + +The OutdoorNav UI has battery, networking, and status indicators on the main dashboard. +In addition, to see the detailed status of the system in the OutdoorNav UI, +select the "STATUS" option from the menu, which will provide the status for key +subsystems: + +- Localization +- Dock +- Wireless Charging +- System/Computer +- Sensors + +All subsystems should have a green checkmark to indicate they are working as intended. +Otherwise, a warning or error message is provided. + +#### Using Pan-Tilt-Zoom Camera in Autonomous Missions + +The Husky Observer is equipped with a pan-tilt-zoom (PTZ) camera that is capable of +high zoom levels. During autonomous missions, pre-configured pan-tilt-zoom settings can be +used to capture images and videos. These pan-tilt-zoom settings are configured through +the [Move PTZ Task](https://docs.clearpathrobotics.com/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#add-task). +To increase the repeatability of data captured when using the Move PTZ Task, the +[Waypoint Heading](https://docs.clearpathrobotics.com/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#waypoint-heading) +should be enabled and [Waypoint Tolerance](https://docs.clearpathrobotics.com/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#waypoint-tolerance) +settings should be set to their minimum values. + +Even with these constraints, given the minimum tolerances and subject to environmental conditions, +to ensure that images/videos captured following a Move PTZ Task are for an equivalent target area +each time the mission is repeated, zoom values above the 25-40 are not recommended by default. +Validation in the customer environment is recommended. + +--- + +## Support + + + +--- + +## Appendix A: Networking Configuration {#networking-configuration} + +### Base Station Network WiFi Access + +In some cases, it may be desirable to connect additional equipment, such as a laptop, to the +Base Station network via WiFi. To do so, use the settings outlined below. By default, the +Base Station is configured in DHCP mode; as such, the device being connected should be +set for DHCP mode. Once connected to the Base Station, an IP address in the 192.168.132.0/24 +will be assigned. + +- **Default WiFi SSID:** CPR Base Station +- **Default WiFi password:** clearpath + +### Accessing the Main Computer from the WAN + +All images and videos that are collected during missions are stored on the Main Computer +inside Husky Observer until downloaded and deleted by the operator. When the download/delete function is performed +by a computer within the Base Station network, the Main Computer can be accessed +as described in the following section by connecting to TCP port 22 on the Main Computer. +When the download/delete function is performed by a computer on the WAN network (connected +to the Base Station WAN port), the operator can access the Main Computer by accessing +TCP port 2222 on the Base Station, which gets mapped to TCP port 22 on the Main Computer. + +### Husky Observer Network Components + +| Component | IP Address | Default Credentials | +| ------------------------------------------------------ | -------------------------------- | --------------------------------------------------- | +| Main Computer | 192.168.131.1
10.252.252.100 | **user:** administrator
**password:** clearpath | +| IndoorNav Computer (optional) | 10.252.252.1 | **user:** administrator
**password:** clearpath | +| Camera, Axis, PTZ | 192.168.131.10 | **user:** root
**password:** clearpath | +| Camera, FLIR, Thermal (optional) | 192.168.131.11 | **user:** administrator
**password:** clearpath | +| 3D LiDAR, Velodyne | 192.168.131.20 | n/a | +| 2D LiDAR, Hokuyo, front | 192.168.131.21 | n/a | +| 2D LiDAR, Hokuyo, rear | 192.168.131.22 | n/a | +| GPS receiver, SwiftNav, Base Station (optional) | 192.168.131.30 | n/a | +| GPS receiver, SwiftNav, robot, right (position) | 192.168.131.31 | n/a | +| GPS receiver, SwiftNav, robot, left (heading) | 192.168.131.32 | n/a | +| Networking Gateway, Microhard, Base Station (optional) | 192.168.131.50 | **user:** administrator
**password:** clearpath | +| Networking Gateway, Microhard, robot | 192.168.131.51 | **user:** administrator
**password:** clearpath | +| Wireless Power Transmitter, WiBotic, dock | 192.168.2.20 | n/a | +| Tablet, Getac | 192.168.131.75 | **user:** administrator
**password:** clearpath | + +--- + +## Appendix B: Advanced Configuration + +Each of the sensors on Husky Observer has a variety of settings, which have +been selected to work in a broad range of use cases. Certain specialized +use cases may require the operator to create a custom configuration. The +information below outlines the key settings for each sensor and where +settings can be updated. + +:::warning + +NOTE: Updating camera settings may affect overall system stability. +Proceed with caution! Contact [Support](#support) if you have any questions. + +::: + +### Axis PTZ Camera Configuration + +The Husky Observer is equipped with an [Axis Q62](https://www.axis.com/products/axis-q62-series) series PTZ camera, with +colour and low-light capabilities, defogger, and lens wiper. + +#### Key Settings + +- Resolution: + - Max: 1920x1080 + - Default: 1280x720 +- Frame rate: + - Max: 60 Hz + - Default: 20 Hz for data capture, 10Hz for UI live stream + +#### Where to make adjustments + +Global camera settings (like pan & tilt limits) can be set by logging into the Axis setup tool on the camera. Connect +a laptop to the robot and assign the laptop a static IP address of `192.168.131.101/24`. Then open a +browser and navigate to http://192.168.131.10. + +Resolution and frame rate settings can be adjusted on the Main Computer by editing the following environment +variables in `/home/administrator/cpr_outdoornav_launch/env/sensors_customization.env`. Note that any increase +in resolution may require a corresponding decrease in the frame rate to avoid data bottlenecks. + +- AXIS_PTZ_WIDTH +- AXIS_PTZ_HEIGHT +- AXIS_PTZ_FPS +- AXIS_Q62_THROTTLE_RATE + +#### Adjusting Pan Limits + +The Axis Q62 is normally capable of making continuous rotations in either direction. This allows the camera to always +take the shortest trajectory to reach any given pan angle. However, if you have additional equipment mounted on top of +the camera, for example a Flir thermal camera or a microphone, this behaviour may cause the wires to get tangled around +the PTZ camera and potentially cause damage to the robot. + +To prevent damage to the robot, the camera has been pre-configured with pan limits on the Axis camera. This will restrict the +camera's range of motion to less than 180 degrees in either direction, eliminating the risk of the camera making +continuous rotations. + +The steps below outline how to adjust the pan limits. + +Connect your laptop to one of the robot's exposed ethernet ports and assign your laptop a static +IP address of `192.168.131.101/24`. Open your web browser and navigate to +http://192.168.131.10. Log into the Axis configuration website using the credentials found +in [Appendix A](#networking-configuration). + +
+
+ +
Axis Q62 login screen
+
+
+ +In the browser, click on Settings and select PTZ + +
+
+ +
Axis Q62 PTZ settings
+
+
+ +Disable any exisitng pan limits by opening the limits menu and making sure all the buttons are off. + +
+
+ +
Disabling the Axis Q62 pan limits
+
+
+ +Move the camera to a pan of -179 degrees. The easiest way to move the camera precisely is to launch the ROS driver on the Main Computer and use the `cmd` topic to move the camera: + +```bash +# Start the driver in one terminal +# Replace the IP address as appropriate for your camera +roslaunch axis_camera axis.launch enable_ptz:=true username:=root password:=clearpath hostname:=192.168.131.10 + +# In a second terminal, run +rostopic pub /axis/cmd axis_camera/Axis "{pan: -179.0, tilt: 0.0, zoom: 1.0, focus: 0.0, brightness: 1.0, iris: 0.0, autofocus: true, autoiris: true}" -1 +``` + +Once the camera finishes moving, set the left pan limit by pressing the left limit button: + +
+
+ +
Setting the left pan limit to -179 degrees
+
+
+ +Then move the camera to a pan of 179 degrees: + +```bash +rostopic pub /axis/cmd axis_camera/Axis "{pan: 179.0, tilt: 0.0, zoom: 1.0, focus: 0.0, brightness: 1.0, iris: 0.0, autofocus: true, autoiris: true}" -1 +``` + +Once the camera finishes moving, click on the right pan limit button to set the right pan limit to 179 degrees. + +
+
+ +
Setting the right pan limit to 179 degrees
+
+
+ +Click the Done button to apply the new limits. Note that the camera will now have a 2-degree deadzone at the rear where +it cannot point. This is an unfortunate but unavoidable side-effect of setting the limits this way. + +### RealSense Front and Rear Rear Driving Camera Configuration + +#### Key Settings + +- Resolution: 854x480 +- Frame rate: 6 Hz + +#### Where to make adjustments + +The front/rear camera settings are not configurable. + +### Motion Buzzer Enable/Disable + +The system is equipped with a buzzer to produces a loud sound when the system +is driving in any direction. This buzzer is enabled by default. To disable the buzzer, +run the following command on the Main Computer: + +``` +rosservice call /safety_alarm/set_mute "data: true" +``` + +### Omnidirectional Microphone Configuration + +No configuration is available for the omnidirectional microphone. diff --git a/docs_versioned_docs/version-ros2humble/robots/accessories/manipulators/kinova_gen3_lite.mdx b/docs_versioned_docs/version-ros2humble/robots/accessories/manipulators/kinova_gen3_lite.mdx index da3cd076..0ff6897a 100644 --- a/docs_versioned_docs/version-ros2humble/robots/accessories/manipulators/kinova_gen3_lite.mdx +++ b/docs_versioned_docs/version-ros2humble/robots/accessories/manipulators/kinova_gen3_lite.mdx @@ -18,7 +18,7 @@ import TabItem from "@theme/TabItem"; | Description | CPR Item | | :-------------------------------- | :------------------------------------------------------: | -| Kinova Gen3 lite Bundle | [022586](/assets/pdf/clearpath_robotics_015822-TDS1.pdf) | +| Kinova Gen3 lite Bundle | [022586](/assets/pdf/clearpath_robotics_022586-TDS2.pdf) | | Kinova Gen3 lite, PACS™ kit | 027219 | --- diff --git a/docs_versioned_docs/version-ros2humble/robots/common/_category_.json b/docs_versioned_docs/version-ros2humble/robots/common/_category_.json index 88b377b2..44fea45e 100644 --- a/docs_versioned_docs/version-ros2humble/robots/common/_category_.json +++ b/docs_versioned_docs/version-ros2humble/robots/common/_category_.json @@ -1,4 +1,4 @@ { "label": "Common", - "position": 6 + "position": 7 } diff --git a/docs_versioned_docs/version-ros2humble/robots/legacy/_category_.json b/docs_versioned_docs/version-ros2humble/robots/legacy/_category_.json index 2db18d85..5de5d26c 100644 --- a/docs_versioned_docs/version-ros2humble/robots/legacy/_category_.json +++ b/docs_versioned_docs/version-ros2humble/robots/legacy/_category_.json @@ -1,4 +1,4 @@ { "label": "Legacy", - "position": 5 + "position": 6 } diff --git a/docs_versioned_docs/version-ros2humble/robots/solutions/_category_.json b/docs_versioned_docs/version-ros2humble/robots/solutions/_category_.json new file mode 100644 index 00000000..73361e5e --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/robots/solutions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Solutions", + "position": 5 +} diff --git a/docs_versioned_docs/version-ros2humble/robots/solutions/husky_observer/husky_observer.mdx b/docs_versioned_docs/version-ros2humble/robots/solutions/husky_observer/husky_observer.mdx new file mode 100644 index 00000000..8c7f9cda --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/robots/solutions/husky_observer/husky_observer.mdx @@ -0,0 +1,14 @@ +--- +title: Husky Observer +sidebar_label: Husky Observer +sidebar_position: 1 +--- + +:::note + +Husky Observer is currently available in ROS 1 Noetic only. Use the link below +to access the User Manual. + +[Link to Husky Observer User Manual](../../../../docs/ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer) + +::: diff --git a/docusaurus.config.js b/docusaurus.config.js index e92a005b..1939b73a 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -89,8 +89,8 @@ const config = { title: " ", logo: { alt: "Clearpath Robotics", - src: "img/website_images/logo_yellow.png", - srcDark: "img/website_images/logo_white.png", + src: "img/website_images/logo_rockwell_pipe_clearpath_colour.png", + srcDark: "img/website_images/logo_rockwell_pipe_clearpath_white.png", }, items: [ { @@ -161,7 +161,7 @@ const config = { }, }, footer: { - copyright: `Copyright © 2023 Clearpath Robotics Inc. All rights reserved.`, + copyright: `Clearpath Robotics, by Rockwell Automation. All rights reserved. © Clearpath Robotics, Inc., a Rockwell Automation Company. All rights reserved.`, }, prism: { theme: lightCodeTheme, diff --git a/outdoornav_user_manual_versioned_docs/version-0.7.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.7.0/getting_started/system_setup.mdx index 29359056..9c61ee01 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.7.0/getting_started/system_setup.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.7.0/getting_started/system_setup.mdx @@ -209,7 +209,7 @@ From this website, navigate to your city and note the **decimal** value given. Once the magnetic declination of your location is determined, modify the `MAGNETIC_DECLINATION` environment variable in the `/etc/ros/setup.bash` on the OutdoorNav Computer. Refer to -[Connecting to the OutdoorNav Computer](/docs_outdoornav_user_manual/navigation#connecting-to-outdoornav-computer) for +the [Connecting to the OutdoorNav Computer](../navigation.mdx#connecting-to-outdoornav-computer) for details on connecting to the OutdoorNav Computer. Then execute the following command to open the required file: diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/system_setup.mdx index 78b4b53f..b75c11e6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/system_setup.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/system_setup.mdx @@ -217,7 +217,7 @@ From this website, navigate to your city and note the **decimal** value given. Once the magnetic declination of your location is determined, modify the `MAGNETIC_DECLINATION` environment variable in the `/etc/ros/setup.bash` on the OutdoorNav Computer. Refer to -[Connecting to the OutdoorNav Computer](/docs_outdoornav_user_manual/navigation#connecting-to-outdoornav-computer) for +[Connecting to the OutdoorNav Computer](../navigation.mdx#connecting-to-outdoornav-computer) for details on connecting to the OutdoorNav Computer. Then execute the following command to open the required file: diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/_category_.json new file mode 100644 index 00000000..c123e1bc --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/_category_.json new file mode 100644 index 00000000..a6e53920 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/_category_.json new file mode 100644 index 00000000..21746ac4 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "API Endpoints", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/api_endpoints.mdx new file mode 100644 index 00000000..a8498972 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/api_endpoints.mdx @@ -0,0 +1,16 @@ +--- +title: API Endpoints +sidebar_label: API Endpoints +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The ROS 1 Noetic API can be used to monitor and manage OutdoorNav Software. Details +are available through the child pages. + +- [Platform API](./platform_api) +- [Autonomy API](./autonomy_api) +- [Mission Manager API](./mission_manager_api) +- [Definitions](./definitions) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/autonomy_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/autonomy_api.mdx new file mode 100644 index 00000000..06ff0e3b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/autonomy_api.mdx @@ -0,0 +1,485 @@ +--- +title: Autonomy API +sidebar_label: Autonomy API +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Autonomy provides some relevant topics and services suitable for +controlling and monitoring the robot as it is performing autonomous +navigation. + +### Topics Published by Autonomy + +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. + +#### /control_selection/control_state + +  **Message Type:** [clearpath_control_msgs/ControlSelectionState](definitions#msg-control-selection-state) + +  **Description:** Indicates the complete state of control selection +including autonomy state and mode. + +#### /control_selection/current_mode + +  **Message Type:** [clearpath_control_msgs/ControlMode](definitions#msg-control-mode) + +  **Description:** Current control mode (NEUTRAL, MANUAL, AUTONOMY). + +#### /dock/feedback + +  **Message Type:** [clearpath_dock_msgs/DockActionFeedback](definitions#action-dock) + +  **Description:** Feedback topic from the dock action. + +#### /dock/result + +  **Message Type:** [clearpath_dock_msgs/DockActionResult](definitions#action-dock) + +  **Description:** Result topic from the dock action. + +#### /dock/properties + +  **Message Type:** [clearpath_dock_msgs/DockProperties](definitions#msg-dock-properties) + +  **Description:** A list of docks, in which each dock includes information related to +the location, id, etc... + +#### /dock/state + +  **Message Type:** [clearpath_dock_msgs/DockState](definitions#msg-dock-state) + +  **Description:** The current state of the docking process. + +#### /localization/odom + +  **Message Type:** nav_msgs/Odometry + +  **Description:** The robot's current pose and velocity. + +#### /localization/status + +  **Message Type:** [clearpath_localization_msgs/LocalizationStatus](definitions#msg-localization-status) + +  **Description:** Current localization status. Includes accuracy, GNSS +status, and whether the robot is dead reckoning. + +#### /mission/feedback + +  **Message Type:** clearpath_navigation_msgs/MissionActionFeedback + +  **Description:** Feedback topic from the mission action. + +#### /mission/result + +  **Message Type:** clearpath_navigation_msgs/MissionActionResult + +  **Description:** Result topic from the mission action. + +#### /navigation/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** This output commanded velocity from the autonomy +software (OutdoorNav) to control the velocity of the platform. It is +commonly relayed directly into the UGV's velocity controller. + +#### /navigation/distance_to_goal + +  **Message Type:** [clearpath_navigation_msgs/DistanceToGoal](definitions#msg-distance-to-goal) + +  **Description:** The current Euclidean distance and the path distance, +in meters, from the robot to its current goal. + +#### /navigation/footprint + +  **Message Type:** geometry_msgs/Polygon + +  **Description:** The footprint of the robot. + +#### /navigation/global_costmap + +  **Message Type:** nav_msgs/OccupancyGrid + +  **Description:** An occupancy grid consisting of the Free, Occupied or +Unknown space that the robot uses to plan paths in the environment. + +#### /navigation/local_costmap + +  **Message Type:** nav_msgs/OccupancyGrid + +  **Description:** An occupancy grid consisting of the Free, Occupied or +Unknown space that the robot uses to detect obstacles. + +#### /navigation/local_plan + +  **Message Type:** nav_msgs/msg/Path + +  **Description:** The MPC local plan that the navigation uses to control +the robot along the reference path. + +#### /navigation/metrics + +  **Message Type:** [clearpath_navigation_msgs/Metrics](definitions#msg-metrics) + +  **Description:** This topic provides metric information regarding the lifetime of +the navigation. This includes the total distance travelled, duration run, as well as mission +information such as how many missions have been sent, how many have been completed and the number +of replanning maneuvers, recoveries and number of tasks executed. + +#### /navigation/motion_state + +  **Message Type:** [clearpath_navigation_msgs/MotionState](definitions#msg-motion-state) + +  **Description:** This topic provides information about the motion state +of the robot. This includes information about whether the robot is +moving or stopped. Whether it is about to make a turn and the direction +of the turn, and the direction of travel of the robot in regards to its +physical orientation. + +#### /navigation/odom_intent (IN DEVELOPMENT) + +  **Message Type:** [clearpath_navigation_msgs/OdomIntent](definitions#msg-odom-intent) + +  **Description:** The robot's current pose and velocity as well as an +intended pose and velocity in the immediate future. + +#### /navigation/path + +  **Message Type:** geometry_msgs/PoseArray + +  **Description:** The path that the robot is currently traversing. This +is initialized with the initial path and may be updated with paths +generated from replanning maneuvers. + +#### /navigation/progress (BETA) + +  **Message Type:** [clearpath_navigation_msgs/Progress](definitions#msg-navigation-progress) + +  **Description:** The completion percentage of the current path, the +current goal and the current mission. + +#### /navigation/safety_footprints + +  **Message Type:** geometry_msgs/PolygonStamped + +  **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. + +#### /navigation/scan_points (IN DEVELOPMENT) + +  **Message Type:** [clearpath_navigation_msgs/ScanPoints](definitions#msg-scan-points) + +  **Description:** Scans and pointclouds from the various ROS message +formats converted into a simple PointVector format that can be easily +consumed by the UI. + +#### /navigation/state (BETA) + +  **Message Type:** [clearpath_navigation_msgs/NavigationState](definitions#msg-navigation-state) + +  **Description:** The current navigation state. The available states are +COMPUTE PATH, EXECUTE, REPLAN, NAVIGATING AROUND OBSTACLE, RECOVERY, +IDLE, PAUSE, ESTOP, LOST. Multiple simultaneous states are possible. + +#### /navigation/track_error + +  **Message Type:** [clearpath_navigation_msgs/TrackError](definitions#msg-track-error) + +  **Description:** The current crosstrack error (ie. the off-path distance +between the robot and the reference path) and as well as the heading +error (ie. the difference between the current heading and the path +direction). + +#### /safety/safety_stop + +  **Message Type:** std_msgs/Bool + +  **Description:** Flag denoting if autonomy should be stopped due to any +of the following reasons: emergency stop active, one of the sensors has +triggered the safety monitor watchdog. + +#### /safety/watchdog_status (IN DEVELOPMENT) + +  **Message Type:** [clearpath_safety_msgs/WatchdogStatus](definitions#msg-safety-watchdog) + +  **Description:** Provides a list of status flags for each of the +possible sensors that may trigger a safety stop. The watchdog will +trigger if the sensor times out (ie. does not publish a relevant ROS +message for 1 second). + +#### /target_tracker/state + +  **Message Type:** [clearpath_dock_msgs/TargetTrackerState](definitions#msg-target-tracker-state) + +  **Description:** The state information for target tracker used as part of docking. + +#### /undock/feedback + +  **Message Type:** [clearpath_dock_msgs/UndockActionFeedback](definitions#action-undock) + +  **Description:** Feedback topic from the undock action. + +#### /undock/result + +  **Message Type:** [clearpath_dock_msgs/UndockActionResult](definitions#action-undock) + +  **Description:** Result topic from the undock action. + +------------------------------------------------------------------------ + +### Topics Subscribed to by Autonomy + +The OutdoorNav software subscribes to the topics in this section. They +can be used to control the behaviour of OutdoorNav. + +#### /platform/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** Platform-level commanded velocity. This should be the velocity tracked by the platforms velocity controller. + +#### /mission/cancel + +  **Message Type:** actionlib_msgs/GoalID + +  **Description:** This topic is used to cancel all the missions that have +been sent to the OutdoorNav software. + +#### /mission/goal + +  **Message Type:** clearpath_navigation_msgs/msg/MissionActionGoal + +  **Description:** This topic is used to send a goal to the OutdoorNav +software. The goal can consist of a series of Waypoints and must include +a Goal point. + +#### /dock/cancel + +  **Message Type:** actionlib_msgs/GoalID + +  **Description:** This topic is used to cancel the docking process that has been +initialized by a previously sent goal. + +#### /dock/goal + +  **Message Type:** [clearpath_dock_msgs/msg/DockActionGoal](definitions#action-dock) + +  **Description:** This topic is used to send a goal to the docking process. +The goal consists of the UUID of the dock to dock at as well as wether or not local docking +should be performed. + +#### /undock/cancel + +  **Message Type:** actionlib_msgs/GoalID + +  **Description:** This topic is used to cancel the undocking process that has been +initialized by a previously sent goal. + +#### /undock/goal + +  **Message Type:** [clearpath_dock_msgs/msg/UndockActionGoal](definitions#action-undock) + +  **Description:** This topic is used to send a goal to the undocking process. +The goal is empty since we always consider undocking to be a local undocking process. + +------------------------------------------------------------------------ + +### Services Exported by Autonomy + +#### /control_selection/set_mode + +  **Service Type:** [clearpath_control_msgs/srv/SetControlMode](definitions#srv-set-control-mode) + +  **Description:** Change the current control mode from NEUTRAL to MANUAL +or AUTONOMY. + +#### /control_selection/autonomy_pause + +  **Service Type:** std_srvs/SetBool + +  **Description:** Pause the autonomy when it is currently in AUTONOMY +mode. Will only pause when autonomy is active. + +#### /control_selection/autonomy_resume + +  **Service Type:** std_srvs/SetBool + +  **Description:** Resume the autonomy when it is current mode is in +AUTONOMY. Will only resume if the robot is in a paused state. + +#### /dock/add + +  **Service Type:** [clearpath_dock_msgs/srv/AddDock](definitions#srv-add-dock) + +  **Description:** Add a dock to the database of docks. Complete list of dock information is required as input. +The new dock will appear on the UI. + +#### /dock/remove + +  **Service Type:** [clearpath_dock_msgs/srv/RemoveDock](definitions#srv-remove-dock) + +  **Description:** Remove and existing dock from the database. Input to this service requires ether the UUID +or the semantic name of the dock. + +#### /dock/clear_data + +  **Service Type:** [std_srvs/srv/Trigger](definitions#srv-clear-dock-data) + +  **Description:** Remove all existing dock data from storage. + +#### /dock/set_location/by_id + +  **Service Type:** [clearpath_dock_msgs/srv/SetDockLocationByID](definitions#srv-set-dock-location-by-id) + +  **Description:** Can be used to either set up a new dock (empty string in the uuid field), or update +the location of an existing dock (where the `uuid` field is required). + +#### /dock/set_location/by_name + +  **Service Type:** [clearpath_dock_msgs/srv/SetDockLocationByName](definitions#srv-set-dock-location-by-name) + +  **Description:** Can be used to update the location of an existing dock. Requires the semantic name +of the dock to be input into the `name` field. + +#### /localization/set_datum + +  **Service Type:** [clearpath_localization_msgs/srv/SetDatum](definitions#srv-set-datum) + +  **Description:** This service is used to manually set the datum +parameters of OutdoorNav running on the UGV. After setting the datum +parameter, this service also reinitializes the states of the +localization according to the current sensor readings. If you are +sending a mission to the UGV without using the UI and through the API, +you must call this service before sending the mission. + +#### /localization/reset + +  **Service Type:** [clearpath_localization_msgs/srv/ResetLocalization](definitions#srv-reset-localization) + +  **Description:** This service can be used to trigger a reset of the UGVs localization. + +#### /navigation/set_collision_avoidance + +  **Service Type:** std_srvs/SetBool + +  **Description:** Modify the state of the collision avoidance feature. If +True, collision avoidance is ENABLED and the robot will use its lidar(s) +to detect and maneuver around obstacles. If False, collision avoidance +is DISABLED and the robot will NOT use its lidar(s) to detect and +maneuver around obstacles. Disabling this feature is not recommended and +should be used with caution. + +:::note + +1. This feature does not take effect immediately when the service is + called, but only takes effect at the next Goal. + +2. Disabling collision avoidance also disables the continuous planner, in such a case where the + continuous planner is enabled. When re-enabling the collision avoidance, + the continuous planner must also be re-enabled using the following API service. + +::: + +#### /navigation/set_continuous_planner + +  **Service Type:** std_srvs/SetBool + +  **Description:** Modify the state of the continuous planning feature. If +True, continuous planning is ENABLED and the robot will proactively +attempt to generate a path around detected obstacles. If False, +continuous planning is DISABLED and the robot will stop in front of +obstacles before generating a path around the obstacle. + +:::note + +1. This feature takes effect immediately once the service is called. +2. This service needs to be called if you are re-enabling the collision + avoidance and want the continuous planner to be active. Disabling + collision avoidance will have disabled the continous planner. + +::: + +#### /navigation/set_path_smoother + +  **Service Type:** [clearpath_navigation_msgs/srv/SetPathSmoother](definitions#srv-set-path-smoother) + +  **Description:** Modify the state of the path smoothing feature. If +True, path smoothing is ENABLED and curved paths will be generated +according to the specified turning radius. If False, path smoothing is +DISABLED and point-to-point paths will be generated. + +:::note + +This feature takes effect immediately once the service is called. + +::: + +#### /navigation/set_path shifter + +  **Service Type:** [clearpath_navigation_msgs/srv/SetPathShifter](definitions#srv-set-path-shifter) + +  **Description:** Modify the state of the path shifting feature. If True, +path shifting is ENABLED and the reference path will be automatically +shifted as it veers off the reference path (to prevent oscillations). If +False, path shifting is DISABLED and normal behaviour is active. + +:::note + +This feature takes effect immediately once the service is called. + +::: + +#### /navigation/set_stop_distance (IN DEVELOPMENT) + +  **Service Type:** [clearpath_navigation_msgs/srv/SetStopDistance](definitions#srv-set-stop-distance) + +  **Description:** Modify the state of the stop distance feature. If True, +the stop distance feature is ENABLED and the robot will stop the +specified distance from obstacles. If False, the stop distance feature +is DISABLED and the robot will stop the default distance from obstacles. + +#### /navigation/set_delay_compensation (IN DEVELOPMENT) + +  **Service Type:** [clearpath_navigation_msgs/srv/SetDelayCompensation](definitions#srv-set-delay-compensation) + +  **Description:** Modify the state of the delay compensation feature. If +True, delay compensation is ENABLED and the controller will compensate +for low-level mechanical delays. If False, delay compensation is +DISABLED and the normal behaviour is expected. + +------------------------------------------------------------------------ + +### Actions Exported by Autonomy + +#### /dock + +  **Action Type:** [clearpath_dock_msgs/action/Dock](definitions#action-dock) + +  **Description:** Send the robot to the charging dock, if the docking +package has been included. + +#### /localization/survey + +  **Action Type:** [clearpath_localization_msgs/action/SurveyBaseStation](definitions#action-survey-base-station) + +  **Description:** Start surveying the base station, if available. + +#### /mission + +  **Action Type:** [clearpath_navigation_msgs/action/Mission](definitions#action-mission) + +  **Description:** Send goals for execution by the robot. This will +include the goal, the viapoint(s), tasks, goal tolerances and goal +heading. + +#### /undock + +  **Action Type:** [clearpath_dock_msgs/action/Dock](definitions#action-undock) + +  **Description:** Undock the robot to the charging dock, if the docking +package has been included. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/definitions.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/definitions.mdx new file mode 100644 index 00000000..f060becf --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/definitions.mdx @@ -0,0 +1,1576 @@ +--- +title: Definitions +sidebar_label: Definitions +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +### Message Definitions + +#### clearpath_control_msgs/ControlMode.msg {#msg-control-mode} + +``` +# Control mode message + +int8 NEUTRAL=0 +int8 MANUAL=1 +int8 AUTONOMY=2 + +int8 mode +``` + +#### clearpath_control_msgs/ControlSelectionState.msg {#msg-control-selection-state} + +``` +# The complete state of the control selection module. This message includes the autonomy state as well as the navigation mode. + +ControlState autonomy +ControlMode mode +``` + +#### clearpath_control_msgs/ControlState.msg {#msg-control-state} + +``` +# The autonomy state message, The autonomy can be either enabled/disabled and active/paused. + +bool enabled +bool paused +``` + +#### clearpath_dock_msgs/DockInfo.msg {#msg-dock-info} + +``` +# Message definition containing the information of a single dock. This includes identifiers, lat/lon and orientation of the location of a dock. + +string name +string uuid +string frame +string target_template + +# ISO 8601 date/time format of last successfull dock location setting +string last_location_set_time + +# maximum allowable distance to allow for predocking. (ie. the distance within which the dock waypoint must be located) +float32 max_predock_distance +# the distance from the dock that the robot will navigate to prior to start docking +float32 predock_distance + +# location of the dock +float64 latitude +float64 longitude +float64 heading +``` + +#### clearpath_dock_msgs/DockProperties.msg {#msg-dock-properties} + +``` +# Message definition containing the properties for each of the docks available. + +clearpath_dock_msgs/DockInfo[] docks +``` + +#### clearpath_dock_msgs/DockState.msg {#msg-dock-state} + +``` +# Message definition containing information on what state the docking process is in. + +uint8 UNDOCKED = 0 +uint8 DOCKED = 1 +uint8 IN_PROGRESS = 2 +uint8 FAILED = 3 +uint8 CANCELLED = 4 + +uint8 state +``` + +#### clearpath_dock_msgs/TargetTrackerState.msg {#msg-target-tracker-state} + +``` +# Message definition containing the state information of the target tracker. +# This includes whether or not the tracker is active, whether the target is visible/lost, and the target pose and score of that pose. + +bool active + +# flag indicates if the target is visible or not +bool target_locked + +geometry_msgs/PoseWithCovarianceStamped target_pose +float32 score + +# the distance of the sensor_link to the dock target +float64 distance_to_target +``` + +#### clearpath_localization_msgs/LocalizationStatus.msg {#msg-localization-status} + +``` +# Localization status message for all sources of localization + +std_msgs/Header header +float32 accuracy # IN DEVELOPMENT + +# status information related to the GPS receiver units +GNSSStatus position_gnss +GNSSStatus heading_gnss +GNSSStatus base_station_gnss + +bool dead_reckoning +``` + +#### clearpath_localization_msgs/GNSSStatus.msg {#msg-gnss-status} + +``` +# GNSS receiver status message + +uint8 POSITION_RECEIVER = 0 +uint8 HEADING_RECEIVER = 1 +uint8 BASE_STATION_RECEIVER = 2 +uint8 receiver_type + +uint8 POSITION_NO_FIX = 0 +uint8 POSITION_SPP = 1 +uint8 POSITION_SBAS = 2 +uint8 POSITION_RTK_FLOAT = 3 +uint8 POSITION_RTK_FIXED = 4 +uint8 position_fix_type + +uint8 HEADING_NOT_APPLICABLE = 0 +uint8 HEADING_NO_SOLUTION = 1 +uint8 HEADING_RTK_FLOAT = 2 +uint8 HEADING_RTK_FIXED = 3 +uint8 heading_fix_type + +uint8 num_connected_sats # Number of satellites connected to the antenna/receiver +uint8 num_sats_solution # Number of sats used in solution +float32[] cn0 # The carrier-to-noise ratio of each connected satellite +float64 correction_age # Age of RTK corrections. -1 indicates none received +``` + +#### clearpath_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} + +``` +# The entire contents of the Mission database +# Note that all of the following cases are valid: +# - a Task can be referenced in multiple Waypoints +# - a Waypoint can be referenced in multiple Missions +# - a Waypoint can be orphaned (i.e. not included in any Missions) +# - a Task can be orphaned (i.e. not included in any Waypoints) + +# All missions defined in the database +clearpath_navigation_msgs/Mission[] missions + +# All waypoints defined in the database +clearpath_navigation_msgs/Waypoint[] waypoints + +# All tasks defined in the database +clearpath_navigation_msgs/Task[] tasks +``` + +#### clearpath_navigation_msgs/Mission.msg {#msg-navigation-mission} + +``` +# Message definition for an OutdoorNav mission + +std_msgs/Header header + +# The human-readable name of this mission +string name + +# A UUID string used to uniquely identify this mission +string uuid + +# The ordered list of Waypoints that make up the mission +clearpath_navigation_msgs/Waypoint[] waypoints + +# Configuration parameters for the mission +# Additional details TBD +string onav_config +``` + +#### clearpath_navigation_msgs/DistanceToGoal.msg {#msg-distance-to-goal} + +``` +# Message includes Euclidean and Path distance to goal + +float32 euclidean +float32 path +``` + +#### clearpath_navigation_msgs/Metrics.msg {#msg-metrics} + +``` +# Message containing some metric information related to the autonomy metrics. + +float64 total_distance_travelled # [m] +float64 total_duration # [s] + +uint64 num_missions_sent +uint64 num_missions_completed +uint64 num_replans +uint64 num_recoveries +uint64 num_tasks_executed +``` + +#### clearpath_navigation_msgs/MotionState.msg {#msg-motion-state} + +``` +# Motion state message to indicate the current motion, expected motion and the direction of travel of the robot. + +# State pertaining to current motion of the robot. +uint8 MOTION_NORMAL=10 +uint8 MOTION_STOPPED=11 +uint8 MOTION_REVERSE=12 +uint8 MOTION_SLOWING=13 # Currently unused +uint8 motion + +# State pertaining to the robot's movement along the path. Predictive, ie state +# will be INDICATOR_LEFT_TURN if in or approaching a left turn. +uint8 INDICATOR_NORMAL=20 +uint8 INDICATOR_LEFT_TURN=21 +uint8 INDICATOR_RIGHT_TURN=22 +uint8 INDICATOR_CLOCKWISE=23 +uint8 INDICATOR_COUNTERCLOCKWISE=24 +uint8 INDICATOR_HAZARD=25 # Currently unused +uint8 indicator + +# Direction of travel of the robot relative to its physical forward direction. +uint8 DIRECTION_FORWARD=30 +uint8 DIRECTION_REVERSE=31 +uint8 direction +``` + +#### clearpath_navigation_msgs/NavigationState.msg {#msg-navigation-state} + +``` +# Message containing the current navigation state(s). Navigation may be in multiple states. + +uint8 STATE_IDLE = 0 +uint8 STATE_COMPUTE_PATH = 1 +uint8 STATE_EXECUTE_PATH = 2 +uint8 STATE_REPLAN = 3 +uint8 STATE_NAVIGATING_AROUND_OBSTACLE = 4 +uint8 STATE_RECOVERY = 5 +uint8 STATE_LOST = 6 +uint8 STATE_DONE = 7 +uint8 STATE_SAFETY_STOP = 8 +uint8 STATE_PAUSE = 9 +uint8 STATE_DISABLE = 10 + +uint8[] states +``` + +#### clearpath_navigation_msgs/OdomIntent.msg {#msg-odom-intent} + +``` +# Message containing current and predicted odom related information + +std_msgs/Header header + +# Current and predicted odom +perception_navigation_msgs/Odom2DLean odom +perception_navigation_msgs/Odom2DLean predicted_odom + +# Time offset corresponding to prediction +float32 dt +``` + +#### clearpath_navigation_msgs/PointVector.msg {#msg-point-vector} + +``` +# Vector of point vectors (for GUI) +std_msgs/Header header + +clearpath_navigation_msgs/Vector2D[] cloud +``` + +#### clearpath_navigation_msgs/Progress.msg (BETA) {#msg-navigation-progress} + +``` +# Message containing the completion percentage of the currently executed path and the current goal. + +float32 path_progress +float32 goal_progress +float32 mission_progress +``` + +#### clearpath_navigation_msgs/ScanPoints.msg {#msg-scan-points} + +``` +# Message definition for the detection points used by the navigation that relate to the detected obstacles. + +std_msgs/Header header + +string[] frames_vector +clearpath_navigation_msgs/PointVector[] cloud_vector +``` + +#### clearpath_navigation_msgs/Task.msg {#msg-navigation-task} + +``` +# A single task that can be executed at a Waypoint + +# The human-readable name of this task +string name + +# A UUID string to uniquely identify this Task +string uuid + +# The ROS action that this task executes +string action_server_name + +# The version of this task +string version + +# Numerical/boolean data to be passed to the action_server_name +# The exact meaning of these values is dependent on the underlying service +float64[] floats + +# String data to be passed to the action_server_name +# The exact meaning of these values is dependent on the underlying service +string[] strings +``` + +#### clearpath_navigation_msgs/TrackError.msg {#msg-track-error} + +``` +# The path error message containing the off-path cross track error and the relative heading error to the path direction + +std_msgs/Header header +float32 cross_track_error +float32 heading_error +``` + +#### clearpath_navigation_msgs/Vector2D.msg {#msg-vector-2d} + +``` +# 2D Vector of floats (used for GUI) + +float32[2] point +``` + +#### clearpath_navigation_msgs/Waypoints.msg {#msg-navigation-waypoints} + +``` +# A single Waypoint along a Mission + +# A UUID string to uniquely identify this Waypoint +string uuid + +# The human-readable name of this Waypoint +string name + +# The latitude (in degrees) of this Waypoint +float64 latitude + +# The longitude (in degrees) of this Waypoint +float64 longitude + +# The compass heading (in degrees) of this Waypoint +float64 heading + +# A radius in meters indicating the acceptable radius from the target location +# Posititon tolerance is disabled if this value is negative +float64 position_tolerance + +# A tolerance in degrees indicating the acceptable deviation from the heading +# Heading tolerance is disabled if this value is negative +float64 yaw_tolerance + +# The ordered set of Tasks to execute once the goal position & orientation are reached +clearpath_navigation_msgs/Task[] tasks +``` + +#### clearpath_platform_msgs/PlatformID.msg {#msg-platform-id} + +``` +# Platform ID message containing the model, serial #, hardware and firmware versions + +string model +string serial_id +string hardware_revision +string firmware_revision +``` + +#### clearpath_safety_msgs/WatchdogStatus.msg {#msg-safety-watchdog} + +``` +# Watchdog status message containing information related to sensor monitoring, emergency stop and safety stops + +bool[] gps_watchdog_triggered +bool[] lidar_watchdog_triggered +bool[] camera_watchdog_triggered +``` + +#### cpr_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} + +``` +# All missions defined in the database +cpr_navigation_msgs/Mission[] missions + +# All waypoints defined in the database +cpr_navigation_msgs/Waypoint[] waypoints + +# All tasks defined in the database +cpr_navigation_msgs/Task[] tasks +``` + +#### cpr_mission_scheduler_msgs/msg/NextSchedule.msg + +``` +# The ID of the next schedule to start +# Empty if nothing is scheduled +string uuid + +# The time until the schedule starts (rounded to the nearest second) +duration time_to_start +``` + +#### cpr_mission_scheduler_msgs/msg/Schedule {#scheduler-schedule} + +``` +# Single-execution mode; the schedule starts at the designated time and runs once +uint8 MODE_ONCE=0 + +# Looping mode; the schedule starts at the designated time, and every loop_interval seconds after +# for the designated number of repeats +uint8 MODE_LOOP=1 + +# Single-shot execution, but does NOT get added to the persistent storage +# Equivalent to MODE_ONCE, but for one-off, throw-away schedules (e.g. "Run X in 5 minutes") +uint8 MODE_TRANSIENT=2 + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The unique ID of this schedule +# A string of the form "12345678-90ab-cdef-1234-567890abcdef" +string uuid + +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time + +# Either MODE_ONCE or MODE_LOOP to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled +``` + +#### cpr_mission_scheduler_msgs/msg/StorageState.msg {#scheduler-state} + +``` +# Single-execution mode; the schedule starts at the designated time and runs once +uint8 MODE_ONCE=0 + +# Looping mode; the schedule starts at the designated time, and every loop_interval seconds after +# for the designated number of repeats +uint8 MODE_LOOP=1 + +# Single-shot execution, but does NOT get added to the persistent storage +# Equivalent to MODE_ONCE, but for one-off, throw-away schedules (e.g. "Run X in 5 minutes") +uint8 MODE_TRANSIENT=2 + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The unique ID of this schedule +# A string of the form "12345678-90ab-cdef-1234-567890abcdef" +string uuid + +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time + +# Either MODE_ONCE or MODE_LOOP to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled +``` + +#### cpr_mission_scheduler_msgs/msg/UtcTime.msg {#scheduler-time} + +``` +# Represents a moment in time on a 24-hour clock + +# The hour, 0-23 +uint8 hour + +# The minute, 0-59 +uint8 minute + +# The second, 0-59 +uint8 second + +# Milliseconds, 0-999 (not typically needed) +uint16 millisecond +``` + +#### Standard ROS Messages {#std-ros-msgs} + +- [actionlib_msgs/GoalID](http://docs.ros.org/en/noetic/api/actionlib_msgs/html/msg/GoalID.html) +- [diagnostic_msgs/DiagnosticArray](http://docs.ros.org/en/noetic/api/diagnostic_msgs/html/msg/DiagnosticArray.html) +- [geometry_msgs/PolygonStamped](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PolygonStamped.html) +- [geometry_msgs/Polygon](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Polygon.html) +- [geometry_msgs/PoseArray](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PoseArray.html) +- [geometry_msgs/Twist](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) +- [nav_msgs/OccupancyGrid](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/OccupancyGrid.html) +- [nav_msgs/Odometry](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html) +- [nav_msgs/Path](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Path.html) +- [sensor_msgs/Imu](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/Imu.html) +- [sensor_msgs/LaserScan](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/LaserScan.html) +- [sensor_msgs/NavSatFix](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/NavSatFix.html) +- [sensor_msgs/PointCloud2](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/PointCloud2.html) +- [std_msgs/Bool](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/Bool.html) +- [std_msgs/Empty](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/Empty.html) +- [std_msgs/String](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/String.html) +- [tf2_msgs/TFMessage](http://docs.ros.org/en/noetic/api/tf2_msgs/html/msg/TFMessage.html) +- [wireless_msgs/Connection](http://docs.ros.org/en/noetic/api/wireless_msgs/html/msg/Connection.html) + +------------------------------------------------------------------------ + +### Service Definitions + +#### clearpath_control_msgs/srv/SetControlMode.srv {#srv-set-control-mode} + +``` +# Service definition to set the control mode + +clearpath_control_msgs/ControlMode mode +--- +``` + +#### clearpath_dock_msgs/srv/AddDock.srv {#srv-add-dock} + +``` +# A dock information message that will be added to the docks list +clearpath_dock_msgs/DockInfo dock +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_dock_msgs/srv/RemoveDock.srv {#srv-remove-dock} + +``` +# A dock information message that will be added to the docks list +string uuid +string name +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_dock_msgs/srv/SetDockLocationById.srv {#srv-set-dock-location-by-id} + +``` +# The UUID of the dock we're setting a location for +# If empty, a new dock is to be added with the location +string uuid +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_dock_msgs/srv/SetDockLocationByName.srv {#srv-set-dock-location-by-name} + +``` +# The UUID of the dock we're setting a location for +# If empty, a new dock is to be added with the location +string name +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_localization_msgs/srv/SetDatum.srv {#srv-set-datum} + +``` +# Service definition to set the datum with a latitude (lat) and longitude (lon) + +float32 lat +float32 lon +--- +bool success +``` + +#### clearpath_localization_msgs/srv/ResetLocalization.srv {#srv-reset-localization} + +``` +# Service definition to reset the localization + +bool require_gnss +uint32 gnss_samples +--- +bool success +``` + + +#### clearpath_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} + +``` +# The UUID of the object we're inserting/removing +# When removing, all instances with this UUID are deleted from the parent +string uuid + +# The UUID of the parent object +string parent_uuid + +# The zero-based index to insert the object into +# Ignored when removing +int32 position +--- +# True if the object was added/removed successfully, otherwise False +bool ok +``` + +#### clearpath_mission_manager_msgs/srv/CloneMission.srv {#storage-clonemission} +``` +# The desired name for the new mission +string name + +# The additional configuration options +# see clearpath_navigation_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids +--- +# The resulting Mission, with an auto-generated UUID is returned +clearpath_navigation_msgs/Mission result +``` + +#### clearpath_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} + +``` +# The desired name for the new mission +string name + +# The additional configuration options +# see clearpath_mission_manager_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids +--- +# The resulting Mission, with an auto-generated UUID is returned +clearpath_navigation_msgs/Mission result +``` + +#### clearpath_mission_manager_msgs/srv/CreateTask.srv {#storage-createtask} + +``` +# The desired name for the Task +string name + +# The ROS Action to invoke to execute the task +string service_call + +# The version of the task +string version + +# The numerical arguments to pass to the service_call +float64[] floats + +# The string arguments to pass to the service_call +string[] strings + +# Optional list of Waypoint UUIDs to assign this task to automatically +# The new task will be appended to the end of the existing Waypoints +string[] assign_to +--- +# The resulting Task with an auto-generated UUID is returned +clearpath_navigation_msgs/Task result +``` + +#### clearpath_mission_manager_msgs/srv/CreateWaypoint.srv {#storage-createwaypoint} + +``` +# The desired name for the Waypoint +string name + +# The latitude for the Waypoint in degrees +float64 latitude + +# The longitude for the Waypoint in degrees +float64 longitude + +# The compass heading in degrees for the Waypoint +float64 heading + +# The position tolerance for the Waypoint in meters +float64 position_tolerance + +# The orientation tolerance for the Waypoint in degrees +float64 yaw_tolerance + +# Optional ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids + +# Optional list of Mission UUIDs to assign the new Waypoint to +# The new Waypoint is appended to the end of the existing Missions +string[] assign_to +--- +# The resulting Waypoint with an auto-generated UUID is returned +clearpath_navigation_msgs/Waypoint result +``` + +#### clearpath_mission_manager_msgs/srv/DeleteById.srv {#storage-deletebyid} + +``` +# The UUID of the object we want to delete +string uuid +--- +# True if the item was successfully deleted, otherwise False +bool ok +``` + +#### clearpath_mission_manager_msgs/srv/DeleteEverything.srv {#storage-deleteeverything} + +``` +# Used to permanently delete everything from the database. +# Use this service at your own risk + +# This must be set to true to confirm you really want to delete everything +bool yes_i_am_absolutely_sure_i_want_to_do_this +--- +# True if the database was cleared, otherwise False +bool ok +``` + +#### clearpath_mission_manager_msgs/srv/ExportData.srv {#storage-exportdata} + +``` +--- +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### clearpath_mission_manager_msgs/srv/GetAllMissions.srv {#storage-getallmissions} + +``` +--- +# An array of all Missions defined in the database +clearpath_navigation_msgs/Mission[] missions +``` + +#### clearpath_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} + +``` +--- +# The array of all Tasks defined in the database +clearpath_navigation_msgs/Task[] tasks +``` + +#### clearpath_mission_manager_msgs/srv/GetAllWaypoints.srv {#storage-getallwaypoints} + +``` +--- +# The array of all Waypoints defined in the database +clearpath_navigation_msgs/Waypoint[] waypoints +``` + +#### clearpath_mission_manager_msgs/srv/GetEverything.srv {#storage-geteverything} + +``` +--- +# All Missions, Waypoints, and Tasks defined in the database +clearpath_mission_manager_msgs/StorageState state +``` + +#### clearpath_mission_manager_msgs/srv/GetMission.srv {#storage-getmission} + +``` +# The UUID of the Mission we want to retrieve +string uuid +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/Mission mission +``` + +#### clearpath_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} + +``` +# The UUID of the Task we want to retrieve +string uuid +--- +# The Task with the given ID, or null if no Task with that ID exists +clearpath_navigation_msgs/Task task +``` + +#### clearpath_mission_manager_msgs/srv/GetWaypoint.srv {#storage-getwaypoint} + +``` +# The UUID of the Waypoint we want to retrieve +string uuid +--- +# The Waypoint with the given ID, or null if no Waypoint with that ID exists +clearpath_navigation_msgs/Waypoint waypoint +``` + +#### clearpath_mission_manager_msgs/srv/ImportData.srv {#storage-importdata} + +``` +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +clearpath_mission_manager_msgs/StorageState state +``` + +#### clearpath_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} + +``` +# The UUID of the mission we want to edit +string uuid + +# The human-readable name for the Mission +string name + +# The configuration parameters for the Mission +string onav_config + +# The ordered list of Waypoint UUIDs to include in the Mission +string[] waypoint_ids +--- +# The edited Mission, or null if no mission with the given ID exists +clearpath_navigation_msgs/Mission result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} + +``` +# The UUID of the Task to edit +string uuid + +# The human-readable name for the Task +string name + +# The ROS Action that the Task executes +string service_call + +# The version of the Task +string version + +# The numerical data to pass to the service_call +float64[] floats + +# The string data to pass to the service_call +string[] strings +--- +# The edited Task, or null if no Task with the given ID exists +clearpath_navigation_msgs/Task result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateWaypoint.srv {#storage-updatewaypoint} + +``` +# The UUID of the Waypoint to edit +string uuid + +# The human-readable name for the Waypoint +string name + +# The latitude of the Waypoint in degrees +float64 latitude + +# The longitude of the Waypoint in degrees +float64 longitude + +# The compass heading of the Waypoint in degrees +float64 heading + +# The Waypoint's position tolerance in meters +float64 position_tolerance + +# The Waypoint's orientation tolerance in degrees +float64 yaw_tolerance + +# The ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids +--- +# The edited Waypoint, or null if no Waypoint with the given ID exists +clearpath_navigation_msgs/Waypoint result +``` + +#### clearpath_navigation_msgs/srv/SetDelayCompensation.srv {#srv-set-delay-compensation} + +``` +# Service definition to enable/disable the delay compensation feature. If enabling, the delay to compensate for must be specified in the request. + +bool enable_delay_compensation +uint16 delay +--- +bool success +string message +``` + +#### clearpath_navigation_msgs/srv/SetPathSmoother.srv {#srv-set-path-smoother} + +``` +# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. + +bool enable_path_smoother +float32 turn_radius +float32 step_size +--- +bool success +string message +``` + +#### clearpath_navigation_msgs/srv/SetPathShifter.srv {#srv-set-path-shifter} + +``` +# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. + +bool enable_path_shifter +float32 path_shift_offset +float32 path_shift_time +--- +bool success +string message +``` + +#### clearpath_navigation_msgs/srv/SetStopDistance.srv {#srv-set-stop-distance} + +``` +# Service definition to enable/disable the stop distance. If enabling, the stop distance must be specified in the request. + +bool enable_stop_distance +float32 stop_distance +--- +bool success +string message +``` + +#### cpr_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} + +``` +# The UUID of the object we're inserting/removing +# When removing, all instances with this UUID are deleted from the parent +string uuid + +# The UUID of the parent object +string parent_uuid + +# The zero-based index to insert the object into +# Ignored when removing +int32 position +--- +# True if the object was added/removed successfully, otherwise False +bool ok +``` + +#### cpr_mission_manager_msgs/srv/CloneMission.srv {#storage-clonemission} +``` +# The UUID of the mission to clone +string uuid + +# The new name for the mission +# If blank, the old mission name will be re-used with -copy appended to the end +string new_name + +# If true, the order of the waypoints within the cloned mission are reversed +bool reverse +--- +# The Mission with the given ID, or null if no Mission with that ID exists +cpr_navigation_msgs/Mission mission +``` + +:::note + +The `reverse` parameter was added in 0.9.0 + +::: + +#### cpr_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} + +``` +# The desired name for the new mission +string name + +# The additional configuration options +# see cpr_mission_manager_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids +--- +# The resulting Mission, with an auto-generated UUID is returned +cpr_navigation_msgs/Mission result +``` + +#### cpr_mission_manager_msgs/srv/CreateTask.srv {#storage-createtask} + +``` +# The desired name for the Task +string name + +# The ROS Action to invoke to execute the task +string service_call + +# The version of the task +string version + +# The numerical arguments to pass to the service_call +float64[] floats + +# The string arguments to pass to the service_call +string[] strings + +# Optional list of Waypoint UUIDs to assign this task to automatically +# The new task will be appended to the end of the existing Waypoints +string[] assign_to +--- +# The resulting Task with an auto-generated UUID is returned +cpr_navigation_msgs/Task result +``` + +#### cpr_mission_manager_msgs/srv/CreateWaypoint.srv {#storage-createwaypoint} + +``` +# The desired name for the Waypoint +string name + +# The latitude for the Waypoint in degrees +float64 latitude + +# The longitude for the Waypoint in degrees +float64 longitude + +# The compass heading in degrees for the Waypoint +float64 heading + +# The position tolerance for the Waypoint in meters +float64 position_tolerance + +# The orientation tolerance for the Waypoint in degrees +float64 yaw_tolerance + +# Optional ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids + +# Optional list of Mission UUIDs to assign the new Waypoint to +# The new Waypoint is appended to the end of the existing Missions +string[] assign_to +--- +# The resulting Waypoint with an auto-generated UUID is returned +cpr_navigation_msgs/Waypoint result +``` + +#### cpr_mission_manager_msgs/srv/DeleteById.srv {#storage-deletebyid} + +``` +# The UUID of the object we want to delete +string uuid +--- +# True if the item was successfully deleted, otherwise False +bool ok +``` + +#### cpr_mission_manager_msgs/srv/DeleteEverything.srv {#storage-deleteeverything} + +``` +# Used to permanently delete everything from the database. +# Use this service at your own risk + +# This must be set to true to confirm you really want to delete everything +bool yes_i_am_absolutely_sure_i_want_to_do_this +--- +# True if the database was cleared, otherwise False +bool ok +``` + +#### cpr_mission_manager_msgs/srv/ExportData.srv {#storage-exportdata} + +``` +--- +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### cpr_mission_manager_msgs/srv/GetAllMissions.srv {#storage-getallmissions} + +``` +--- +# An array of all Missions defined in the database +cpr_navigation_msgs/Mission[] missions +``` + +#### cpr_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} + +``` +--- +# The array of all Tasks defined in the database +cpr_navigation_msgs/Task[] tasks +``` + +#### cpr_mission_manager_msgs/srv/GetAllWaypoints.srv {#storage-getallwaypoints} + +``` +--- +# The array of all Waypoints defined in the database +cpr_navigation_msgs/Waypoint[] waypoints +``` + +#### cpr_mission_manager_msgs/srv/GetEverything.srv {#storage-geteverything} + +``` +--- +# All Missions, Waypoints, and Tasks defined in the database +cpr_mission_manager_msgs/StorageState state +``` + +#### cpr_mission_manager_msgs/srv/GetMission.srv {#storage-getmission} + +``` +# The UUID of the Mission we want to retrieve +string uuid +--- +# The Mission with the given ID, or null if no Mission with that ID exists +cpr_navigation_msgs/Mission mission +``` + +#### cpr_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} + +``` +# The UUID of the Task we want to retrieve +string uuid +--- +# The Task with the given ID, or null if no Task with that ID exists +cpr_navigation_msgs/Task task +``` + +#### cpr_mission_manager_msgs/srv/GetWaypoint.srv {#storage-getwaypoint} + +``` +# The UUID of the Waypoint we want to retrieve +string uuid +--- +# The Waypoint with the given ID, or null if no Waypoint with that ID exists +cpr_navigation_msgs/Waypoint waypoint +``` + +#### cpr_mission_manager_msgs/srv/ImportData.srv {#storage-importdata} + +``` +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +cpr_mission_manager_msgs/StorageState state +``` + +#### cpr_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} + +``` +# The UUID of the mission we want to edit +string uuid + +# The human-readable name for the Mission +string name + +# The configuration parameters for the Mission +string onav_config + +# The ordered list of Waypoint UUIDs to include in the Mission +string[] waypoint_ids +--- +# The edited Mission, or null if no mission with the given ID exists +cpr_navigation_msgs/Mission result +``` + +#### cpr_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} + +``` +# The UUID of the Task to edit +string uuid + +# The human-readable name for the Task +string name + +# The ROS Action that the Task executes +string service_call + +# The version of the Task +string version + +# The numerical data to pass to the service_call +float64[] floats + +# The string data to pass to the service_call +string[] strings +--- +# The edited Task, or null if no Task with the given ID exists +cpr_navigation_msgs/Task result +``` + +#### cpr_mission_manager_msgs/srv/UpdateWaypoint.srv {#storage-updatewaypoint} + +``` +# The UUID of the Waypoint to edit +string uuid + +# The human-readable name for the Waypoint +string name + +# The latitude of the Waypoint in degrees +float64 latitude + +# The longitude of the Waypoint in degrees +float64 longitude + +# The compass heading of the Waypoint in degrees +float64 heading + +# The Waypoint's position tolerance in meters +float64 position_tolerance + +# The Waypoint's orientation tolerance in degrees +float64 yaw_tolerance + +# The ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids +--- +# The edited Waypoint, or null if no Waypoint with the given ID exists +cpr_navigation_msgs/Waypoint result +``` + +#### cpr_mission_scheduler_msgs/srv/CloneSchedule.srv {#scheduler-cloneschedule} + +``` +# The UUID of the schedule to clone +string uuid + +# The name for the new copy of the schedule +string new_name +--- +# The cloned schedule +# This should be identical to the original, but with a new name and new UUID +cpr_mission_scheduler_msgs/Schedule schedule +``` + +#### cpr_mission_scheduler_msgs/srv/CreateSchedule.srv {#scheduler-createschedule} + +``` +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time + +# Either Schedule.MODE_ONCE, Schedule.MODE_LOOP, OR Schedule.MODE_TRANSIENT to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled + +--- + +# The created mission, as-saved on disk +cpr_mission_scheduler_msgs/Schedule result +``` + +#### cpr_mission_scheduler_msgs/srv/EnableSchedule.srv {#scheduler-enableschedule} + +``` +# The ID of the schedule to enable/disable +string uuid + +# Should this schedule be enabled or disabled? +bool enable + +--- + +# True if we successfully enabled/disabled the schedule +# False if there was an error or the schedule wasn't found +bool ok +``` + +#### cpr_mission_scheduler_msgs/srv/ExportData.srv {#scheduler-exportdata} + +``` +--- +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### cpr_mission_scheduler_msgs/srv/GetAllSchedules.srv {#scheduler-getallschedules} + +``` +--- +cpr_mission_scheduler_msgs/Schedule[] schedules +``` + +#### cpr_mission_scheduler_msgs/srv/GetNextSchedule.srv {#scheduler-getnextschedule} + +``` +--- +# The ID of the next schedule to start +# Empty if nothing is scheduled +string uuid + +# The time until the schedule starts (rounded to the nearest second) +duration time_to_start +``` + +#### cpr_mission_scheduler_msgs/srv/GetSchedule.srv {#scheduler-getschedule} + +``` +string uuid +--- +cpr_mission_scheduler_msgs/Schedule schedule +``` + +#### cpr_mission_scheduler_msgs/srv/ImportData.srv {#scheduler-importdata} + +``` +# A base-64 encoded string representing a compressed version of +# the database contents. +# The data itself is a gzipped JSON string representing the database contents +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +cpr_mission_scheduler_msgs/StorageState state +``` + +#### cpr_mission_scheduler_msgs/srv/UpdateSchedule.srv {scheduler-updateschedule} + +``` +# The ID of the mission to edit +string uuid + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The time that this mission starts every day +cpr_mission_scheduler_msgs/UtcTime start_time + +# Either Schedule.MODE_ONCE, Schedule.MODE_LOOP, OR Schedule.MODE_TRANSIENT to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled + +--- + +# The modified mission, as-saved on disk +cpr_mission_scheduler_msgs/Schedule result +``` + +#### Standard ROS Services + +- [std_srvs/Empty](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/Empty.html) +- [std_srvs/SetBool](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/SetBool.html) + +------------------------------------------------------------------------ + +### Action Definitions + +#### clearpath_dock_msgs/action/Dock.action {#action-dock} + +``` +# Action definition for sending a Clearpath UGV to one of its charging dock. + +# goal +string uuid +bool local_mode +--- +# result +bool success +--- +# feedback +string state + +# the distance of the charger_link to the dock target +float64 distance_to_dock +``` + +#### clearpath_dock_msgs/action/Undock.action {#action-undock} + +``` +# Action definition for undocking a Clearpath UGV from one of its charging docks. + +# goal +string uuid +--- +# result +bool success +--- +# feedback +string state + +# the distance of the charger_link to the dock target +float64 distance_to_dock +``` + +#### clearpath_localization_msgs/action/SurveyBaseStation.action {#action-survey-base-station} + +``` +# Action definition for surveying the base station + +# goal +# the number of GPS fixes that will be used to compute to surveyed position +uint32 number_of_desired_fixes +--- +# result +bool success +--- +# feedback +# current progress, as a percentage, of the surveying +float32 percent_complete +``` + +#### clearpath_navigation_msgs/action/Mission.action {#action-mission} + +``` +# Action definition for sending a mission to the Clearpath OutdoorNav software + +# goal +clearpath_navigation_msgs/Mission mission +--- +# result +bool success +--- +# feedback +string state +``` + +#### clearpath_dock_msgs/action/Dock.action {#action-dock} + +``` +# Action definition for sending a Clearpath UGV to its charging dock. + +# goal +uint8 DOCK = 0 +uint8 UNDOCK = 1 +float32 type +float32 enable_predock +--- +# result +bool success +--- +# feedback +string state +float64 dist_to_dock # (IN DEVELOPMENT) +``` + +#### cpr_mission_scheduler_msgs/action/RunScheduleByUuid.action {#scheduler-runschedulebyuuid} + +``` +# Action definition for executing a schedule on-demand +# Potentially only useful for debugging + +# The UUID of the schedule to execute +string uuid + +# Wait this long before starting the schedule +duration delay +--- +# Did the schedule terminate successfully? +bool success +--- +# The ID of the mission we're executing right now +string current_mission_uuid + +# One of "waiting" or "executing" indicating what the schedule is doing +string state +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/mission_manager_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/mission_manager_api.mdx new file mode 100644 index 00000000..3b220d50 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/mission_manager_api.mdx @@ -0,0 +1,254 @@ +--- +title: Mission Manager API +sidebar_label: Mission Manager API +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Mission Manager API allows creation, deletion, and modification of OutdoorNav missions. Mission data is stored +in a databse-like structure on-disk. The web UI is the primary method of managing missions, but this service +API provides the ability to write your own UI if desired. + +### Topics Exported by Mission Manager + +#### mission_manager/state + +**Message Type:** [clearpath_mission_manager_msgs/msg/StorageState](definitions#storage-storagestate) + +**Description:** Latched topic that publishes the current database contents every time a change is made. + +### Services Exported by Mission Manager + +#### mission_manager/add_task_to_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Add an existing Task to an existing Waypoint. If the `position` parameter is negative the Task +is added to the end of the Waypoint's `tasks` list. + +#### mission_manager/add_waypoint_to_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Add an existing Waypoint to an existing Mission. If the `position` parameter is negative the Waypoint +is added to the end of the Task's `waypoints` list. + +#### mission_manager/clone_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CloneMission](definitions#storage-clonemission) + +**Description:** Create a deep-copy of a Mission. The new Mission will be given the provided name, or reuse the original +mission's name wth `-copy` appended to the end if no name is provided. All Waypoints and their associated Tasks are also +deep-copied. If the `reverse` parameter is set to `true` the order of waypoints is reversed in the new mission. + +:::note + +In 0.8.0 onward, all missions are required to have unique names. If the specified name is not unique the cloning will +fail. Cloning a mission multiple times without specifying a unique name will add incrementing numbers to the suffix: +`-copy` for the first, `-copy1` for the second, `-copy2` for the third, and so on. + +::: + +:::note + +The `reverse` parameter was added in 0.9.0 and is not available in older versions. + +::: + +#### mission_manager/clone_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions#storage-gettask) + +**Description:** Create a deep-copy of a Task. + +#### mission_manager/clone_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetWaypoint](definitions#storage-GetWaypoint) + +**Description:** Create a deep-copy of a Waypoint. The new Waypoint will be renamed to have `-copy` at the end. All +Tasks in the original Waypoint are also duplicated. + +#### mission_manager/create_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateMission](definitions#storage-createmission) + +**Description:** Create a new Mission. + +:::note + +In 0.8.0 onward, all missions are required to have unique names. Creating a mission with a duplicate mission will fail. + +::: + +#### mission_manager/create_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateTask](definitions#storage-createtask) + +**Description:** Create a new Task. + +#### mission_manager/create_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateWaypoint](definitions#storage-createwaypoint) + +**Description:** Create a new Waypoint. + +#### mission_manager/delete_all + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteEverything](definitions#storage-deleteeverything) + +**Description:** Delete everything in the database. + +:::note + +Use with extreme caution; this procedure cannot be undone. + +::: + +#### mission_manager/delete_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions#storage-deletebyid) + +**Description:** Delete the Mission with the given ID. Waypoints that are included in this mission are not +deleted, as they may be referenced by other Missions. + +#### mission_manager/delete_orphan_objects + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteEverything](definitions#storage-deleteeverything) + +**Description:** Delete all Waypoints that are not referenced by any Missions and all Tasks that are not referenced +by any Waypoints. + +:::note + +Use with caution; deleted items cannot be recovered. + +::: + +#### mission_manager/delete_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions#storage-deletebyid) + +**Description:** Delete the Task with the given ID. Any Waypoints that reference the deleted Task will be modified +to omit this Task once it is deleted. + +#### mission_manager/delete_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions#storage-deletebyid) + +**Description:** Delete the Waypoint with the given ID. Tasks that are included in this mission are not +deleted, as they may be referenced by other Waypoints. Any Missions that reference the deleted Waypoint will be +modified to omit this Waypoint once it is deleted. + +#### mission_manager/export + +**Service Type:** [clearpath_mission_manager_msgs/srv/ExportData](definitions#storage-exportdata) + +**Description:** Export the database so its contents can be restored later using the `mission_manager/import` service. + +:::note + +The data returned in a base64 encoded, gzipped JSON string representing the underlying storage file's contents. + +::: + +#### mission_manager/get_all + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetEverything](definitions#storage-geteverything) + +**Description:** Get the entire contents of the database, including all Missions, Tasks, and Waypoints. + +:::note + +If you need to maintain an up-to-date copy of the database state, rather than calling this service repeatedly you +should subscribe to the `mission_manager/state` topic. + +::: + +#### mission_manager/get_all_missions + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllMissions](definitions#storage-getallmissions) + +**Description:** Get all Missions defined in the database. + +#### mission_manager/get_all_tasks + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllTasks](definitions#storage-getalltasks) + +**Description:** Get all Tasks defined in the database. + +#### mission_manager/get_all_waypoints + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllWaypoints](definitions#storage-getallwaypoints) + +**Description:** Get all Waypoints defined in the database. + +#### mission_manager/get_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetMission](definitions#storage-getmission) + +**Description:** Get the Mission with the specified ID. + +#### mission_manager/get_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions#storage-gettask) + +**Description:** Get the Task with the specified ID. + +#### mission_manager/get_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetWaypoint](definitions#storage-getwaypoint) + +**Description:** Get the Waypoint with the specified ID. + +#### mission_manager/import + +**Service Type:** [clearpath_mission_manager_msgs/srv/ImportData](definitions#storage-importdata) + +**Description:** Overwite the database contents with data generated by the `mission_manager/export` service. + +:::note + +All existing Missions, Tasks and Waypoints are deleted permanently and the entire database contents are replaced +with the imported data. + +The data itself is a base64 encoded JSON string representing the underlying on-disk storage. + +::: + +#### mission_manager/remove_task_from_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Remove a Task from a Waypoint. All instances of the Task are removed from the given Waypoint. + +#### mission_manager/remove_waypoint_from_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Remove a Waypoint from a Mission. All instances of the Waypoint are removed from the given Mission. + +#### mission_manager/update_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateMission](definitions#storage-updatemission) + +**Description:** Modify a Mission. All attributes of the Mission are replaced with the provided values. + +:::note + +In 0.8.0 onward, all missions are required to have unique names. Assigning a name that is already in-use will result +in an error. + +::: + +#### mission_manager/update_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateTask](definitions#storage-updatetask) + +**Description:** Modify a Task. All attributes of the Task are replaced with the provided values. + +#### mission_manager/update_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateWaypoint](definitions#storage-updatewaypoint) + +**Description:** Modify a Waypoint. All attributes of the Waypoint are replaced with the provided values. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/mission_scheduler_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/mission_scheduler_api.mdx new file mode 100644 index 00000000..606e3a1c --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/mission_scheduler_api.mdx @@ -0,0 +1,199 @@ +--- +title: Mission Scheduler API +sidebar_label: Mission Scheduler API +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Mission Scheduler API provides a ROS interface for creating, deleting, editing, and executing missions on a daily +schedule. Schedules are stored in a database-like structure on-disk, and can be executed manually or automatically. + +The web UI is the primary method of creating and modifying schedules, though the ROS API is available should you wish +to write your own interface or create automation tools to interact with the scheduler. + +## The Schedule Object + +A schedule consists of one or more missions to be executed in the specified order at a particular start time. For +consistency the start time is expressed as a 24-hour time in UTC. + +The schedule must be in one of 3 modes: +- `MODE_ONCE` -- the mission is executed exactly once per day, at the indicted UTC time +- `MODE_LOOP` -- the mission is executed a set number of times per day, starting at the indicated UTC time and repeating + at fixed intervals until the desired number of repetitions is reached +- `MODE_TRANSIENT` -- the mission is run exactly once, and is not saved to the persistent storage. This is intended to + be used for deferred execution of a mission (e.g. `execute mission X in 5 minutes` would use a transient schedule) + +Deleting a mission from the Mission Manager will result in that mission being automatically removed from any schedules +it was part of. If a schedule has no missions it is automatically disabled, and cannot be re-enabled until it contains +at least one mission. + +### A Note on Schedule Timing + +Automatically-scheduled missions are executed at the provided time +/- 10 seconds. The duration provided by the +`next_schedule` topic and `get_next_schedule` service is therefore approximate. We recommend rounding the time to the +nearest minute when displaying the countdown information to the user in any sort of GUI. + +## Topics Exported by Mission Scheduler + +### mission_scheduler/next_schedule + +**Message Type:** [cpr_mission_scheduler_msgs/msg/NextSchedule](definitions#scheduler-nextschedule) + +**Description:** Publishes the UUID and duration to the next scheduled mission. If no missions are scheduled the UUID +will be blank. + +**Update Rate:** 1Hz + +### mission_scheduler/state + +**Message Type:** [cpr_mission_scheduler_msgs/msg/StorageState](definitions#scheduler-state) + +**Description:** Publishes the current state of the database. Anything that needs to display the current set of +schedules should subscribe to this topic + +**Update Rate:** Latched, publishes on state-change only + +## Services Exported by Mission Scheduler + +### mission_scheduler/add_mission + +**Service Type:** [cpr_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Add a mission to an existing schedule. + +### mission_scheduler/clone_schedule + +**Service Type:** [cpr_mission_scheduler_msgs/srv/CloneSchedule](definitions#scheduler-cloneschedule) + +**Description:** Perform a deep-copy of an existing schedule + +### mission_scheduler/create_schedule + +**Service Type:** [cpr_mission_scheduler_msgs/srv/CreateSchedule](definitions#scheduler-createschedule) + +**Description:** Create a new schedule + +### mission_scheduler/delete_all_schedules + +**Service Type:** [cpr_mission_manager_msgs/srv/DeleteEverything](definitions#storage-deleteeverything) + +**Description:** Delete all schedules. + +:::note + +This action is permanent and cannot be undone. Use with caution. + +::: + +### mission_scheduler/delete_schedule + +**Service Type:** [cpr_mission_manager_msgs/srv/DeleteById](definitions#storage-deletebyid) + +**Description:** Delete a single schedule. + +:::note + +This action is permanent and cannot be undone. Use with caution. + +::: + +### mission_scheduler/enable_schedule + +**Service Type:** [mission_scheduler/srv/UpdateSchedule](definitions#scheduler-enablechedule) + +**Description:** Enable or disable a schedule. + +:::note + +Disabled schedules can still be run manually with the `run_now` action (see below). Disabled schedules will never +be run automatically. + +::: + +### mission_scheduler/export + +**Service Type:** [cpr_mission_scheduler_msgs/srv/ExportData](definitions#scheduler-exportdata) + +**Description:** Export all schedule data to a base64 string to it can be backed-up or copied to another robot. + +:::note + +This service is intended to be used in combination with the `import_data` service to facilitate backups or +synchronizing schedules across multiple robots. + +::: + +### mission_scheduler/get_all_schedules + +**Service Type:** [mission_scheduler/srv/GetAllSchedules](definitions#scheduler-getallschedules) + +**Description:** Get the list of all schedules. The list will include enabled, disabled, and transient schedules. + +### mission_scheduler/get_next_schedule + +**Service Type:** [mission_scheduler/srv/GetNextSchedule](definitions#scheduler-getnextschedule) + +**Description:** Get the UUID of the next schedule that will be run automatically. If nothing is scheduled (e.g. because +there are no enabled schedules) the UUID will be blank. + +:::note + +The duration is the approximate time left before the schedule will be started automatically. Schedules will start at +their designated start time +/- 10 seconds. + +::: + +### mission_scheduler/get_schedule + +**Service Type:** [mission_scheduler/srv/GetSchedule](definitions#scheduler-getschedule) + +**Description:** Get the schedule with the provided UUID. If an error occurred, or no schedule with the provided UUID +exists, the returned object will have a blank UUID. + +### mission_scheduler/import + +**Service Type:** [cpr_mission_scheduler_msgs/srv/ImportData](definitions#scheduler-importdata) + +**Description:** Import data exported by the `export_data` service. This will delete all schedules and replace the +database contents with the imported data. + +:::note + +This service is intended to be used in combination with the `export_data` service to facilitate backups or +synchronizing schedules across multiple robots. + +::: + +### mission_scheduler/remove_mission + +**Service Type:** [cpr_mission_manager_msgs/srv/AddRemoveById](definitions#storage-addremovebyid) + +**Description:** Remove the mission at a given position from a schedule, or remove all copies of a mission from a +schedule + +### mission_scheduler/update_schedule + +**Service Type:** [mission_scheduler/srv/UpdateSchedule](definitions#scheduler-updateschedule) + +**Description:** Modify an existing schedule. All of the schedule's properties are overwritten with the new values +provided in the service call. + +:::note + +Before modifying a schedule it is recommended to call the `get_schedule` service to get the schedule's current state, +copy all values to the service request object, and then change the fields you want to overwrite. + +::: + +## Actions Exported by Mission Scheduler + +### mission_scheduler/run_now + +**Action Type:** [cpr_mission_scheduler_msgs/action/RunScheduleByUuid](definitions#scheduler-runschedulebyuuid) + +**Description:** Execute the schedule with the given UUID. The `delay` parameter will defer the execution by the +specified time. This action can be used to run a disabled schedule, or run a schedule at a time other than its +scheduled start time. + +**Feedback Rate:** 1Hz diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/platform_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/platform_api.mdx new file mode 100644 index 00000000..277ddc9b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_endpoints/platform_api.mdx @@ -0,0 +1,203 @@ +--- +title: Platform API +sidebar_label: Platform API +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Platform API provides topics to communicate with the hardware +platform (eg. sensor data, command velocity, tfs, etc\...). This API can +be used by autonomy software packages to interface with the hardware +platform. + +### Topics Published by UGV {#topics-published-by-platform} + +The topics in this section are published by the UGV. If available, they +are used by the OutdoorNav software. + +#### /tf + +  **Message Type:** tf2_msgs/TFMessage + +  **Description:** Transform tree describing the 3D links/frames of the +robot. + +#### /tf_static + +  **Message Type:** tf2_msgs/TFMessage + +  **Description:** Static links/frames of robot transform tree. + +#### /platform/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** Platform-level velocity used to drive the robot. + +#### /platform/description + +  **Message Type:** std_msgs/String + +  **Description:** String containing robot URDF description. + +#### /platform/diagnostics_agg + +  **Message Type:** diagnostic_msgs/DiagnosticArray + +  **Description:** Provides a list of human-readable diagnostic messages +from various subsystems (sensors, onboard systems, localization, +navigation, mapping etc.) + +#### /platform/emergency_stop + + **Message Type:** std_msgs/Bool + + **Description:** True, if robot is emergency stopped, False, otherwise. + +#### /platform/id + +  **Message Type:** [clearpath_platform_msgs/PlatformID](definitions#msg-platform-id) + +  **Description:** Contains model, serial number, and hardware revision of +the platform + +#### /platform/joint_states + +  **Message Type:** sensor_msgs/JointState + +  **Description:** Position and velocity of robot's joints. + +#### /platform/odom + +  **Message Type:** nav_msgs/Odometry + +  **Description:** Platform-level wheel odometry. + +#### /platform/odom_filtered + +  **Message Type:** nav_msgs/Odometry + +  **Description:** EKF fused odometry from available sources on the +platform. This may include the wheel odometry, imu data, etc.. + +------------------------------------------------------------------------ + +The following table contains the types of sensors that could be +integrated onto our robot platforms. + +| Type | Test | +| ---- | ---------- | +| **gps** | A singular GPS (Global Positioning System) antenna/receiver pair. These may also be referred to as GNSS receivers. | +| **ins** | An inertial navigation system (INS) that consists of an IMU and a GPS unit. | +| **imu** | An inertial measurement unit consisting of an accelerometer, gyroscope and potentially a magnetometer. | +| **lidar** | A light emitting sensor that uses this light to determine the distance to obstacles. This includes 1D, 2D and 3D range detection sensors. | +| **radar** | A radio emitting sensor used to compute distance/velocity of obstacles. | +| **camera** | A singular lens (ie. mono) camera that produces an ROS image stream. This can therefore include regular mono cameras as well as single lens thermal imagers, etc\... | +| **stereo** | A type of camera with two or more image sensors. | + +#### /sensors/imu_\[0,1,\...\]/data + +  **Message Type:** sensor_msgs/Imu + +  **Description:** Raw data from IMU (gyro / acceleration) + +#### /sensors/imu_\[0,1,\...\]/magnetic_field + +  **Message Type:** sensor_msgs/MagneticField + +  **Description:** Reports the MPU 9250 Magnetometer sensor information. + +#### /sensors/_\[0,1,\...\]/fix + +  **Message Type:** sensor_msgs/NavSatFix + +  **Type:** gps, ins + +  **Description:** GPS latitude and longitude data. This data can either +be RTK corrected or regular GPS data. + +#### /sensors/_[0,1,\...\]/heading + +  **Message Type:** sensor_msgs/Imu + +  **Type:** gps, ins, imu + +  **Description:** RTK heading data computed from a dual GPS receiver +setup. + +#### /sensors/_\[0,1,\...\]/pointcloud + +  **Message Type:** Type: sensor_msgs/PointCloud2 + +  **Type:** lidar, radar, stereo, camera + +  **Description:** Raw pointcloud data generated from the specific sensor. + +#### /sensors/_\[0,1,\...\]/scan + +  **Message Type:** sensor_msgs/LaserScan + +  **Type:** lidar, radar, stereo, camera + +  **Description:** Raw scan data generated from the specific sensor. + +#### /sensors/_\[0,1,\...\]/camera_info + +  **Message Type:** sensor_msgs/CameraInfo + +  **Type:** camera, stereo + +  **Description:** Camera information including image dimensions, +distortion parameters, calibration parameters, etc\... + +#### /sensors/_\[0,1,\...\]/image_raw + +  **Message Type:** sensor_msgs/Image + +  **Type:** camera, stereo + +  **Description:** Raw image data from the specific sensor. + +#### /sensors/_\[0,1,\...\]/depth/camera_info + +  **Message Type:** sensor_msgs/CameraInfo + +  **Type:** camera, stereo + +  **Description:** Camera information for the depth image including image dimensions, +distortion parameters, calibration parameters, etc\... + +#### /sensors/_\[0,1,\...\]/depth/image_rect_raw + +  **Message Type:** sensor_msgs/Image + +  **Type:** camera, stereo + +  **Description:** Raw depth image from the specific sensor. + +#### /onboard_systems/wireless/connection + +  **Message Type:** wireless_msgs/Connection + +  **Description:** Information about the robot's wireless connection +including ssid, frequency, bitrate, and signal and noise levels. + +#### /onboard_systems/bms/state + +  **Message Type:** sensor_msgs/BatteryState + +  **Description:** State data for each battery module installed. + +------------------------------------------------------------------------ + +### Topics Subscribed to by UGV {#topics-subscribed-by-platform} + +The UGV subscribes to the topics in this section. + +#### /cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** The command velocity to the platform layer effectively +commanding the wheels to spin. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/api_examples.mdx new file mode 100644 index 00000000..e123509b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/api_examples.mdx @@ -0,0 +1,18 @@ +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +The API Examples section is currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/mission_from_file.mdx new file mode 100644 index 00000000..2c80b317 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/mission_from_file.mdx @@ -0,0 +1,220 @@ +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +API examples are currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + +## The Code + +``` python +#! /usr/bin/env python3 + +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.yaml_config import YamlConfig +import time +import os + +# The file containing the mission configuration (adjust as needed) +MISSION_YAML_FILE = os.environ.get("HOME", "administrator") + "/example_ws/src/" + \ + "CPR-OutdoorNav/src/cpr_outdoornav_api_examples/config/sample_mission.yaml" + +class MissionFromYamlFile(RosNode): + """ + Create and run a mission loaded from a YAML configuration file. + Be sure that your robot is within 3 meters of your first Waypoint prior to starting the mission. + """ + + def __init__(self): + """Initialize the mission details and server connection.""" + + RosNode.__init__(self, 'mission_from_yaml_file') + self.mission = YamlConfig.yamlFileToMission(MISSION_YAML_FILE) + + # NOTE: to save the configuration to file, uncomment the following lines: + # YamlConfig.missionToYamlFile('/tmp/test1.yaml', self.mission) + + def run(self): + """Execute the mission.""" + + if not self.mission.startMission(): + return False + while not self.mission.isMissionComplete(): + time.sleep(1.0) + return self.mission.getMissionSuccess() + + +if __name__ == '__main__': + if MissionFromYamlFile().run(): + print("Mission completed successfully") + else: + print("Mission failed") + +``` + +## The Code Explained + +Let's break down the code. + +``` python +#! /usr/bin/env python3 +``` + +Every Python ROS Node will have this declaration at the top. The first line makes sure your script is executed as a Python3 script. + + +``` python +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.yaml_config import YamlConfig +``` + +We provide a library of classes that can be used within your file for ease of use. In the above example, we import the RosNode and YamlConfig classes. +The RosNode class is used by all of our examples to initialize a ROS node that will execute the example mission. The YamlConfig class is used to import +a YAML file and convert it to a Mission object. + +``` python +MISSION_YAML_FILE = os.environ.get("HOME", "administrator") + "/example_ws/src/" + \ + "CPR-OutdoorNav/src/cpr_outdoornav_api_examples/config/sample_mission.yaml" +``` + +This defines the file path of the YAML file that contains the mission to be executed. See the [YAML file](#yaml-file) below for the example YAML file +that will be executed. + +``` python +class MissionFromYamlFile(RosNode): +``` + +Creates a class for your example, which inherits a RosNode object. All python mission files are requried to inherit the RosNode class. + +``` python + RosNode.__init__(self, 'mission_from_yaml_file') + self.mission = YamlConfig.yamlFileToMission(MISSION_YAML_FILE)``` +``` + +Initialize the ROS node with name `mission_from_yaml_file` and import the the mission from the yaml config file. The `YamlConfig.yamlFileToMission()` function +reads teh configuration you have created in the YAML file and converts it into a Mission object. + +``` python + if not self.mission.startMission(): + return False +``` + +Upon execution of the script, the `self.mission.startMission()` function creates the mission client if not yet created, connects to the mission action server +and sends the goal to the action server to begin the execution of the mission. + +``` python + while not self.mission.isMissionComplete(): + time.sleep(1.0) + return self.mission.getMissionSuccess() +``` + +`self.mission.isMissionComplete()` monitors the mission status and only proceeds to terminating the mission has completed or been cancelled. + + +## YAML File {#yaml-file} + +The following YAML file is used in the above example mission. + +``` python +mission: + header: + seq: 0 + stamp: + secs: 0 + nsecs: 0 + frame_id: '' + name: "Sample Mission" + uuid: "8f57fd20-8a8c-4748-85ef-be1495b3ee06" + waypoints: + - + name: "Waypoint: 60" + uuid: "3edcedd7-ae0d-47cf-bd23-f7988d2779b7" + latitude: 50.10950820165676 + longitude: -97.31898507913323 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 61" + uuid: "ad23202e-7067-4f1c-8677-2dc07af1e729" + latitude: 50.1095698924641 + longitude: -97.31929487427445 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 62" + uuid: "fe452e77-4a26-41b0-b4ab-ee1859612a60" + latitude: 50.109437123117864 + longitude: -97.31946787675591 + heading: -1.0 + tasks: + - + name: "Wait" + uuid: "ec1121a8-7481-420f-b532-c47ea86afcd7" + service_call: "/wait" + version: "0.0.0" + floats: [3.0] + strings: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 63" + uuid: "5ed54c1f-1599-497a-9c16-93c7ca6c355e" + latitude: 50.109384820042074 + longitude: -97.3194477601883 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 64" + uuid: "2e021345-636b-4bd3-81ba-4f6901fdc016" + latitude: 50.10934056359333 + longitude: -97.31936192949982 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 65" + uuid: "00c041ee-2ca4-40ba-8e38-65ac900d5a1d" + latitude: 50.10946930962604 + longitude: -97.31921709021302 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 66" + uuid: "a5826fc5-b696-4b63-82aa-cc2e7a426640" + latitude: 50.10949344950718 + longitude: -97.31911382516594 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 67" + uuid: "7ff204b2-79a3-46da-a8c0-2c734b4c5314" + latitude: 50.10949613171619 + longitude: -97.31898910244675 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + onav_config: "To be determined" +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/mission_with_custom_tasks.mdx new file mode 100644 index 00000000..fc062073 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/mission_with_custom_tasks.mdx @@ -0,0 +1,243 @@ +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +API examples are currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + +Before being able to run the examples similar to the one explained below, it is required that you have written your own custom tasks. See the +[Custom Tasks](../../features/custom_tasks) section for information on how to develop tasks for your application. + +## The Code + +``` python +#! /usr/bin/env python3 + +import rospy +import actionlib +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from clearpath_navigation_msgs.msg import Task, UITaskResult, UITaskAction + + +CUSTOM_ACTION_NAME = "/record_gnss" +UNSPECIFIED_HEADING = -1 + + +class MissionWithCustomTask(RosNode): + """Create and run a mission with 3 waypoints, each of which executes a custom task. + + Our goal is to set up 3 waypoints, then create a mission such that the robot drives + to each waypoint in order. In addition, at each of the waypoints, a custom task will be + called to record the timestamp, goal name, and GPS coordinates. Since this is a custom task, + it is necessary to create an actionlib server to implement the custom task. + + The main component of this example is the mission builder, which builds up the set of goals, + including information on the custom tasks, and runs the mission, to execute the custom task. + + The coordinates used in this example are based on the cpr_agriculture_gazebo + world and should be updated to match the location in which the user's + robot will be operating. + """ + + class MissionBuilder: + """Creates and runs the mission, including custom tasks.""" + + def __init__(self): + """Creates the mission with 3 waypoints and custom tasks.""" + + # First waypoint, with custom task + waypoint_a_name = "A" + custom_task_a = Task() + custom_task_a.name = "my_custom_task_a" # choose any name here + custom_task_a.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_a.version = "1.0" # choose any version + custom_task_a.floats = [1000] # param: unique ID + custom_task_a.strings = [waypoint_a_name] # param: goal name + + # Second waypoint, with custom task + waypoint_b_name = "B" + custom_task_b = Task() + custom_task_b.name = "my_custom_task_b" # choose any name here + custom_task_b.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_b.version = "1.0" # choose any version + custom_task_b.floats = [1001] # param: unique ID + custom_task_b.strings = [waypoint_b_name] # param: goal name + + # Third waypoint, with custom task + waypoint_c_name = "C" + custom_task_c = Task() + custom_task_c.name = "my_custom_task_c" # choose any name here + custom_task_c.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_c.version = "1.0" # choose any version + custom_task_c.floats = [1002] # param: unique ID + custom_task_c.strings = [waypoint_c_name] # param: goal name + + waypoints = [ + Waypoint(waypoint_a_name, "uuid-waypoint-01", 43.50076203007681, -80.546296281104, UNSPECIFIED_HEADING), + Waypoint(waypoint_b_name, "uuid-waypoint-02", 43.50073600330896, -80.54621215801687, UNSPECIFIED_HEADING, [custom_task_b]), + Waypoint(waypoint_c_name, "uuid-waypoint-03", 43.50067256664828, -80.5462159469465, UNSPECIFIED_HEADING, [custom_task_c]), + ] + + # Build mission from two waypoints with custom tasks + self._mission = Mission("Custom task mission", "uuid-mission-1", waypoints) + + def getMission(self): + """Gets a reference to the mission. + + Returns + ------- + A reference to the mission. + """ + return self._mission + + def __init__(self): + """Initializes ROS, the custom task server, GPS subscriber and mission.""" + + RosNode.__init__(self, 'mission_with_custom_task') + self._mission_builder = MissionWithCustomTask.MissionBuilder() + + + def run(self): + """Execute the mission. + + This function blocks until the mission is complete. + + Returns + ------- + True on successful execution of the mission; else False on any error. + """ + + if not self._mission_builder.getMission().startMission(): + return False + while not self._mission_builder.getMission().isMissionComplete(): + rospy.sleep(1.0) + return self._mission_builder.getMission().getMissionSuccess() + + +if __name__ == '__main__': + if MissionWithCustomTask().run(): + print("Mission completed successfully") + else: + print("Mission failed") + rospy.signal_shutdown('Done') +``` + +## The Code Explained + +``` python +import rospy +import actionlib +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from clearpath_navigation_msgs.msg import Task, UITaskResult, UITaskAction +``` + +Import the `RosNode`, `Waypoint` and `Mission` classes which will be used to create the mission to be executed. +We also import the `Task` and `UITask` messages which are used to generate the action servers. + +``` python + class MissionBuilder: + """Creates and runs the mission, including custom tasks.""" + + def __init__(self): + """Creates the mission with 3 waypoints and custom tasks.""" + + # First waypoint, with custom task + waypoint_a_name = "A" + custom_task_a = Task() + custom_task_a.name = "my_custom_task_a" # choose any name here + custom_task_a.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_a.version = "1.0" # choose any version + custom_task_a.floats = [1000] # param: unique ID + custom_task_a.strings = [waypoint_a_name] # param: goal name + + # Second waypoint, with custom task + waypoint_b_name = "B" + custom_task_b = Task() + custom_task_b.name = "my_custom_task_b" # choose any name here + custom_task_b.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_b.version = "1.0" # choose any version + custom_task_b.floats = [1001] # param: unique ID + custom_task_b.strings = [waypoint_b_name] # param: goal name + + # Third waypoint, with custom task + waypoint_c_name = "C" + custom_task_c = Task() + custom_task_c.name = "my_custom_task_c" # choose any name here + custom_task_c.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_c.version = "1.0" # choose any version + custom_task_c.floats = [1002] # param: unique ID + custom_task_c.strings = [waypoint_c_name] # param: goal name + + + waypoints = [ + Waypoint(waypoint_a_name, "uuid-waypoint-01", 50.1095255, -97.3192484, UNSPECIFIED_HEADING, [custom_task_a]), + Waypoint(waypoint_b_name, "uuid-waypoint-02", 50.1094938, -97.3191085, UNSPECIFIED_HEADING, [custom_task_b]), + Waypoint(waypoint_c_name, "uuid-waypoint-03", 50.1094600, -97.3192100, UNSPECIFIED_HEADING, [custom_task_c]), + ] + + # Build mission from two waypoints with custom tasks + self._mission = Mission("Custom task mission", "uuid-mission-1", waypoints) +``` + +We create the `MissionBuilder` subclass that will create the mission to be executed. We initialize custom task objects +where we specify the `action_server_name` field with the specific action of the custom task. These are then added to the +Waypoints as a list of tasks and the Mission object is created. + +``` python + def __init__(self): + """Initializes ROS, the custom task server, GPS subscriber and mission.""" + + RosNode.__init__(self, 'mission_with_custom_task') + self._mission_builder = MissionWithCustomTask.MissionBuilder() +``` + +We initialize the example class by starting a ROS node and initialize the mission to be executed. + +``` python + def run(self): + """Execute the mission. + + This function blocks until the mission is complete. + + Returns + ------- + True on successful execution of the mission; else False on any error. + """ + + if not self._mission_builder.getMission().startMission(): + return False + while not self._mission_builder.getMission().isMissionComplete(): + time.sleep(1.0) + return self._mission_builder.getMission().getMissionSuccess() +``` + +The `run()` function starts the mission and checks for completion. Once complete we terminate the example code. + +``` python +if __name__ == '__main__': + if MissionWithCustomTask().run(): + print("Mission completed successfully") + else: + print("Mission failed") + rospy.signal_shutdown('Done') +``` + +The main python execution block. We first initialize the example class (runs the __init__ function) and then execute the run() function which +executes the mission and outputs the status information. + + diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/monitor_status.mdx new file mode 100644 index 00000000..8aeb3ca8 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_examples/monitor_status.mdx @@ -0,0 +1,162 @@ +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::info + +API examples are currently in BETA. That is, we are providing instructions and examples of how to +generate your own example scripts using our API, however not everyone will be able to run these +scripts. During the BETA release of this feature, only a select few partners will be eligible to +run their custom example scripts. Full access/release of this feature will be available in version 0.10.0 +(estimated Nov. 2023). + +::: + +## The Code + +``` python +#! /usr/bin/env python3 + +import rospy +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from cpr_outdoornav_api_examples_lib.platform_status import PlatformStatusMonitor +from cpr_outdoornav_api_examples_lib.control_status import ControlStatusMonitor +from cpr_outdoornav_api_examples_lib.localization_status import LocalizationStatusMonitor +from cpr_outdoornav_api_examples_lib.navigation_status import NavigationStatusMonitor + + +class MonitorStatus(RosNode): + """Run a simple mission and report status throughout. + + The coordinates used in this example are based on the cpr_agriculture_gazebo + world and should be updated to match the location in which the user's + robot will be operating. + """ + + def __init__(self): + """Initialize the mission details and server connection.""" + + RosNode.__init__(self, 'monitor_status') + waypoints = [ + Waypoint("A", "uuid-waypoint-1", 50.1094938, -97.3191085), + Waypoint("B", "uuid-waypoint-2", 50.1095100, -97.3192000), + Waypoint("C", "uuid-waypoint-3", 50.1095255, -97.3192484), + ] + self.mission = Mission("Monitor status mission", "uuid-mission-1", waypoints) + self._platform_status = PlatformStatusMonitor() + self._control_status = ControlStatusMonitor() + self._localization_status = LocalizationStatusMonitor() + self._navigation_status = NavigationStatusMonitor() + + def _reportStatus(self): + """Report the current status.""" + + rospy.loginfo("--------------------------------------------------------") + self._platform_status.report() + self._control_status.report() + self._localization_status.report() + self._navigation_status.report() + + def run(self): + """Execute the mission and report status.""" + + if not self.mission.startMission(): + rospy.logerr("Failed to start mission") + return False + while not self.mission.isMissionComplete(): + self._reportStatus() + rospy.sleep(1.0) + return self.mission.getMissionSuccess() + + +if __name__ == '__main__': + if MonitorStatus().run(): + print("Mission completed successfully") + else: + print("Mission failed") + +``` + +## The Code Explained + +``` python +import rospy +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from cpr_outdoornav_api_examples_lib.platform_status import PlatformStatusMonitor +from cpr_outdoornav_api_examples_lib.control_status import ControlStatusMonitor +from cpr_outdoornav_api_examples_lib.localization_status import LocalizationStatusMonitor +from cpr_outdoornav_api_examples_lib.navigation_status import NavigationStatusMonitor +``` + +Import the `RosNode`, `Waypoint`, `Mission` classes which will be used to create the mission to be executed. We also import the +`PlatformStatusMonitor`, `ControlStatusMonitor`, `LocalizationStatusMonitor`, `NavigationStatusMonitor` classes which are set up to monitor the topics +relavant to the platform, localization, contrle selection an navigation modules respectively. + +``` python + waypoints = [ + Waypoint("A", "uuid-waypoint-1", 50.1094938, -97.3191085), + Waypoint("B", "uuid-waypoint-2", 50.1095100, -97.3192000), + Waypoint("C", "uuid-waypoint-3", 50.1095255, -97.3192484), + ] + self.mission = Mission("Monitor status mission", "uuid-mission-1", waypoints) +``` + +After initializing the ROS node, we create a mission manually by first creating a list of Waypoint objects and then adding then using the waypoint list +to construct the Mission object. + +``` python + self._platform_status = PlatformStatusMonitor() + self._control_status = ControlStatusMonitor() + self._localization_status = LocalizationStatusMonitor() + self._navigation_status = NavigationStatusMonitor() +``` + +We then initialize the platform, control, localization and navigation monitors, which subscribes to several API topics. + +``` python + def _reportStatus(self): + """Report the current status.""" + + rospy.loginfo("--------------------------------------------------------") + self._platform_status.report() + self._control_status.report() + self._localization_status.report() + self._navigation_status.report() +``` + +The `_reportStatus()` function outputs the results of the monitors to the ROS logs. This includes both the internal ROS logs as well as terminal output. + +``` python + def run(self): + """Execute the mission and report status.""" + + if not self.mission.startMission(): + rospy.logerr("Failed to start mission") + return False + while not self.mission.isMissionComplete(): + self._reportStatus() + rospy.sleep(1.0) + return self.mission.getMissionSuccess() +``` + +The `run()` function starts the mission and checks for completion. Every seconds we run the `reportStatus()` function to output the status information. +Once complete we terminate the example code. + +``` python +if __name__ == '__main__': + if MonitorStatus().run(): + print("Mission completed successfully") + else: + print("Mission failed") +``` + +The main python execution block. We first initialize the example class (runs the __init__ function) and then execute the run() function which +executes the mission and outputs the status information. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_overview.mdx new file mode 100644 index 00000000..23d711db --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/api/api_overview.mdx @@ -0,0 +1,61 @@ +--- +title: API Overview +sidebar_label: API Overview +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +While the Web User Interface provides a great way to get started quickly +with OutdoorNav Software, some users will want programmatic control or +may wish to develop their own graphical user interfaces \-- for those +users, the Application Programming Interface (API) provides the +flexibility to do so. This is illustrated in the figure below. + +
+
+ +
Interconnection between OutdoorNav Software and UGV Controller
+
+
+ +The API is, at present, a [ROS 1 Noetic](http://wiki.ros.org/noetic) API, +but will soon be extended to a ROS 2 API. The API is divided into two +sections, whose details are provided below: + +- [Platform API](./api_endpoints/platform_api): The set of [ROS + Topics](http://wiki.ros.org/Topics) are used to comminucate with the + hardware platform (eg. sensor data, wireless, battery state, command + velocity). This API can be used by autonomy software packages to + interface with the hardware platform. + - [Topics Published by UGV](/docs_outdoornav_user_manual/api/api_endpoints/platform_api#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](/docs_outdoornav_user_manual/api/api_endpoints/platform_api#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](./api_endpoints/autonomy_api): The set of [ROS + Topics](http://wiki.ros.org/Topics) that are used for monitoring and + controlling the the hardware platform through the OutdoorNav + autonomy software. + - [Topics Published by Autonomy](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api#topics-published-by-autonomy): + The set of [ROS Topics](http://wiki.ros.org/Topics) published by + OutdoorNav Software, to be subscribed to by the UGV. + - [Topics Subscribed to by Autonomy](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api#topics-subscribed-to-by-autonomy): + The set of [ROS Topics](http://wiki.ros.org/Topics) + subscribed to by OutdoorNav Software, typically published by the + client for directing OutdoorNav operation. + - [Services Exported by Autonomy](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api#services-exported-by-autonomy): + The set of [ROS Services](http://wiki.ros.org/Services) provided + by OutdoorNav Software, for use by the client to modify/control + the behaviour of the Autonomy. + - [Actions Exported by Autonomy](/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api#actions-exported-by-autonomy): + The set of [ROS Actions](http://wiki.ros.org/actionlib) provided + by OutdoorNav Software, for use by the client to modify/control + the behaviour of the Autonomy. +- [Mission Manager API](./api_endpoints/mission_manager_api): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions +- [Definitions](./api_endpoints/definitions): The set of custom + [ROS Message](http://wiki.ros.org/Messages), [ROS + Service](http://wiki.ros.org/Services), and [ROS + Action](http://wiki.ros.org/actionlib) definitions. +- API Examples: Example code to come. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/cpr_hardware.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/cpr_hardware.mdx new file mode 100644 index 00000000..9592cc29 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/cpr_hardware.mdx @@ -0,0 +1,405 @@ +--- +title: "Appendix B: CPR Hardware" +sidebar_label: "Appendix B: CPR Hardware" +sidebar_position: 13 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +When using a Clearpath Robotics UGV and Base Station, the following +hardware setup may be required. + +## Calibrating the IMU + +Although IMU magnetometers are calibrated at the factory to remove any +internal magnetic influences in the device, measurements are still +subject to influence from external magnetic anomalies when the sensor is +installed. These anomalies are divided into two classes: hard iron +offsets and soft iron distortions. Hard iron offsets are created by +objects that produce a magnetic field. Soft iron distortions are +considered deflections or alterations in the existing magnetic field. +Ideally, these influences are mitigated by installing the sensor away +from magnetic sources, such as coils, magnets, and ferrous metal +structures and mounting hardware. However, often these sources are hard +to avoid or are hidden. To mitigate this effect when using the IMU +magnetometer to aid in heading estimations, a field calibration of the +magnetometer after final installation is highly recommended. This means +that the IMU must be calibrated in the same environment that you use +your UGV for autonomous navigation. + +### Microstrain IMU + +If your UGV has a 3DM-GX5-25 Microstrain IMU, the complete instruction +on calibration of your IMU can be found in section 5.4 of the +[datasheet](https://www.microstrain.com/sites/default/files/3dm-gx5-25_user_manual_8500-0012.pdf). +Note that you need a computer with Windows system and the LORD Sensing +MIP Hard and Soft Iron Calibration software installed which can be found +at the Microstrain website. + +### UM6/7 IMU + +If you are using UM6 or UM7 IMUs, you will need the magnetometer display +package which is located at the following address on your UGV: +`~/catkin_ws/Drivers/src/imu_tools/magnetometer_display`. + +Follow these steps to calibrate the IMU on your machine: + +1. Create a catkin workspace on your local machine and copy the package + `magnetometer_display` into your src folder. Build this package with + the `catkin_make` command. + +2. Perform the following command to make the calibration script + executable: + + ``` bash + $ sudo chmod +x calibration.py + ``` + +3. Connect the IMU to your computer and launch the driver. Or if you + are on the same network as your UGV, make your UGV the ROS master + and ensure that you can echo the IMU topic on your computer. + +4. Open the `magnetometer.launch` file in the `magnetometer_display` + package and change the sections shown in the figure below. + Specifically, set `use_mag_field` to true when the IMU is outputting + magnetometer measurements with a `sensor_msgs/MagneticField` + message, otherwise set to false. Microstrain is the only IMU which + uses the MagneticField message type. + +
+
+ +
Magnetometer calibration, general launch settings
+
+
+ +5. Launch the calibration using the following command: + + ``` bash + $ roslaunch magnetometer_display magnetometer.launch + ``` + +6. Move the IMU around to get good coverage. RViz will display + magnetometer points (red) and will plot current ellipsoid fit + (green) as shown in the figure below. + +
+
+ +
Magnetometer calibration, ellipsoid fit plot
+
+
+ +7. Ellipsoid fit parameters are displayed in terminal as shown in the + figure below. + +
+
+ +
Magnetometer calibration, ellipsoid fit + parameters
+
+
+ +8. Once there are enough red points on your fitted ellipsoid, enter the + above calibrations in the IMU driver launch file. Open the + `sensor.launch` file in the `cpr_gps_localization` package and go to + the UM7 (or UM6) section of the launch file. The figure below shows + this section for the UM7. + +
+
+ +
Magnetometer calibration, ellipsoid fit settings in launch file
+
+
+ + You should enter the parameters generated in the Ellipsoid fit step + as follows (to account for the NED to ENU transform the driver + applies): + + - Launch file X = Terminal Y + - Launch file Y = Terminal X + - Launch file Z = -Terminal Z + +## RTK Positioning GPS Setup + +:::note + +Please skip this section if your robot does not have RTK GPS. + +::: + +The following configuration is for establishing communications between +the Base Station and the UGV using TCP/IP for the purpose of +transmitting RTK corrections. Before starting this procedure, make sure +that you have installed the [SwiftNav +console](https://support.swiftnav.com/support/solutions/articles/44001903699-installing-swift-console). + +### Base Station GPS Configuration + +- Connect the Swift Navigation device to a computer via USB or the USB + to Serial Adapter cable. + +- Open Swift Console and connect to the device. + +- Set the following options in the **ethernet** section as shown in + the figure below. + + 1. ip_config_mode: `Static` + 2. ip_address: `192.168.131.30` + 3. netmask: `255.255.255.0` + +
+
+ +
Base Station Ethernet settings
+
+
+ +- Set the following options in the **tcp_server1** section as show in + the figure below. + + 1. mode: `SBP` + 2. port: `55556` + 3. enabled_sbp_messages: `72,74,117,65535` + +
+
+ +
Base Station TCP1 Server settings
+
+
+ +- Set the following options in the **solution** section as shown in + the figure below. + + 1. soln_freq: `10` + 2. correction_age_max: `30` + 3. output_every_n_obs: `10` + 4. dgnss_solution_mode: `Low Latency` + +
+
+ +
Base Station Solution settings
+
+
+ +- Next the Base Station has to be surveyed. There are two ways of + doing this which are explained in [RTK Survey Positioning](#base-station-survey). +- Click Save to Flash. +- Close Swift Console. +- Disconnect the device from the computer. + +### UGV Position GPS Configuration {#ugv-position-gps-config} + +- Connect the Swift Navigation device to a computer via USB or the USB + to Serial Adapter cable. + +- Open Swift Console and connect to the device. + +- Set the following options in the **ethernet** section as shown in + the figure below. + + 1. ip_config_mode: `Static` + 2. ip_address: `192.168.131.31` + 3. netmask: `255.255.255.0` + +
+
+ +
UGV GPS Ethernet settings
+
+
+ +- Set the following options in the **tcp_client0** section as show in + the figure below. + + 1. mode: `SBP` + 2. port: `192.168.131.30:55556` + 3. enabled_sbp_messages: `0` + +
+
+ +
UGV GPS TCP Client0 settings
+
+
+ +- Set the following options in the **solution** section as show in the + figure below. + + 1. soln_freq: `10` + 2. correction_age_max: `30` + 3. output_every_n_obs: `10` + 4. dgnss_solution_mode: `Low Latency` + +
+
+ +
UGV GPS Solution settings
+
+
+ +- Click Save to Flash. + +- Close Swift Console. + +- Disconnect the device from the computer. + +Once you have entered these settings. Connect your computer to the Wi-Fi +network of the Base Station. Also make sure that the UGC (which is +connected to the UGV GPS unit) is also connected to the Base Station +Wifi. The you should be able to verify connectivity across the devices. +To check the Base Station, complete the following steps. + +- Open Swift Console on you computer +- Select **TCP/IP** +- For IP Address enter `192.168.131.30` +- For IP Port enter `55555` +- Click **OK** +- Select the **Observations** tab +- In the **Remote** section you should see observation data from your + UGV. + +To check the UGV, complete the following steps. + +- Open Swift Console +- Select **TCP/IP** +- For IP Address enter `192.168.131.31` +- For IP Port enter `55555` +- Click **OK** +- Select the **Observations** tab +- In the **Remote** section you should see observation data from your + Base Station. + +Further information on [RTK setup](https://swiftnav.freshdesk.com/support/solutions/articles/44001904334-piksi-multi-gnss-rtk-position-with-stationary-base%7D%7Bhttps://swiftnav.freshdesk.com/support/solutions/articles/44001904334-piksi-multi-gnss-rtk-position-with-stationary-base) +is available from SwiftNav. + +## RTK Survey Positioning {#base-station-survey} + +:::note + +Please skip this section if your UGV does not have RTK GPS. + +::: + +:::warning + +Once you have surveyed the location of the Base Station, you **cannot** +relocate the Base Station throughout your tests. Otherwise, this step +has to be repeated. + +::: + +There are three ways to survey the Base Station location: + +1. OutdoorNav Web User Interface (easiest/accurate), +2. Swiftnav console autosurvey (fastest/least accurate), +3. ROS launch file geodetic survey (for debug output display). + +Using the OutdoorNav Web UI is the easiest and most accurate way to do +this since it runs the ROS geodetic survey tool which uses more samples +to compute the final position of the Base Station than the Swiftnav +console. Using the geodetic ROS survey launch file directly would allow +the user to visualize the output log directly but requires preliminary +knowledge in ROS. + +### Base Station Survey: Web UI + +Using the OutdoorNav Web UI to survey the Base Station is very simple. +See [Survey Base Station](/docs_outdoornav_user_manual/getting_started/system_setup#survey_base_station) for details. + +### Base Station Survey: Piksi Console + +Use the Piksi console connect the base station GPS. Go to "Settings -\> +surveyed position", click to any field in this section and then click +the button on the top right corner "Auto Survey". The figure below +shows these steps. The last 1000 GPS points will be used to compute the +position of the Base Station. + +
+
+ +
Auto Survey
+
+
+ +After that, make sure the four fields in "surveyed position" +(broadcast, surveyed lat, surveyed lon, surveyed alt) are consistent +with your location. + +### Base Station Survey: ROS Geodetic Survey + +The `ethz_piksi_ros` repository should be installed in the UGV's +`catkin_ws`. To run the surveying process simply connect your PC to the +Base Station network, `ssh` into the UGV's computer and run the +following: + +``` bash +roslaunch {robot_name}_gps_navigation geodetic_survey.launch +``` + +where `robot_name` is either `jackal`, `husky`, or `warthog` depending +on your UGV. The surveying will begin and you will see a running tally +of the collected data. + +## RTK Heading Setup + +For the rest of this section, it is assumed that a third Swiftnav Duro +device is available with IP address of 192.168.131.32. Note that in +order to change the IP address of a Swiftnav Duro, you need to use the +Swiftnav console and connect to the device with the serial port. + +:::note + +The instructions in this section will overwrite some of the settings set +in [UGV Position GPS Configuration](#ugv-position-gps-config) on the +Position/Reference Duro receiver. This is normal since the configuration +in [UGV Position GPS Configuration](#ugv-position-gps-config) is for a UGV +with only the position Duro receiver. If the heading receiver is +connected as well, please continue with the instructions below. + +::: + +The two Swiftnav Duro GPS device on the UGV are connected via serial +cable. They are also both connected via Ethernet cable to the computer +on the UGV. For computing the heading, on Duro (the one on the rear with +IP address 192.168.131.31) operates only to provide GNSS Observations to +the other Duro that computes an RTK derived heading (the Duro on the +front with IP address 192.168.131.32). For the purposes of this +document, we will call the Duro/Piksi that operates to provide the raw +GNSS observations only the "Reference Receiver" and the Duro/Piksi +producing heading measurements the "Attitude Receiver." + +Use the Swiftnav console to connect to the Reference Receiver (with IP +address of 192.168.131.31) and insert the settings shown in the figure +below. + +
+
+ +
Reference Receiver settings
+
+
+ +Next, connect to the Attitude Receiver (with IP address of +192.168.131.32) and change the configuration as shown in the figure +below. + +
+
+ +
Attitude Receiver settings
+
+
+ +For further information please refer to [these instructions](https://swiftnav.freshdesk.com/support/solutions/articles/44001907898-rtk-heading-gnss-compass-configuration%7D%7Bhttps://swiftnav.freshdesk.com/support/solutions/articles/44001907898-rtk-heading-gnss-compass-configuration). + +## Wireless Motion Stop + +Please refer to the hardware user manual of the motion stop device for proper +usage. A trained operator should be used to supervise navigation of the +UGV under autonomous control at all times. The Operator should be +familiar with the use of the wireless motion stop device. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/_category_.json new file mode 100644 index 00000000..4c27a4d9 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Appendix C: Tuning & Customization", + "position": 14 +} \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/sensor_customization.mdx new file mode 100644 index 00000000..3839162f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/sensor_customization.mdx @@ -0,0 +1,9 @@ +--- +title: "Sensor Customization" +sidebar_label: "Sensor Customization" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Information incoming in a future release. Please contact Clearpath customer support at to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/_category_.json new file mode 100644 index 00000000..d62e291a --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx new file mode 100644 index 00000000..51639337 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -0,0 +1,9 @@ +--- +title: "Ackermann Drive" +sidebar_label: "Ackermann Drive" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +Information incoming in release 0.10.0. Please contact Clearpath customer support at support@clearpathrobotics.com to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/differential_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/differential_drive_dynamics.mdx new file mode 100644 index 00000000..87a81542 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/differential_drive_dynamics.mdx @@ -0,0 +1,562 @@ +--- +title: "Differential Drive" +sidebar_label: "Differential Drive" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +:::note + +**When tuning controllers, it is advised to always only modify one single parameter prior to each +test. This allows the user to analyze the effect of this single parameter on the controller performance.** + +::: + +# Tuning Flowchart + +When attempting to tune the navigation controller, it is recommended to follow the following +flowchart. Begin with setting up [Initial Parameters](#initialize_parameters) for your UGV. + +
+
+ +
Differential Drive Tuning Flowchart
+
+
+ +**Condition Blocks**: The condition blocks can be seen in the flowchart as **RED** decision +blocks and either contain tests needed to be run or features of the software that are +enabled/disabled. + +**Tuning Blocks**: The tuning blocks can be seen in the flowchart as **YELLOW** blocks where it +is expected that the user modifies a parameter prior to re-testing the controller. + +## Conditions Blocks {#condition_blocks} + +#### Velocity Deadband Tests {#velocity_deadband_tests} + +The "**Velocity Deadband?**" condition block asks the user to verify if there is a velocity deadband that the UGV +motors must overcome in order to move the UGV. (ie. what is the minimum velocity that the UGV +is required to receive, in order for it to move). + +To verify this, the user should set up two missions: + +1. A two Waypoint mission where the first Waypoint is located on the robot, and second Waypoint about 10-20 meters +directly in front of the UGV. This will verify the requried linear motion of the UGV. +2. A two Waypoint mission where the first Waypoint is located on the robot, and second Waypoint about 10-20 meters +directly behind the UGV. The first part of the navigation to this point (ie. the rotation to face the Waypoint) will +verify the required angular motion of the UGV. + +If the above tests demonstrate that the UGV **is stuck** in a velocity deadband and is not moving, +then proceed to [Tune Deadband](#tune_deadband). + +If the above tests demonstrate that the UGV **is NOT stuck** in a velocity deadband (ie. it can +smoothly start navigating the mission), proceed to the following condition block: [Oscillation Tests](#oscillation_tests). + +#### Oscillation Tests (Straights) {#oscillation_tests} + +The "**Oscillations on Straights?**" conditions block asks if there are any oscillations present during +normal navigation along a straight path. + +##### Tests + +To verify the amount of oscilations around the reference path, the user should set up four +missions, each of which should pass (or fall within the users requirements) prior to moving on from this section of the tuning. The start +and end points of each of the tests should be identical and the start position (XY) should +be noted/marked on the testing area. The first Waypoint should be placed on the robots current location and the second Waypoint should be +placed 20-30m away from the start position. The four UGV orientations for each test are as follows: + +1. Align the UGV with a 0° offset from the Waypoint. +2. Align the UGV with a 90° offset from the Waypoint. +3. Align the UGV with a -90° offset from the Waypoint. +4. Align the UGV with a 180° offset from the Waypoint. + +See the image below to determine the placement of the UGV. The red arrow indicates the +orientation of the UGV with respect to the Waypoint. + +
+
+ +
Oscillation Test Start Orientations
+
+
+ +It is not necessary to run all of the offset tests after every parameter change. It is enough +to progress systematically through the tests as they succeed. That is, if +there are no oscillations during a 0° offset test, proceed to run the 45° test and so on +and so forth. If the 0° offset test fails, then there is no need to run the other three tests before updating a parameter. +The condition has been satisfied when all of the test results in minimal to no +oscillations (or as is deemed acceptable). + +##### Causes + +Oscillations during navigation along straight paths can be caused by one or several of the following +reasons. They are listed here in order of likelihood of occurence: + +| | Cause | Description | +|-|-------|-------------| +| **1** | Untuned MPC parameters | The default MPC controller parameters have been tuned for CPR UGVs, and may not be the same for third-party OEM UGVs. | +| **2** | Controller delay | There may be delay present in your UGV between the time the navigation computes a command velocity and when the velocity is actually executed. This could appear as mechanical delay in your motors or even mechanical delay in the rotational components of UGVs control mechanisms . It is rarely noticed when electrical motors are used. The effect of controller delay is most commonly noticed when when entering a straight from a curve or after a pure rotation.| +| **3** | Deformable Tires | If your tires are deformable, then after coming out of a pure rotation, while the UGV may be facing the required direction of travel, a purely linear command velocity would cause the UGV to veer off to the left/right. This in turn would cause the controller to correct itself, and place it into an oscillatory motion. | +| **4** | Uneven weight distribution | If your UGV is carrying more weight on one side it may bias the UGVs motion when being command straight and veer the UGV off to one side. The controller would then consistently try to correct this bias by pulling it back towards the reference path, thus causing oscillations. | + +To determine if causes 3 and 4 may apply to you, it is a good idea to run the following test: + +1. send the following command to rotate your UGV for one full rotation, +``` bash +rostopic pub /cmd_vel geometry_msgs/Twist "linear: + x: 0.0 + y: 0.0 + z: 0.0 +angular: + x: 0.0 + y: 0.0 + z: 0.3" -r 10 +``` +2. stop the rotation by stopping the command. +3. send the following command to move the UGV purely forward, +``` bash +rostopic pub /cmd_vel geometry_msgs/Twist "linear: + x: 0.5 + y: 0.0 + z: 0.0 +angular: + x: 0.0 + y: 0.0 + z: 0.0" -r 10 +``` +4. Analyse the motion and then stop the linear motion. If the UGV drifts left/right +during step 3, then your UGV is likely to suffer from the effect of uneven weight +distribution or deformable tires. (If not, there may be bigger issues). Further +investigation/discussion with Clearpath would be required. + +If the above tests demonstrate that the UGV **is oscillating** around the reference path, +then proceed to [Reduce Oscillations](#reduce_oscillations_on_straights). + +If the above tests demonstrate that the UGV **is NOT oscillating** or **within an acceptable +range of oscillation**, proceed to onto the following condition block: [Velocity Increase](#linear_velocity_condition). + + +#### Linear Velocity Condition/Test {#linear_velocity_condition} + +The "Increase Linear Velocity?" condition block asks if the user wants to increase the linear +velocity that the UGV will travel along long straight paths. This does not mean that it will +always drive at this velocity, but it is the velocity that it will accelerate to on straights, +when starting a mission and/or when coming out of a curve. + +To test this we want to create a mission that sends the UGV to a Waypoint +directly in front of the UGVs current position. This requires two Waypoints: the first one located at the robots +current position and the second Waypoint at least 20 meters away from the start position and will depend on the +linear velocity you wish to acheive. + +If during the above test, the velocity **does not** reach the desired velocity, proceed to +[Increase Linear Velocity](#increase_linear_velocity) and repeat the above test until the +desired has been achieved. + +If the above test results in the UGVs maximum velocity reaching the desired velocity, +then proceed to checking the two subconditions: [Goal Behavior](#goal_overshoot_tests) and +[Cornering Behavior](#cornering_tests). + +:::note + +Only advance to the following condition block: [Collision Avoidance](#collision_avoidance_condition) +if the UGVs maximum velocity has reached the desired velocity and all subconditions are +also satisfied. Ie. you have tuned the corner and goal behavior to within your allowable limits. + +::: + +#### Goal State Tests {#goal_overshoot_tests} + +The "Goalpoint Overshoot?" condition block asks the user to check if, at the end of a mission, +the UGV overshoots the goalpoint. This condition should always be checked every time the +velocity is increased. A similar test can be used as in the [Velocity Increase](#linear_velocity_condition) section. + +If the test results in the UGV **overshooting the goal point**, then proceed to +[Tune Goal Behavior](#tune_goal_state). + +If the test results in a **smooth deceleration to the goal point, with the UGV completing its +mission within the required tolerance, and NO overshoot**, then proceed to re-verifying that your +changes have not caused any oscillations by returning to the [Oscillation Tests](#oscillation_tests). + +:::note + +Only advance to the following condition block: [Collision Avoidance](#collision_avoidance_condition) +if the UGVs maximum velocity has reached the desired velocity and all subconditions also +are also satisfied. Ie. you have tuned the corner and goal behavior to within your allowable limits. + +::: + +#### Corner State Tests {#cornering_tests} + +The "Overshoot/Oscillations in Corners?" condition block asks the user to check if the UGV +overshoots the entry to corners, and/or if the UGV oscillates during the cornering. This +condition should always be checked every time the velocity is increased. + +A test should be designed so that the UGV will navigate a curve/corner. This type of mission +can be set up regardless of whether or not you have set a specified turn radius for the path planner. + +The Waypoints for the test mission should be placed such that there is sufficient change in +orientation of the reference path that the controller will switch into its CORNER state. An example mission +is provided below which demonstrates said Waypoint placement (although an extreme case with lots of Waypoints +for vehicle with a large turn radius). + +
+
+ +
Example test mission (complex) for cornering tests
+
+
+ +For the current case of differential drive UGVs who are able to turn on the spot, simpler +test missions can be used that change the heading of the UGV more than 45°, at each +Waypoint. + +If the test results in the UGV **overshooting the entrance to the corner/curve**, then proceed to +the first issue listed in [Tune Corner State](#tune_cornering_state). + +If the test results in the UGV **oscillating during the corner/curve**, then proceed to +the second issue listed in [Tune Corner State](#tune_cornering_state). + +If the test results in the UGV **navigating smoothly through all curves/corners, with no +minimal oscillations and no overshoot**, then proceed to re-verifying that your +changes have not caused any oscillations during straights ([Oscillation Tests](#oscillation_tests)). + +:::note + +Only advance to the following condition block: [Collision Avoidance](#collision_avoidance_condition) +if the UGVs maximum velocity has reached the desired velocity and all subconditions are also satisfied. +Ie. you have tuned the corner and goal behavior to within your allowable limits. + +::: + +#### Collision Avoidance Condition {#collision_avoidance_condition} + +The final condition block asks the user if collision avoidance is enabled or disabled on the +UGV. + +If collision avoidance is DISABLED, then you have completed tuning your UGV. +**Congratulations!** + +When collision avoidance is ENABLED, it is recommended to begin with a straight line test as in [Velocity Increase](#linear_velocity_condition) +but with an obstacle placed roughly in the center of the predicted path (ie. at the midpoint +between the start and goal locations). This obstacle should be at least 30 cm tall +and at least 10 cm wide. The user should be ready to emergency stop the UGV if they +notice it approaching the obstacle too fast or too closely. + +If the test results in any unexpected behaviour, such as: + +1) not stopping in front of the obstacle, + +2) not navigating after stopping in front of the obstacle, + +3) jittery motion navigating around the obstacle, + +then proceed to the respective issue listed in +[Tune Collision Avoidance Behavior](#tune_collision_avoidance). + + +## Tuning Blocks {#tuning_blocks} + +#### Initialize Parameters {#initialize_parameters} + +1. Update the footprint offsets of the UGV in the `${HOME}/cpr_outdoornav_launch/outdoornav_tuning.env` file. + +
+
+ +
Differential Drive Tuning Flowchart
+
+
+ +| Environment Variable | Description | Sign | +|----------------------|-------------|------| +| FOOTPRINT_OFFSET_POS_X | Distance from base_link to the furthest edge of any part/sensor at the front of the UGV. | **+** | +| FOOTPRINT_OFFSET_NEG_X | Distance from base_link to the furthest edge of any part/sensor at the left of the UGV. | **-** | +| FOOTPRINT_OFFSET_POS_Y | Distance from base_link to the furthest edge of any part/sensor at the rear of the UGV. | **+** | +| FOOTPRINT_OFFSET_NEG_Y | Distance from base_link to the furthest edge of any part/sensor at the right of the UGV. | **-** | + +2. Update the [`vehicle_length`](../tuning_parameters/navigation_parameters#default_state_params) +parameter to be the longitudinal length (ie. along the x-axis) of your UGV. This is not +the sum of the above footprint x-axis magnitudes, but only the length of the UGV body. + +3. Update the following parameters with your UGV specific maximums and minimums: + + * [`max_fwd_velocity`](../tuning_parameters/navigation_parameters#default_state_params) + * [`min_fwd_velocity`](../tuning_parameters/navigation_parameters#default_state_params) + * [`max_rev_velocity`](../tuning_parameters/navigation_parameters#default_state_params) + * [`max_ang_velocity`](../tuning_parameters/navigation_parameters#default_state_params) + * [`max_accel`](../tuning_parameters/navigation_parameters#default_state_params) + * [`max_decel`](../tuning_parameters/navigation_parameters#default_state_params) + * [`max_ang_accel`](../tuning_parameters/navigation_parameters#default_state_params) + * [`max_lateral_accel`](../tuning_parameters/navigation_parameters#default_state_params) + +4. Update the [`stiction_compensator_fwd`](../tuning_parameters/navigation_parameters#default_state_params) +and [`stiction_compensator_yaw`](../tuning_parameters/navigation_parameters#default_state_params) to +be equivalent to the minimum linear and angular velocities that the UGV requires it to move +(eg. `stiction_compensator_fwd` would be equal to `min_fwd_velocity`). + + +#### Tune Velocity Deadband {#tune_deadband} + +To tune the velocity deadband, the user should at least start off by knowing the minimum +linear and angular velocities that the UGV motors can generate. + +If not already set from the [Initial Parameters](#initialize_parameters) section, you should set +the [`min_fwd_velocity`](../tuning_parameters/navigation_parameters#default_state_params) to the minimum +forward linear velocity that the UGV can handle. + +For each iteration of the linear deadband tuning, increment the following parameters by **0.05 m/s** +, until smooth linear motion is acheived from standstill: + +- [`min_fwd_velocity`](../tuning_parameters/navigation_parameters#default_state_params) +- [`stiction_compensator_fwd`](../tuning_parameters/navigation_parameters#default_state_params) + +For each iteration of the angular deadband tuning, increment the following parameters by **0.02 rad/s** +, until smooth angular motion is acheived from standstill: + +- [`stiction_compensator_yaw`](../tuning_parameters/navigation_parameters#default_state_params) + + +#### Reducing Oscillation (Straights) {#reduce_oscillations_on_straights} + +To tune the UGV behavior on straights when dealing with the simple cause of untuned MPC +controller parameters, we list the following parameters along with likely ranges and their initial +default values. The are listed in order of which parameter will have the most effect of improving +the performance of the current tuning block. + +| Parameter | Likely Range* | Default | +|-----------|---------------|---------| +| [`yaw_weight`](../tuning_parameters/navigation_parameters#default_state_params) | 90 - 120 | 18.0 | +| [`y_weight`](../tuning_parameters/navigation_parameters#default_state_params) | 12 - 18 | 14.0 | +| [`endpoint_multiplier`](../tuning_parameters/navigation_parameters#default_state_params) | 10 - 20 | 10 | +| [`max_lookahead`](../tuning_parameters/navigation_parameters#default_state_params) |2.5 - 3.5 | 2.5 | +| [`x_weight`](../tuning_parameters/navigation_parameters#default_state_params) | 14 - 16 | 14.0 +| [`lookahead_factor`](../tuning_parameters/navigation_parameters#default_state_params) | 1.4 - 1.6 | 1.45 | +| [`mpc_opt_maxiteration`](../tuning_parameters/navigation_parameters#default_state_params)* | 10 - 15 | 13 | +| [`discretization_steps`](../tuning_parameters/navigation_parameters#default_state_params)* | 6 - 10 | 8 | + +:::note + +\* These parameters should be changed with caution. + +::: + +When you are experiencing oscillations due to cause \#2 (controller delay) try the modifying the +following parameters: + +| Parameter | Likely Range* | Default | +|-----------|---------------|---------| +| [`enable_delay_compensation`](../tuning_parameters/navigation_parameters#delay_compensation_params) | true | false | +| [`controller_delay`](../tuning_parameters/navigation_parameters#delay_compensation_params) | depends on your delay in your system. (usually between 300 - 1000 will provide changes to the performance) | NA | + + +No available solutions yet to resolve oscillations due to causes \#3 and \#4. Please contact +Clearpath customer support at to discuss any related issue. + +#### Increase Linear Velocity {#increase_linear_velocity} + +** *The following instructions are only relevant if you are planning on +increasing the velocity of the UGV above 2.0 m/s.* ** + +To increase the UGVs maximum velocity, the following parameters should be modified. + +First, the [`mpc_horizon`](../tuning_parameters/navigation_parameters#default_state_params) parameter +should be set to: 1.0 + +The following parameters should then be modified to the desired velocity ($v_{des}$). Ie. if $v_{des}=4.0$ m/s, then you should modify both parameters to be 4.0. + +| Parameter | Value | +|-----------|-------| +| [`max_fwd_velocity`](../tuning_parameters/navigation_parameters#default_state_params) | $v_{des}$ | +| [`max_lookahead`](../tuning_parameters/navigation_parameters#default_state_params) | $v_{des}$ | + +Finally, if you are increasing the velocity to a value greater than or equal to 4.0 m/s or if you +are seeing that the velocity is being limited even after changing the above parameters, +it is possible to try and increase the size (width and height) of the local costmap in file: +`~/cpr_outdoornav_launch/onav_robots/params/platform/navigation/costmap_local.yaml`. +The limit in the velcoity is due to the fact that the lookahead distance at higher speeds ends +up exceeding the size of the local costmap. By increasing it, we allow the controller to +lookahead further and allow for that velocity increase. + +#### Tune Goal State {#tune_goal_state} + +A few different issues may have occurred that led you to tuning the goal behavior. We list a +few of them and the possible parameters that can be modified to improve the performance in and +around the goal point. + +1) Overshooting the goal point can be caused by a few factors: + +* Not decelerating fast enough or soon enough as the UGV approaches the goal. + +To tune for this issue, some parameters are listed in order in which they will have the most effect of +improving the performance of the current tuning block: + +| Parameter | Default | +|-----------|---------| +| [`goal_horizon_threshold`](../tuning_parameters/navigation_parameters#goal_state_params) | 2.0 | +| [`goal_slowdown_multiplier`](../tuning_parameters/navigation_parameters#goal_state_params) | 1.5 | +| [`goal_horizon_threshold`](../tuning_parameters/navigation_parameters#goal_state_params) | 0.8 | +| [`endpoint_multiplier_goal`](../tuning_parameters/navigation_parameters#goal_state_params) | 20 | +| [`x_weight_goal`](../tuning_parameters/navigation_parameters#goal_state_params) | 14.0 | +| [`fwd_v_weight_goal`](../tuning_parameters/navigation_parameters#goal_state_params) | 0.01 | +| [`fwd_a_weight_goal`](../tuning_parameters/navigation_parameters#goal_state_params) | 8.0 | + + +* The autonomy core not considering the goal complete because it has too high of a velocity as it +starts entering the goal tolerance. + +To to tune for this issue, modify the following parameter: + +| Parameter | Value | Default | +|-----------|-------|---------| +| [`max_speed_at_goal`](../tuning_parameters/navigation_parameters#goal_state_params) | *depends on the deceleration of your UGV* | 0.8 | + +2) Oscillations (or jittery behavior) around the goal point are typically caused by the the +tolerance at the goal point being set too small. If they are too small and the UGV is unable +to localize itself within the required position and yaw tolerances, then it will jitter and +rotate to attempt to be a precise as you are expecting it to be. To resolve this, it is advised +to slightly increase the goal tolerance parameters: + +| Parameter | Default | +|-----------|---------| +| [`goal_tolerance_xy_rtk`](../tuning_parameters/navigation_parameters#goal_state_params) | 0.1 | +| [`goal_tolerance_yaw_rtk`](../tuning_parameters/navigation_parameters#goal_state_params) | 0.25 | +| [`goal_tolerance_xy_nortk`](../tuning_parameters/navigation_parameters#goal_state_params) | 0.3 | +| [`goal_tolerance_yaw_nortk`](../tuning_parameters/navigation_parameters#goal_state_params) | 0.5 | + +:::note + +If your UGV has RTK corrections, then it is only required to modify [`goal_tolerance_xy_rtk`](../tuning_parameters/navigation_parameters#goal_state_params) +and [`goal_tolerance_yaw_rtk`](../tuning_parameters/navigation_parameters#goal_state_params). Otherwise, +only modify [`goal_tolerance_xy_nortk`](../tuning_parameters/navigation_parameters#goal_state_params) +and [`goal_tolerance_yaw_nortk`](../tuning_parameters/navigation_parameters#goal_state_params). + +::: + +A complete list of parameters that relate to the GOAL state can be found +[here](../tuning_parameters/navigation_parameters#goal_state_params), however, the above set of +parameters is likely to satisfy the users requirements. + +#### Tune Cornering State {#tune_cornering_state} + +A few different issues may have occured that led you to tuning the cornering behavior. We list a +few of them and the possible parameters that can be modified to improve the performance approaching +as well as in the corner. + +1) Overshooting the corner only to enter the turn late + +This issue occurs most often, when the controller is unable to slow the UGV down early and/or +fast enough, prior to entering the corner. A reduction in velocity earlier in the approach to +the corner will improve the cornering performance. Below some parameters are listed that will +allow the user to improve the behavior entering corners: + +| Parameter | Default | +|-----------|---------| +| [`corner_segment_slowdown`](../tuning_parameters/navigation_parameters#corner_state_params) | false | +| [`corner_lookahead`](../tuning_parameters/navigation_parameters#corner_state_params) | 5.0 | +| [`corner_detection_threshold`](../tuning_parameters/navigation_parameters#corner_state_params) | 0.15 | +| [`corner_slowdown_multiplier`](../tuning_parameters/navigation_parameters#corner_state_params) | 1.5 | + +2) Oscillations during the corner + +To reduce the oscillations in the corners, some parameters are listed in order in which they will have the most effect of +improving the performance: + +| Parameter | Default | +|-----------|---------| +| [`endpoint_multiplier_corner`](../tuning_parameters/navigation_parameters#corner_state_params) | 20.0 | +| [`curvature_slowdown`](../tuning_parameters/navigation_parameters#default_state_params) | 0.15 | +| [`controller_delay`](../tuning_parameters/navigation_parameters#delay_compensation_params) | 0 | +| [`y_weight`](../tuning_parameters/navigation_parameters#default_state_params) | 14.0 | +| [`x_weight`](../tuning_parameters/navigation_parameters#default_state_params) | 14.0 | + +The complete list of parameters that relate to the CORNER state can be found +[here](../tuning_parameters/navigation_parameters#corner_state_params), however, the above set of +parameters is likely to satisfy the users requirements. + + +#### Tune Collision Avoidance {#tune_collision_avoidance} + +A few different issues may have occured that led you to tuning the collision avoidance. We list a +few of them and the possible parameters that can be modified to improve the performance approaching +as well as navigating around detected obstacles. + +1) UGV not stopping in front of the obstacle + +This issue would either occur if the collision avoidance has been disabled, or if the detection sensors +are not populating the costmap with the obstacle(s). To enable/disable collision avoidance: + +| Parameter | Default | +|-----------|---------| +| [`ENABLE_COLLISION_AVOIDANCE`](../tuning_parameters/collision_avoidance_parameters#general_collision_avoidance_params) | true | + +For the case where the obstacle that you are using is not being detected by the detection sensors, +make sure that it is neither too short nor too thin. Use RViz to check that the local costmap is being populated with +the obstacle. + +2) UGV not navigating after stopping in front of an obstacle + +This issue is either due to the robot unable to replan around the obstacle, in which case the +following parameters may help: + +| Parameter | Default | +|-----------|---------| +| [`inflation radius`](../tuning_parameters/collision_avoidance_parameters#costmap_params) | 1.0 | +| [`cost_scaling_factor`](../tuning_parameters/collision_avoidance_parameters#costmap_params) | 0.5 | +| [`max_decel`](../tuning_parameters/navigation_parameters#default_state_params) | 0.5 | +| [`max_accel`](../tuning_parameters/navigation_parameters#default_state_params) | 0.5 | + +or that the obstacle has gotten inside of the safety footprints causing the navigation to place the +UGV in a collision state: + +Consult the [Footprint Tuning](footprint_tuning) instructions to increase the safety footprint sets. +The user can also try increasing the stop distance from the UGV to an obstacle as it decelerates +to a stop. + +| Parameter | Default | +|-----------|---------| +| [`enable_stop_distance radius`](../tuning_parameters/navigation_parameters#stop_distance_params) | false | +| [`obstacle_stop_distance`](../tuning_parameters/navigation_parameters#stop_distance_params) | 3.0 | + +3) UGV has jittery motion navigating around the obstacle, + +This issue is typically a problem when the safety footprints collide with the obstacle as it is +trying to navigate the replanned path around the obstacle: + +Consult the [Footprint Tuning](footprint_tuning) instructions to modify the safety footprint sets. + +The user can also try increasing the stop distance of the UGV to an obstacle. + +| Parameter | Default | +|-----------|---------| +| [`enable_stop_distance radius`](../tuning_parameters/navigation_parameters#stop_distance_params) | false | +| [`obstacle_stop_distance`](../tuning_parameters/navigation_parameters#stop_distance_params) | 3.0 | + + +4) UGV suddenly reducing its velocity as it accelerates up to maximum + +This issue is due to the safety footprints exceeding the length of the local costmap. Since the +safety footprints increase in length as the velocity increases, the user must also increase the +size of the local costmap. This allows the safety footprints to extend to their entire length +without triggering a "false" obstacle detection due to the footprint exceeding the local +costmap size. Increase the costmap using these parameters: + +| Parameter | Default | +|-----------|---------| +| [`local_costmap/width`](../tuning_parameters/collision_avoidance_parameters#costmap_params) | $2 * l_{max\_footprint} + 0.5$ | +| [`local_costmap/height`](../tuning_parameters/collision_avoidance_parameters#costmap_params) | $2 * l_{max\_footprint} + 0.5$ | + +where l_{max\_footprint} is the length of the largest safety footprint. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/footprint_tuning.mdx new file mode 100644 index 00000000..a36d1b85 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -0,0 +1,9 @@ +--- +title: "Footprint Tuning" +sidebar_label: "Footprint Tuning" +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +Information incoming in release 0.9.0. Please contact Clearpath customer support at to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_overview.mdx new file mode 100644 index 00000000..74d2aaa3 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_overview.mdx @@ -0,0 +1,25 @@ +--- +title: "Tuning Overview" +sidebar_label: "Tuning Overview" +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The scope of Appendix C is to provide information on how to tune the various components of +OutdoorNav. + +Instructions for tuning specific platform types can be found here: + +- [Differential Drive (Skid-Steer) Dynamics](./tuning_instructions/differential_drive_dynamics) +- [Ackermann Drive Dynamics](./tuning_instructions/ackermann_drive_dynamics) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](./tuning_parameters/localization_parameters) +- [Navigation Parameters](./tuning_parameters/navigation_parameters) +- [Collision Avoidance Parameters](./tuning_parameters/collision_avoidance_parameters) + +In future releases, we will describe how the user can [Customize their UI](./user_interface_customization) +as well as how to [Customize which Sensors](./sensor_customization) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/_category_.json new file mode 100644 index 00000000..fb6592a9 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/collision_avoidance_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/collision_avoidance_parameters.mdx new file mode 100644 index 00000000..a48e4e01 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/collision_avoidance_parameters.mdx @@ -0,0 +1,37 @@ +--- +title: "Collision Avoidance Parameters" +sidebar_label: "Collision Avoidance Parameters" +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +## General Environment Variables {#general_collision_avoidance_params} + +| Parameter | Description | File | Default | +|-----------|-------------|------|---------| +| `ENABLE_COLLISION_AVOIDANCE` | Flag to enable/disable collision avoidance | ~/cpr_outdoornav_launch/outdoornav_tuning.env | false | + + +## Costmap {#costmap_params} + +### Determine the file location of the parameter {#file_location} + +The parameters related to the costmap, can be found here: + +``` bash +~/cpr_outdoornav_launch/onav_robots/params//navigation/costmap_.yaml +``` + +If they are not listed in the above file, it is because they are using the default values and are not being overwritten. + + +The following parameters can be used to modify the costmap, specifically when trying to tune +collision avoidance. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `width` | The width of the costmap | [/navigation/*<global/local>*_costmap](#file_location) | **m** | +| `height` | The height of the costmap | [/navigation/*<global/local>*_costmap](#file_location) | **m** | +| `inflation_radius` | The radius to which the map inflates obstacle cost values | [/navigation/*<global/local>*_costmap/inflation](#file_location) | **m** | +| `cost_scaling_factor` | A scaling factor to apply to cost values during inflation. The cost function is computed as follows for all cells in the costmap further than the inscribed radius distance and closer than the inflation radius distance away from an actual obstacle | [/navigation/*<global/local>*_costmap/inflation](#file_location) | - | diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/localization_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/localization_parameters.mdx new file mode 100644 index 00000000..b8102c74 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/localization_parameters.mdx @@ -0,0 +1,9 @@ +--- +title: "Localization Parameters" +sidebar_label: "Localization Parameters" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +Information incoming in release 0.9. Please contact Clearpath customer support at to discuss the issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/navigation_parameters.mdx new file mode 100644 index 00000000..72b6da38 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -0,0 +1,167 @@ +--- +title: "Navigation Parameters" +sidebar_label: "Navigation Parameters" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +import versions from "@site/static/versions.js" + +## Controllers {#controllers} + +### Determine the file location of the parameter {#file_location} + +The parameters related to the controller, can be found here: + +``` bash +~/cpr_outdoornav_launch/onav_robots/params//navigation/controls_general.yaml +``` + +If they are not listed in the above file, it is because they are using the default values and are not being overwritten. + +### MPC Controller {#controller} + +#### MBF Plugins + +Currently we have implemented a Move-Base Flex controller plugin named: **OnavMbfMpcController** + +Two instances of this plugin are loaded at runtime by our navigation node (as seen in the table below). The parameters are equivalent for each instance of the plugin but the values of certain of these parameters are different. + +| Controller name | Description | +|-----------------|-------------| +| **`mpc_controller`** | The controller used during normal navigation and applies to tracking the paths generated between all the mission waypoints. | +| **`mpc_dock_controller`** | The controller used during docking and applies only to tracking the dock and undock paths. | + +#### MPC State Machine + +The MPC controller operates as a state machine that contains the following states: + +| MPC State | Description | Condition | +|-----------|-------------|-----------| +| **`DEFAULT`** | Standard tracking behavior. | Will revert to this state if none of the other state conditions are met. | +| **`GOAL`** | Tracking behavior as the UGV approaches the goal. | Will enter GOAL mode when the `goal_horizon_threshold` parameter distance to the goal has been reached.| +| **`PRECISE`** | State when more precision is required in the tracking. | At the start of the path, we begin in Precise mode to ensure that we have a good start to tracking.| +| **`RESCUE`** | State to rescue the tracker when the UGV is stuck. | Will enter RESCUE mode when UGV is appraching a condition that make it stuck.| +| **`HYSTERESIS`** | State when you the UGV requires compensation for tire flexion. | Will enter HYSTERESIS mode when the UGV detects that it will begin oscillating due to tire deformation. | +| **`CORNER`** | State when there is a curve or a corner ahead. | Will enter CORNER mode when the UGV approaches, within a `corner_lookahead` parameter distance, to a corner with at least `corner_detection_threshold` of a curvature.| + +#### Default State Parameters {#default_state_params} + +The following list defines the default parameters that the MPC controller uses. +For the most part, they apply to all states of the MPC controller. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `vehicle_length` | The length (longitudinally) of the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `mpc_horizon` | The prediction horizon of the MPC. | [/navigation/*<controller>*/path_tracker](#file_location) | **s** | +| `max_lookahead` | Maximum distance along the path we seek to follow. Affects how far we do collision checks as well as the maximum velocity of the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `min_lookahead` | Minimum distance along the path we seek to follow. Affects how far we do collision checks as well as the maximum velocity of the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `lookahead_smoother` | Factor between 0 and 1 that determines the smoothness of the change in lookahead distance: 0 means only maximum velocity is used to determine the horizon (can be jumpy but speeds up the UGV faster); 1 means only averaged planned velocity is used to determine the horizon (smoother but speeds up the UGV slowly). | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `lookahead_factor` | How aggressively do we want to increase the lookahead from min_lookahead to max_lookahead | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `mpc_opt_maxiteration` | The maximum number of iterations that the solver will run. Increase this value for better performance, decrease for shorter computation time. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `discretization_steps` | Number of grid points along the MPC prediction; Lower: less accuracy, but faster | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `max_fwd_velocity` | The maximum allowable linear velocity that the MPC controller can compute. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `min_fwd_velocity` | The minimum allowable linear velocity, in any mode, that the MPC controller can compute. This can be used to overcome the different deadbands that different UGVs may have. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `max_rev_velocity` | The maximum allowable reverse linear velocity (ie. positive value), in any mode, that the MPC controller can compute. By default this is set to the `max_fwd_velocity`, so only needed if your maximum linear reverse velocity is different than the forward linear velocity.| [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `max_ang_velocity` | The maximum allowable angular velocity, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative angular velocities. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad/s** | +| `max_accel` | The maximum allowable linear acceleration, in normal navigation mode, that the MPC controller can compute. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s/s** | +| `max_decel` | The maximum allowable linear deceleration (ie. negative value), in any mode, that the MPC controller can compute. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s/s** | +| `max_ang_accel` | The maximum allowable angular acceleration, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative angular accelerations. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad/s/s** | +| `max_lateral_accel` | The maximum allowable lateral acceleration, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative lateral accelerations. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s/s** | +| `stiction_compensator_fwd` | The minimum linear velocity for movement of the UGV. This should typically be the minimum linear velocity that the UGV requires for it to move. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `stiction_compensator_yaw` | The minimum angular velocity for movement of the UGV. This should typically be the minimum angular velocity that the UGV requires for it to move. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `x_weight` | Weight for state x in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `y_weight` | Weight for state y in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `yaw_weight` | Weight for state yaw in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `fwd_v_weight` | Weight for state ẋ (forward velocity) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `yaw_d_weight` | Weight for state (yaw velocity) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `fwd_a_weight` | Weight for state ẍ (forward acceleration) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `yaw_a_weight` | Weight for state (yaw acceleration) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `horizon_percent_change` | The percentage factor used when shortening the MPC horizon. This will affect how quickly we want to speed up after a curvature slowdown. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `error_slowdown_multiplier` | The amount by which to increase the MPC horizon based on the crosstrack and/or heading error. This should be greater than 1.0 since increasing the MPC horizon will decrease the maximum MPC velocity. ** Less than 1.0 will result in the opposite behaviour which is not the expected behaviour for this parameter. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `crosstrackerror_slowdown` | Threshold on the amount of crosstrack error, above which to a slowdown the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `headingerror_slowdown` | Threshold on the amount of heading error, above which to a slowdown the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `curvature_slowdown` | Threshold on the path curvature, above which to a slowdown the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `endpoint_multiplier` | Weight multiplier of the very last point along the local plan segment in MPC state: DEFAULT. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `shrinking_horizon_min` | The minimum horizon that will be used in the computation. This value will prevent the horizon from dropping below this value during all the horizon adjustments. | [/navigation/*<controller>*/path_tracker](#file_location) | **s** | +| `crosstrack_tolerance` | The amount of lateral error that the controller will handle before stopping the UGV and replanning a new path. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `reference_trajectory_factor` | A factor that will skew the path parameter. This value should be between 0 and 1. Values closer to 0.0 will skew the path param closer to the UGV, decreasing speed but increasing the accuracy of the path tracking, and vice versa as you approach 1.0. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | + +#### Goal State Parameters {#goal_state_params} + +The following parameters can be modified to tune the controller as it approaches +the goal point as well as its behavior around the goal point. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `goal_horizon_threshold` | The distance from the goal point which the MPC state will switch into state: GOAL , and begin reducing the horizon accordingly. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `goal_slowdown_multiplier` | The multiplier by which to increase the MPC horizon during the MPCs GOAL state in order to slow the UGV down from its top speed. This value should be greater than 1.0. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `max_speed_at_goal` | The maximum allowable speed at the goal point for the controller to stop and consider the goal complete. On OEM UGVs, this value should be increased. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `x_weight_goal` | Weight for state x in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `y_weight_goal` | Weight for state y in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `yaw_weight_goal` | Weight for state yaw in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `fwd_v_weight_goal` | Weight for state ẋ (forward velocity) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `yaw_d_weight_goal` | Weight for state (yaw velocity) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `fwd_a_weight_goal` | Weight for state ẍ (forward acceleration) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `yaw_a_weight_goal` | Weight for state (yaw acceleration) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `endpoint_multiplier_goal` | Weight multiplier of the very last point along the local plan segment in MPC state: GOAL. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `goal_tolerance_xy_rtk` | The (x, y) tolerance value (ie. radius) assigned to a goal, when RTK is enabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `goal_tolerance_yaw_rtk` | The yaw tolerance value (ie. heading) assigned to a goal, when RTK is enabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad** | +| `goal_tolerance_xy_nortk` | The (x, y) tolerance value (ie. radius) assigned to a goal, when RTK is disabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `goal_tolerance_yaw_nortk` | The yaw tolerance value (ie. heading) assigned to a goal, when RTK is disabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad** | + +#### Corner State Parameters {#corner_state_params} + +The following parameters can be modified to tune the behavior of the controller during and as it +as it approaches corners. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `corner_segment_slowdown` | Flag to enable/disable the slowdown behaviour in MPC state: CORNER | [/navigation/*<controller>*/path_tracker](#file_location)| **bool** | +| `corner_lookahead` | The distance on the reference path from the UGVs current location, along which to determine if a corner is present. If a corner is present the MPC state will switch to CORNER state and begin reducing the horizon accordingly. | [/navigation/*<controller>*/path_tracker](#file_location)| **m** | +| `corner_detection_threshold` | Threshold on the path curvature, between the UGVs current location and the end of the corner_lookahead distance, above which to switch the MPC in state: CORNER, and begin reducing the horizon accordingly. | [/navigation/*<controller>*/path_tracker](#file_location)| **rad** | +| `corner_slowdown_multiplier` | The multiplier by which to increase the MPC horizon during the MPCs CORNER state in order to slow the UGV down from its top speed. This value should be greater than 1.0. | [/navigation/*<controller>*/path_tracker](#file_location)| **--** | +| `endpoint_multiplier_corner` | Weight multiplier of the very last point along the local plan segment in MPC state: CORNER. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | [/navigation/*<controller>*/path_tracker](#file_location)| **--** | + +#### OEM Specific Parameters {#oem_tuning_params} + +When tuning the controller on a third-party OEM UGV, there are several other considerations +that we will not have taken into account during the tuning of our UGVs. Below, we define +parameters that may be modified to tune the controller for your third-party OEM UGV. + +##### UGV Dynamics {#platform_dynamics_params} + +The following parameters can be used to modify the dynamics model that the contrller uses to +compute command velocities. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `no_turn_on_spot_motion` | Flag to enable/disable turn on spot motion. By default, the MPC motion model is represented by a differential drive kinematics. This parameter will modify the MPC motion model to remove turn in place motions and bias the motion in the forward direction. | [/navigation/*<controller>*/path_tracker](#file_location) | - | +| `min_fwd_turn` | | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `pivot_point_offset_x` | The longitudinal offset that can be applied to the MPC model in order to account for a particular UGVs center of rotation | [/navigation/*<controller>*/path_tracker](#file_location) | - | +| `pivot_point_offset_y` | The lateral offset that can be applied to the MPC model in order to account for a particular UGVs center of rotation | [/navigation/*<controller>*/path_tracker](#file_location) | - | +| `min_fwd_turn` | | [/navigation/*<controller>*/path_tracker](#file_location) | **--**| + +##### Delay Compensation {#delay_compensation_params} + +The following parameters can be used to compensate for any delays that are present in the system. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `enable_delay_compensation` | A boolean flag to enable/disable the delay compensation feature. The delay compensation feature is used to compensate for low-level dynamics delays that may be present in the UGV to be controlled. The user can apply an input controller delay and the feature will compute command velocities that compensate for such a delay. | [/navigation/*<controller>*/path_tracker](#file_location) | **bool** | +| `controller_delay` | The amount of controller delay that the delay compensation feature will attempt to compensate for, in ms. | [/navigation/*<controller>*/path_tracker](#file_location) | **ms** | + +##### Stop Distance {#stop_distance_params} + +The following parameters can be used to set a specific stop distance away from obstacles. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `enable_stop_distance` | A flag to use enable/disable the stop distance feature. The stop distance feature forces the UGV to stop a specified distance in front of obstacles. | [/navigation/*<controller>*/path_tracker](#file_location) | **bool** | +| `obstacle_stop_distance` | The distance at which the UGV will stop in front of a detected obstacle. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | + + +## Path Planners {#path_planners} + +Information incoming in release 0.9. Please contact Clearpath customer support at to discuss the issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/user_interface_customization.mdx new file mode 100644 index 00000000..17c27a3f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/user_interface_customization.mdx @@ -0,0 +1,9 @@ +--- +title: "UI Customization" +sidebar_label: "UI Customization" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Information incoming in a future release. Please contact Clearpath customer support at to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/faq.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/faq.mdx new file mode 100644 index 00000000..28b4db4e --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/faq.mdx @@ -0,0 +1,194 @@ +--- +title: Frequently Asked Questions +sidebar_label: Frequently Asked Questions +sidebar_position: 10 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## General + +1. **How do I start, pause or stop a mission?** + + A mission can be started in a few different ways, i) through the web user interface (See [Mission Execution](./web_user_interface/ui_autonomous_mode#mission-execution)) or, + ii) through the ROS API (See [API Examples](./api/api_examples)). + +2. **When I start a mission the UGV does not move. What could be the + problem?** + + There could be one of several reasons for why this is happening: + + 1. Check that none of the onboard Motion-Stop actuators are + activated. + 2. Check that none of the wireless Motion-Stops are engaged. This + can be checked via the UI (a red Status Indicator means + Motion-Stop is engaged) or the onboard UGV lights (will flash + when Motion-Stop is engaged). + 3. If OutdoorNav is running on a Clearpath Robotics Warthog UGV + that is programmed with a Futaba controller, then ensure that + the controller is turned off. If it is on then it will be + sending "no motion" commands that will be overriding the + autonomy commands. + 4. Check the task settings for each Waypoint in the Mission. + A missing task setting for a Move PTZ task will block the + execution of the Mission it is in. + +3. **What version of ROS is compatible with OutdoorNav?** + + Currently OutdoorNav is developed in ROS 1 (and is built in Docker containers on top of ROS 1 Noetic). + So, the recommended ROS version is ROS 1 Noetic. However, although not recommended, it is still + possible to use ROS 1 Melodic. Some issues may arise related to the mismatched message types. + Also, if trying to run any python scripts as Melodic targets Python2, whereas Noetic targets Python3. + + Finally, official ROS 2 compatibility is currently unsupported. In theory, if you only have ROS 2 installed + on your system, you can try to install ROS 1 Noetic as well and set up a ros1_to_ros2 bridge. Since the + OutdoorNav software is packaged in Dockers, it will communicate directly ROS 1 and then the data can be + redirected by the ros1_to_ros2 bridge to ROS 2. + +4. **How can I record ROS data?** + + There are two ways to record ROS data. The first is [through the UI](./features/rosbag_recorder) and the + second is the more traditional method of accessing the command line of the UGV's computer and running + [rosbag record commands](http://wiki.ros.org/rosbag/Commandline). + +5. **Where do all the video/audio/images get saved from the mission tasks?** + + All of the data that gets saved (ROSbags, video recordings, audio recordings, and saved images) get stored on + UGV's computer at the following location: `~/clearpath_files/...` + +## Autonomy + +1. **Am I able to send the UGV on a repeated loop?** + + When generating a single mission on the UI or through the API, it is not possible for the + mission to start at the location of the robot and end at the location of the robot. This has to do with + the navigation thinking that the UGV has already arrived at its goal and will not generate a path through + the Waypoints. However, it is possible to split the mission into two missions (ie. one to go to a + location and the second to return to the starting point). With these two missions you will then either be + able to send each mission one after the other or you can use the [Mission Scheduler](./features/mission_scheduler). + Add the two missions to the schedule and you will have the ability to also repeat this loop as many times as needed. + +2. **Why is surveying failing?** + + There are several checks that should be done: + + - Check that the base station is powered on, and that all the devices inside are powered on. + - From the UGV's computer, check that you can ping the base station. + +``` bash +ping 192.168.131.30 +``` + +  If all of these tests PASS, contact [Support](./support). + +3. **Is it possible to increase the maximum velocity of the UGV?** + + The OutdoorNav software has been tune for specific maximum velocities depending on the platform, + 1.2 m/s, 1.0 m/s and 2.0 m/s for Jackal, Husky and Warthog UGVs, respectively. The Husky maximum velocity + is 1.0 m/s so increasing above this is not possible however if you would like to increase the maximum + velocity for either the Jackal or the Warthog, further tuning may be required. Consult the + [tuning guide](./customized_tuning/tuning_instructions/differential_drive_dynamics) and contact + [Support](./support) if required. + +4. **My robot it detecting too many obstacles and replanning too frequently. How can I resolve this?** + + Please consult the [Limitations](./features/collision_avoidance#limitations) section of the collisison + avoidance feature. It will describe some limits to the obstaacle detection and can help you improve the + smoothness of the navigation. + +5. **I am getting a 'Robot too far off path warning'. What should I do?** + + These types of warnings appear on the UI under two conditions: + i) If the robot indicator (blue arrow on the UI) is not within 3.0 meters of the first Waypoint (the Green one on the UI). + ii) If the robot is outside of the allowable navigable space (defined by the path contraint, default: 3.0 meters around the reference path). + Enable the visualization of the [path contraint](./web_user_interface/ui_autonomous_mode#constrained_path) and Teleop the robot back into the + navigable space. + +6. **How can I remove certain sensors from the collision avoidance pipeline?** + + If your robot is equipped with collision avoidance sensors (eg. Velodyne, Hokuyo, Sick LMS), it is + possible to enable/disable the throughput of each sensor data into the collision avoidance pipeline. + Consult the [Collision Avoidance](./features/collision_avoidance) section for these instructions. + +7. **Can I use OutdoorNav without using the UI?** + + We empower customers to send mission via either the UI or our [ROS 1 API](./api/api_overview). Through this + API, you are enabled to write either CPP code or Python scripts where you would generate your mission, survey the base station, + set the datum, assign [custom tasks](./features/custom_tasks) to your mission. If using Python, we provide a set of libraries that + speed up the develpment process. See some of the [example codes](./api/api_examples) for an idea of how to generate these scripts. + +## Web User Interface + +1. **How do I delete a waypoint on the UI?** + + Make sure the **Edit Missions** toggle is enabled, then click the + **Waypoint Mode** button. Now you can click the Waypoint you wish to + delete. A drop down list will appear. Select **Delete**. + +2. **How do I add a Task to a Waypoint on the UI?** + + See [Add Task to Waypoint](./web_user_interface/ui_autonomous_mode#add-task) for information on how + to add a Task to a Waypoint. + +3. **Why is the "Save Image" Task failing?** + + Check the Waypoints that have a **Save Image** task in the Waypoint panel. + If you see a red warning triangle beside the **Save Image** task it means + that the settings for this task were not properly set. Set them and rerun + the mission. + +4. **Are we able to make any changes to the UI?** + + Unfortunately, users are not currently enabled to make modifications to the user interface. + This feature will be available in a future release. Please direct any feature requests to [Support](./support). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](./features/custom_tasks) instructions. When adding the + custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_autonomous_mode#add-task) + for your custom task are correct. + +6. **Why are either of the GNSS Status indicator (POS and/or DIR) on the UI not Green?** + + i) If the **POS** indicator is YELLOW, and you are using an RTK base station: + - Check communication between the robot and the base station by pinging 192.168.131.30 (from the UGV's computer) + - Re-survey the base station + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the both the base station IP (192.168.131.30) and the position unit IP (192.168.131.31) and ensure that certain + settings are set correctly: + On the base station unit: + 1) surveyed_position/broadcast = True + tcp_server1/mode = SBP + tcp_server1/enabled sbp messages = 72,74,117,65535,114 + tcp_server1/address = 55556 + On the position unit: + 2) tcp_client0/mode = SBP + tcp_client0/enabled sbp messages = 0 + tcp_client0/address = 192.168.131.30:55556 + ii) If the **POS** indicator is RED: + - Check communication between the robot and the position GNSS unit by pinging 192.168.131.31 (from the UGV's computer) + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the position unit IP (192.168.131.31) and ensure that the unit is working by checking that satellites are being + tracked in the "Tracking" tab. + + iii) If the **DIR** indicator is YELLOW, + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the position unit IP (192.168.131.31) and the heading unit IP (192.168.131.32), and ensure that certain + settings are set correctly: + On the position unit: + 1) tcp_server1/mode = SBP + tcp_server1/enabled sbp messages = 74,117 + tcp_server1/address = 55556 + On the heading unit: + 2) tcp_client0/mode = SBP + tcp_client0/enabled sbp messages = 0 + tcp_client0/address = 192.168.131.31:55556 + solution/dgnss_solution_mode = Time Matched + solution/heading offset = 0 + solution/send heading = True + solution/soln freq = 5 + solution/output ever n obs = 1 + + iv) If the **DIR** indicator is RED: + - Check communication between the robot and the position GNSS unit by pinging 192.168.131.31 (from the UGV's computer) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/_category_.json new file mode 100644 index 00000000..732c6cb7 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/collision_avoidance.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/collision_avoidance.mdx new file mode 100644 index 00000000..f32f5f66 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/collision_avoidance.mdx @@ -0,0 +1,334 @@ +--- +title: Collision Avoidance +sidebar_label: Collision Avoidance +sidebar_position: 2 +toc_min_heading_level: 2 +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. + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + +The collision avoidance feature of OutdoorNav allows our platforms to detect, +replan and then navigate around any obstacles that may be present in the UGV's +path. The workflow of this feature can be seen in the figure below. + + +
+
+ +
Collision avoidance workflow
+
+
+ +The detection sensors available on the UGV will have their data filtered, if necessary into data +that can be fed into the costmap(s). The costmap will then use this filtered data +to generate two costmaps (local and global). + +- **global costmap**: A large costmap (whose size gets set relative to the +Waypoints of the desired mission) the replanned paths around detected obstacles. +- **local costmap**: A smaller costmap that is used solely for detecting potential +collisions and triggering the path replanner. + +Therefore, there are two components in which we can tune the behaviour of the collision +avoidance feature: the sensor filters or the costmap generation. We will expand on these below. + +## Sensor Tuning + +The following table lists the sensors that are useable with the +OutdoorNav software. The sensor drivers can be turned on/off using +these environment variables, however, the sensor will always remain +powered on. The environment variables, should be added to the +`~/cpr_outdoornav_launch/env/sensors_customization.env` file. + +| Environment Variable | Description | Data Type +|--------------------------------|-------------------------------------------|-------------- +| **SWIFTNAV_ENABLE_DRIVER** | Enable/disable the Swiftnav Piksi/Duro ROS driver, if integrated. | bool | +| **UBLOX_ENABLE_DRIVER** | Enable/disable the UBlox ROS driver, if integrated. | bool | +| **MICROSTRAIN_ENABLE_DRIVER** | Enable/disable the Microstrain GX5/CV5 ROS driver, if integrated. | bool | +| **XSENS_ENABLE_DRIVER** | Enable/disable the XSens MTI ROS driver, if integrated. | bool | +| **VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (rear unit if more than one). | bool | +| **LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (rear unit if more than one). | bool | +| **HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (rear unit if more than one). | bool | +| **D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (rear unit if more than one). | bool | + + +### Sensor Filters + +:::info + +It is currently only possible to use one filter of the 3D LiDAR filters (voxel, cropbox, radius, or statistical outlier) at a +time on any source of data. In future releases we plan on expanding this to work as a filter chain. + +::: + +The following list of environment variables can be used to filter the +sensor data in order to modify/improve the sensory input to the +OutdoorNav autonomy. It is recommended that you first consult the +following links before attempting to modify these parameters. + +- [PCL Filters](http://wiki.ros.org/pcl_ros/Tutorials/filters) +- [PointCloud to LaserScan Filter](http://wiki.ros.org/pointcloud_to_laserscan) +- [DepthImage to LaserScan Filter](http://wiki.ros.org/depthimage_to_laserscan) + +#### Voxel Grid Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_VOXEL** | Enable/disable the PCL voxel filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FIL_FILTER_VOXEL_LEAF_SIZE** | The size of a leaf (on x,y,z), in meters, used for downsampling. Range: 0.0 to 1.0. | double (0.01) | + +#### Cropbox Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_CROPBOX** | Enable/disable the PCL cropbox filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_CROPBOX_MIN_X** | The lower bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(0.01) | +| **PCL_FILTER_CROPBOX_MAX_X** | The upper bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(2.0) | +| **PCL_FILTER_CROPBOX_MIN_Y** | The lower bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-10.0) | +| **PCL_FILTER_CROPBOX_MAX_Y** | The upper bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | +| **PCL_FILTER_CROPBOX_MIN_Z** | The lower bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-0.5) | +| **PCL_FILTER_CROPBOX_MAX_Z** | The upper bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | + +#### Radius Outlier Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_RADIUS_OUTLIER** | Enable/disable the PCL radius outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_ROR_RADIUS_SEARCH** | The number of points within this distance, in meters, from the query point will need to be equal or greater than PCL_FILTER_ROR_MIN_NEIGHBORS in order to be classified as an inlier point (i.e. will not be filtered). | double
(0.05) | +| **PCL_FILTER_ROR_MIN_NEIGHBORS** | The number of points within PCL_FILTER_ROR_RADIUS_SEARCH from the query point will need to be equal or greater than this number in order to be classified as an inlier point (i.e. will not be filtered). | int
(10) | + +#### Statistical Outlier Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_STATISTICAL_OUTLIER** | Enable/disable the PCL statistical outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_SOR_MEAN_K** | The number of points (k) to use for mean distance estimation Range: 2 to 100. | double
(5.0) | +| **PCL_FILTER_SOR_STD_DEV** | The standard deviation multiplier threshold. All points outside the mean +- sigma * std_mul will be considered outliers. Range: 0.0 to 5.0. | double
(0.3) | + +#### PointCloud to LaserScan Filter + +The following filter is enabled by default and is applied after any 3D LiDAR filtering has occured. It projects the final pointcloud topic onto the 2D plane that is then used to generate the costmap. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_POINTCLOUD_TO_LASERSCAN** | Enable/disable the pointcloud to laserscan outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_TO_SCAN_MIN_HEIGHT** | The minimum height to sample in the point cloud, in meters. | double
(0.2) | +| **PCL_TO_SCAN_MAX_HEIGHT** | The maximum height to sample in the point cloud, in meters. | double
(1.2) | +| **PCL_TO_SCAN_MIN_ANGLE** | The minimum scan angle, in radians. | double
(3.14) | +| **PCL_TO_SCAN_MAX_ANGLE** | The maximum scan angle, in radians. | double
(3.14) | +| **PCL_TO_SCAN_ANGLE_INCREMENT** | Resolution of laser scan, in radians, per ray. | double
(0.00218) | +| **PCL_TO_SCAN_TIME** | The scan rate in seconds. | double
(0.3333) | +| **PCL_TO_SCAN_MIN_RANGE** | The minimum ranges to return, in meters. | double
(0.3) | +| **PCL_TO_SCAN_MAX_RANGE** | The maximum ranges to return, in meters. | double
(100.0) | + + +#### DepthImage to LaserScan Filter + +Applicable for depth image data published on the `../depth/image_rect_raw` topic. + +Eg. Realsense [`DepthImage`](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/Image.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_DEPTH_TO_LASERSCAN** | Enable/disable the depth image to laserscan outlier filter for the sensor of type .

type = {D435, REAR_D435} | bool
(false) | +| **DEPTH_TO_SCAN_HEIGHT** | The number of pixel rows to use to generate the laserscan. For each column, the scan will return the minimum value for those pixels centered vertically in the image. | int | +| **DEPTH_TO_SCAN_TIME** | Time between scans (seconds). Typically, 1.0/frame_rate. This value is not easily calculated from consecutive messages, and is thus left to the user to set correctly. | double | +| **DEPTH_TO_SCAN_MIN_RANGE** | The minimum ranges to return in meters. Ranges less than this will be output as -Inf. | double | +| **DEPTH_TO_SCAN_MAX_RANGE** | The maximum ranges to return in meters. Ranges greater than this will be output as +Inf. | double | + + +## Costmap Tuning + +The following section provides a list of environment variables that can +be modified in order to tune OutdoorNav. All of the environment variables listed below +can be modified in the `~/cpr_outdoornav_launch/env/autonomy_customization.env` file. + +### Costmap Inputs + +The following table lists the environment variables that can be used to +enable/disable which sensor is used as part of the collision avoidance +feature of OutdoorNav. + +| Environment Variable | Description | Data Type | +|----------------------|------------------------------------------|-----------| +| **VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | + +### Costmap Generation + +The following list of environment variables can be used to modify some +of the navigation inputs of to the OutdoorNav autonomy. It is +recommended that you first consult the following link(s) before +attempting to modify these parameters. + +- [Costmap2D/ObstacleLayer](http://wiki.ros.org/costmap_2d/hydro/obstacles) + +| Environment Variable | Description | Data Type | +|----------------------|------------------------------------------|-----------| +| **COSTMAP\_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | +| **COSTMAP\_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | +| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (rear unit if more than one). | double | +| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | + + +## Limitations + +The collision avoidance feature as it currently stands, does come with some limitations. These are listed listed below: + +#### Detection range limits + +The maximum collision avoidance range for the OutdoorNav Software is +UGV-dependent and is related to the maximum speed of the UGV. These +ranges for Clearpath Robotics UGVs are: + +- Jackal UGV: 4.5 meters +- Husky UGV: 4.5 meters +- Warthog UGV: 15.0 meters + +While the sensors are able to detect objects at further distances, the +OutdoorNav Software only considers obstacles detected within these +distances for collision avoidance. That is, the UGV will only begin to +decelerate as it detects obstacles within this range. + +The detection itself is also related to the horizontal size +(width/diameter) of the obstacle. The limitations in detecting objects +with small horizontal size are described in the table below. + +_Maximum Reliable Obstacle Detection Distance from UGV, according to Obstacle Horizontal Size_ + +| Object Size (Horizontal) | Starter Sensor Kit | Standard/(CUstom w/ VLP) Sensor Kit | +|--------------------------|----------------------------------------------------------------|----------------------------------------------------------------| +| Less than 0.6 cm | No reliable detection | No reliable detection | +| 0.6 to 1.0 cm | 0.8 m | No reliable detection | +| 1.0 to 3.0 cm | 2.0 m | 1.75 m | +| Greater than 3.0 cm | Maximum collision avoidance distance (UGV-specific; see above) | Maximum collision avoidance distance (UGV-specific; see above) | + +Finally, the OutdoorNav Software bounds the obstacle detection to +prevent ground hits and to remove detections above the UGV body. The +following bounds are relative to the ground, assuming a flat surface. +Obstacles that are entirely below the lower bound or entirely above the +upper bound are not considered obstacles and will not be avoided. + +_Obstacle Detection Vertical Bounds_ + +| Vertical Bound | Jackal UGV | Husky UGV | Warthog UGV | +|-----------------------|------------|-----------|-------------| +| Lower Detection Bound | 0.3 m | 0.3 m | 0.3 m | +| Upper Detection Bound | 0.8 m | 1.3 m | 1.8 m | + +:::note + +The vertical detection bounds above are for the Standard Sensor Kit or a +custom sensor configuration that includes a Velodyne. The vertical +detection bounds for the Starter Sensor Kit have yet to be determined. + +::: + +#### Tall grass + +**Description**: Grass that is taller than 15cm may occasionally be detected as the robot is driving. + +**Workaround Available?**: Yes (Mitigation) + +**Mitigating Solution**: There are a couple of ways to reduce the amount of detections of long blades of grass. + +1) Apply either a radial filter or a statistical outlier filter on the pointcloud data to filter out the stray detections. + +- File: `~/cpr_outdoornav_launch/env/sensors_customization.env` +- Environment variable(s): `_ENABLE_FILTER_RADIUS_OUTLIER`, `_ENABLE_FILTER_STATISTICAL_OUTLIER` + +2) Increase the pointcloud to laserscan conversion filter minimum height parameter. The environment variable + +- File: `~/cpr_outdoornav_launch/env/sensors_customization.env` +- Environment variable(s): `PCL_TO_SCAN_MIN_HEIGHT` + +#### Pitch changes + +**Description**: Pitch changes along the UGVs planned path may cause the ground to be detected and +unwanted replanning may occur. This occurs because since we do not track change in pitch of the robot, +and since we filter the sensor data such that essentially chop off the lower portion of the data. +With the change in pitch this lower plane will then cause ground detections. + +**Workaround Available?**: Yes (Mitigation) + +**Mitigating Solution**: Limit the range from the `base_link` that the costmap generates lethal +obstacles, for a specific sensor. Eg. If your UGV has both a 3D and a 2D LiDAR. We want to limit +the range at which the 2D LiDAR will generate obstacles since the 3D LiDAR will cover a majority +of the detections. You would be able to reduce the range that the 2D LiDAR generates obstacles, +so that it does not overlap with the detection field of the 3D LiDAR. + +- File: `~/cpr_outdoornav_launch/env/autonomy_customization.env` +- Environment variable(s): `COSTMAP_LIDAR_2D_OBSTACLE_RANGE` and/or `COSTMAP_REAR_LIDAR_2D_OBSTACLE_RANGE` + +#### Branches across narrow path + +**Description**: If there are overhanging branches across a path (ie. not coming from the ground), +the navigation may not be able to maneuver through them. + +**Workaround Available?**: Limited to None + +**Mitigating Solution**: Reduction of the global costmap `inflation_radius` and/or `costmap_scaling_factor` +parameters may provide sufficient space for the navigation to replan though the branches. + +- File: `~/cpr_outdoornav_launch/env/onav_robots/params//navigation/costmap_global.yaml` +- Environment variable(s): `/navigation/global_costmap/inflation/inflation_radius` and/or `/navigation/global_costmap/inflation/cost_scaling_factor` + +:::info + +See the bottom of [this](http://wiki.ros.org/costmap_2d/hydro/inflation) page for information on how the +costmap inflation layer costs are computed based on the above two parameters. + +::: + +#### Reflective surfaces + +**Description**: Reflective surfaces on or around the robot can cause false positive obstacle placement +at incorrect locations on the costmap. + +**Workaround Available?**: No software workaround available. + +**Mitigating Solution**: Remove/cover/re-position all reflective surfaces on the robot. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/custom_tasks.mdx new file mode 100644 index 00000000..32c3115e --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/custom_tasks.mdx @@ -0,0 +1,203 @@ +--- +title: Custom Tasks +sidebar_label: Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Users can create their custom tasks for their application following a specific template. When creating these tasks, the user should begin by creating a python file in the **~/cpr_outdoornav_launch/custom_tasks** directory. The file should be written following +the instructions provided below: + +1. Import the `custom_task_base` package. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * +``` + +2. The user should then create a class name to replace `CustomTask` and initialize it with the +`CustomTaskBase`'s __init__ function and the action server name for the task. + +```python +class CustomTask(CustomTaskBase): + def __init__(self): + # The derived class must always call the super() and provide the action server name. + # This name will need to be unique among custom tasks and must match what is in the + # UI. + super().__init__("custom_task_name") +``` + +:::note + +The `CustomTaskBase` exposes a `SimpleActionServer` (see here +for further details) object as `_as`, a `UITaskFeedback` object as `_feedback` and a `UITaskResults` object as `_result` to be used as part of +the tasks functionality. + +::: + +3. The last requirement is that the `CustomTask` needs to have the `run_task(self, goal)` function be defined, +which takes in the UITaskGoal. + +```python + def run_task(self, goal): +``` + +:::note + +When running the task users may handle errors through the action servers `set_aborted()` function. When this function is called the entire mission +will be aborted. + +::: + +4. Restarting the UGV will trigger the system to load the custom task that was created, making it available for mission use. +If a custom task is not configured properly the custom task manager will ignore the task and proceed loading in the next task while logging an error with ROS. + + +## Sample Custom Tasks + +### Input Looper + +Below is a sample template file named "input_looper.py" which iterates throught the two data variables and publishes them to the feedback +topic. If neither of the variables have any data in them the task is aborted. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * + +class InputLooperTask(CustomTaskBase): + def __init__(self): + # The derived class must always call the super() and provide the action server name. + # This name will need to be unique among custom tasks and must match what is in the + # UI. + super().__init__("input_looper") + + def run_task(self, goal): + if len(goal.strings) == 0 and len(goal.floats) == 0: + # Task and running mission will be aborted in this case + self._as.set_aborted() + return False + + # Loop through the strings and float values and publish them each to the /input_looper/feedback topic + for string in goal.strings: + self._feedback.state = string + self._as.publish_feedback(self._feedback) + + for num in goal.floats: + self._feedback.state = str(num) + self._as.publish_feedback(self._feedback) + + # Returning True or False will not currently impact the mission but will write the current state to the + # /task/result topic accordingly. + return True +``` + +### Record GNSS Data + +Below is a sample custom task file named "record_gnss.py" which outputs the current GNSS data to the console. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * +from sensor_msgs.msg import NavSatFix +from threading import Lock +import rospy + +class RecorGNSSTask(CustomTaskBase): + def __init__(self): + super().__init__("record_gnss") + self._sub = rospy.Subscriber("/sensors/gps_0/fix", NavSatFix, self.gpsSubscriberCallback) + self.gps_lat = 0.0 + self.gps_lon = 0.0 + self._gps_coordinates_lock = Lock() + + def run_task(self, goal): + feedback = UITaskFeedback() + feedback.state = 'Recording GNSS lat/lon' + self._as.publish_feedback(feedback) + msg = "" + with self._gps_coordinates_lock: + msg = "ID: %f Name: %s Latitude: %f Longitude: %f" % ( + goal.floats[0], goal.strings[0], self.gps_lat, self.gps_lon) + rospy.loginfo(msg) + return True + + def gpsSubscriberCallback(self, msg): + with self._gps_coordinates_lock: + self.gps_lat = msg.latitude + self.gps_lon = msg.longitude +``` + + +### Move PTZ camera to a Lat/Lon + +Below is a more advanced custom task. The file is "move_ptz_lat_lon.py" which pans a PTZ camera to point to a specific lat/lon coordinate. + +```python +from onav_tasks.custom_task_base import * +import actionlib +from clearpath_localization_msgs.srv import * +from clearpath_navigation_msgs.msg import * +from nav_msgs.msg import Odometry +from ptz_action_server_msgs.msg import PtzAction +import ptz_action_server_msgs.msg +import math +from math import remainder, tau +import rospy +from sensor_msgs import * +from tf.transformations import euler_from_quaternion, quaternion_from_euler + + + +class MovePtzLatLon(CustomTaskBase): + def __init__(self): + super().__init__("move_ptz_lat_lon") + self.localization_subscriber_ = rospy.Subscriber("/localization/odom", Odometry, self.localizationCallback) + self.move_ptz_client_ = actionlib.SimpleActionClient('/sensors/camera_0/move_ptz', PtzAction) + self.service_ = rospy.ServiceProxy('/localization/lat_lon_to_xy', ConvertLatLonToCartesian) + self.current_pose = Odometry() + + def localizationCallback(self, odom_msg): + self.current_pose = odom_msg + + def run_task(self, goal): + if len(goal.strings) == 0 and len(goal.floats) == 0: + rospy.logwarn('Warning') + self._as.set_aborted() + return False + goal_latitude = goal.floats[0] + goal_longitude = goal.floats[1] + goal_zoom = goal.floats[2] + str2 = 'Received goal latitude: ' + str(goal_latitude) + ', goal longitude: ' + str(goal_longitude) + ', zoom: ' + str(goal_zoom) + feedback = UITaskFeedback() + feedback.state = 'Aiming camera at lat-lon (' + str(goal_latitude) + ', ' + str(goal_longitude)+')' + self._as.publish_feedback(feedback) + orientation_q = self.current_pose.pose.pose.orientation + orientation_list = [orientation_q.x, orientation_q.y, orientation_q.z, orientation_q.w] + (roll, pitch, yaw) = euler_from_quaternion (orientation_list) + + gps_msg = sensor_msgs.msg.NavSatFix() + gps_msg.latitude = goal_latitude + gps_msg.longitude = goal_longitude + goal_utm = self.service_(gps_msg) + + goal_x = goal_utm.pose.pose.position.x + goal_y = goal_utm.pose.pose.position.y + + goal_angle = math.atan2(goal_y - self.current_pose.pose.pose.position.y, goal_x - self.current_pose.pose.pose.position.x) + pan_angle = math.remainder(goal_angle - yaw, math.tau) + print(pan_angle) + + self.move_ptz_client_.wait_for_server() + goal = ptz_action_server_msgs.msg.PtzGoal() + goal.pan=pan_angle + goal.tilt=0 + goal.zoom=goal_zoom + self.move_ptz_client_.send_goal(goal) + self.move_ptz_client_.wait_for_result() + print(self.move_ptz_client_.get_result()) + return True +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/foxglove_visualization.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/foxglove_visualization.mdx new file mode 100644 index 00000000..7a36a4fc --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/foxglove_visualization.mdx @@ -0,0 +1,27 @@ +--- +title: Foxglove Visualization +sidebar_label: Foxglove Visualization +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +We have enabled Foxglove visualization as part of OutdoornNav, for improved debugging and data visualization and analysis. +To access the Foxglove visualization interface for standard OutdoorNav configurations, navigate to the following +[URL](http://192.168.132.1/_/foxglove). + +For UGVs running OutdoorNav that are not equipped with a base station, you must first connect the UGV's computer to a network over the 192.168.131.xxx +subnet. You will then be able to access the platform at (`platform_pc_ip_address`/\_/foxglove), where the __ is +the IP address of the host (UGV) computer, typically 192.168.131.1. + +
+
+ +
Foxglove layout
+
+
+ +For more information on the available Foxglove panels and how to more thoroughly us it, please consult the [Foxglove documentation](https://foxglove.dev/docs/studio). \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/mission_scheduler.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/mission_scheduler.mdx new file mode 100644 index 00000000..95c87061 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/mission_scheduler.mdx @@ -0,0 +1,43 @@ +--- +title: Mission Scheduler +sidebar_label: Mission Scheduler +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +### Scheduling missions + +By selecting the "SCHEDULER" option from the upper left hand menu, the user can open the Mission Scheduler interface. This interface +allows users to schedule groups of missions to run at a later time. These schedules can be set to run only once or to be looped over a period of time. +For example, a user could create a schedule that will run 3 missions starting at 9 AM and run every hour 8 times. Once the last iteration is run, the +schedule will disable itself and can be re-enabled to run again later. The view itself can be found in the image below and is elaborated further afterwards. + +
+
+ +
Mission Scheduler View
+
+
+ +#### Adding/Updating a Schedule + +The user can either create a new schedule by filling in the appropriate fields or edit a schedule by selecting the pencil icon for that schedule +in the bottom table. The input fields are outlined as follows: + +- Name: The name of the schedule. +- Start Time: The browser's local time that the schedule will start. This is stored as UTC time on the robot. +- Enabled: Enables/Disables the schedule. When schedules are completed they will disable themselves. +- Missions: The list of missions that will run. The schedule will run the missions in the order that they are added. +- Schedule Mode: Sets the kind of schedule mode to be either "Run Once" or "Looped". If it is set to run once, the next 2 inputs will be disabled. +- Loops: The number of iterations the schedule should run for. If for example it is set to Loop 5 times then the schedule will run 5 times (instead of run once and then re-runs 5 times). +- Loop Interval: The amount of time between the start of successive loop iterations. This is independent of the mission duration. +- Minimum Battery Charge: The minimum battery percentage that the UGV should be at to run the schedule. +- Timeout: The maximum amount of time to spend on running a single loop of the schedule. If a loop exceeds this timeout value the schedule is assumed to have failed and alerts the user + accordingly. This can be set to 0 to disable the timeout feature. + +#### Schedule Table + +Schedules found in the database are displayed in a simple table at the bottom of the screen. Schedules can be enabled, edited or deleted from this table through the +icons on the right hand side. The schedules can also be sorted by name or start time in ascending/descending order. The next schedule to run (if one is available) will have +a small information icon next to it's name and will also be reported at the top of the screen. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/navigation.mdx new file mode 100644 index 00000000..39e6dea1 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/navigation.mdx @@ -0,0 +1,38 @@ +--- +title: Navigation Features +sidebar_label: Navigation Features +sidebar_position: 1 +toc_min_heading_level: 2 +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. + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + +The OutdoorNav Software contains a set of features that can be enabled +or disabled according to your required application requirements. These +features can be enabled or disabled through the use of environment +variables, which should be added to the +`~/cpr_outdoornav_launch/env/autonomy_customization.env` file. The +following table describes the available features, their default state +and any additional parameters that we expose that may also be included +to tune the feature. + +| Feature | Description | +|-----------------------------|----------------------------------------| +| **Collision Avoidance** | Collision avoidance is the UGV's ability to detect obstacles and stop/maneuver around the obstacle without any collisions. If `true`, the UGV will detect obstacles and if `false` no obstacles will be detected. Setting to `false` is not recommended and may cause harm to property or to individuals.

Environment Variable: `ENABLE_COLLISION_AVOIDANCE` (Default: `true`). | +| **Constrained Planning** | The constrained replanning feature, which is always enabled, restricts the area in which the UGV can plan paths. For example, if the default `PATH_CONSTRAINT` of 3.0 m is used, the UGV will not be allowed to 1) produce paths that drives it more than 3.0 meters from the initial path, and 2) fail to compute paths if the UGV is further than 3.0 meters from the any of the Waypoints. This allowable planning/navigation area can be shown on the map over the connecting lines between Waypoints. See [Constrained Replanning](../web_user_interface/ui_autonomous_mode#constrained_path) for further details.

Use the `PATH_CONSTRAINT` environment variable to modify the path constraint (in meters). | +| **Path Smoothing** | Generate paths according to a specified turning radius.

Environment Variable: `ENABLE_DUBINS_PATH_SMOOTHER` (Default: `false`).

Use the `TURN_RADIUS` environment variable to modify the radius of the planned paths (in meters). | +| **Stop Distance** | The stop distance feature allows the UGV to stop a predefined distance away from obstacles. This is useful if a UGV cannot drive in reverse and needs the required room in front of it to replan around an obstacle.

Environment Variable: `ENABLE_STOP_DISTANCE` (Default: `false`)

Use the `STOP_DISTANCE` environment variable to modify the stop distance (in meters). Note that if the stop distance is larger than 4.5 meters for the Clearpath Robotics Jackal and Husky UGVs, or 10.0 meters for the Clearpath Robotics Warthog UGV, the computational load will increase and may cause a decrease in performance in the navigation. | +| **Delay Compensation** | The delay compensation feature is able to compensate for mechanical delay on UGVs where either the accelerator introduces delay into the linear velocity or the steering introduces delay in the angular velocity. This feature is not required for Clearpath Robotics UGVs as negligible delay is present in our system.

Environment Variable: `ENABLE_DELAY_COMPENSATION` (Default: `false`)

Use the `CONTROLLER_DELAY` environment variable to modify the amount of delay to be compensated (in milliseconds). | +| **Docking** | If purchased, autonomous docking will allow the user to autonomously dock/undock their UGV. If not purchased, enabling this environment variable will do nothing.

Environment Variable: `OUTDORRNAV_ENABLE_DOCKING` (Default: `false`).| diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/features/rosbag_recorder.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/rosbag_recorder.mdx new file mode 100644 index 00000000..503d94ae --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/rosbag_recorder.mdx @@ -0,0 +1,34 @@ +--- +title: ROSbag Recorder +sidebar_label: ROSbag Recorder +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +If you need to perform a quick rosbag recording from the UI you can do +so by navigating to the Settings dropdown in the upper left hand menu and +select **Start rosbag recording**. This will record a rosbag of the +following topics (or all the topics in the namespace if followed by a +`/*`): + +- '/rosout(.*)' +- '/twist_marker_server/(.*)' +- '/dock/(.*)' +- '/laser_target_tracker/(.*)' +- '/localization/(.*)' +- '/localization_core/(.*)' +- '/localization_helper/(.*)' +- '/mission/(.*)' +- '/navigation/(.*)' +- '/onboard_systems/(.*)' +- '/platform/(.*)' +- '/swiftnav/(.*)' +- '/sensors/gps(.*)' +- '/sensors/imu(.*)' +- '/target/(.*)' +- '/tf(.*)' + +To stop the recording navigate to the Settings drop down and select +**Stop rosbag recording**. This will save the rosbag with the date and +time as its file name in the `~/clearpath_files/rosbag_data` folder. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/_category_.json new file mode 100644 index 00000000..8b4a486d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/first_time_checklist.mdx new file mode 100644 index 00000000..ed7b5ace --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/first_time_checklist.mdx @@ -0,0 +1,114 @@ +--- +title: First Time Use Checklist +sidebar_label: First Time Use Checklist +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Hardware Setup + +### ☐ Has the Base Station been set up? + +Ensure that the Base Station has been set up approximately 5 meters +away from any buildings and is currently powered on. See +[System Startup](./system_setup) for further +instructions related to setting up the Base Station. + +### ☐ Is the UGV connected to the Base Station? + +Check to see that the UGV can be pinged from the Base Station network. +See [Connecting to Web UI](./system_setup#connecting_to_web_ui) for further +details. + +## Software Setup + +### ☐ Is ROS running on the UGV? + +SSH into the UGV and run `rostopic list` to generate a list of the +rostopics that are currently available. The list is generally fairly +long so if you are looking for any specific topic please refer to +[API Endpoints](../api/api_endpoints). You can also check the +ROS status through the OutdoorNAV UI by referring to the diagnostics section +on the Status page. + +### ☐ Is the OutdoorNAV software running? + +Check to see if the relevant dockers are running (ssh into the UGV and +run `docker ps` which should show at least 5 separate docker containers +running). + +### ☐ Is the computer using the UI connected to the Base Station network? + +This can be confirmed by following the steps found in +[Connecting to Web UI](./system_setup#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware#base-station-survey) for +information on how and when to survey the Base station. + +### ☐ Do you have a strong GPS signal? + +After surveying the Base Station check the upper right hand corner of +the UI to confirm that you have a strong GPS signal (the POS and DIR +icons should be green). If either of these icons are not green refer +to [Checking GPS RTK Fix](../cpr_hardware#base-station-survey) for further +troubleshooting information. + +### ☐ Is the map loading correctly? + +Currently the map requires internet access to load. Refer to +[Loading Map Tiles](./system_setup#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](./system_setup#set-datum) for information on how +to set the Datum variables. + +### ☐ If docking is enabled has the location been set? + +If the Clearpath Robotics autonomous docking package was purchased the +docking location will need to be set. See +[Set Dock Location](./system_setup#set-dock-location) for information on +how to set the docking location. + +### ☐ Is the Navbar status icon functioning? + +To check if the Navbar icon is functioning, trigger the UGV's motion stop +and check to see if it has turned to a red icon. Clicking the icon +will bring up the status information as well as any recent messages +(see below). + +![](/img/outdoornav_images/ugvStatusMessages.png) + +## Using the UI + +The following items are general checks to ensure that the UI is working +properly. + +### ☐ Can the virtual joystick drive the UGV? + +See [Web UI Manual Mode](../web_user_interface/ui_manual_mode) for further details +related to this. + +### ☐ Can you create a new mission? + +Select the mission list and then click on `Add Mission` to create a +new mission. To add new waypoints for the mission refer to +[Mission Creation](../web_user_interface/ui_autonomous_mode#mission-creation). + +### ☐ After creating a new mission, can you execute the mission? + +To execute a mission refer to [Mission Execution](../web_user_interface/ui_autonomous_mode#mission-execution). + +### ☐ Are the cameras (if present) active in the view bar section when running the mission? + +For more information related to camera views see +[Camera Views](../web_user_interface/ui_overview#camera-views). + +### ☐ Can you select a camera and save an image after it loads on the main screen? + +See [Pan-Tilt-Zoom (PTZ) View ](../web_user_interface/ui_overview#ptz-view) for more details related +to saving images. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/system_setup.mdx new file mode 100644 index 00000000..95480fcd --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/system_setup.mdx @@ -0,0 +1,236 @@ +--- +title: System Setup +sidebar_label: System Setup +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +This section outlines how to set up your OutdoorNav system for some +preliminary testing with the OutdoorNav Software on a UGV. For details +on simulation, refer to [Simulation](../simulation). + +These instructions assume that the UGV is already powered ON. + + + +## Connecting to Web UI {#connecting_to_web_ui} + +The web server for the UI typically runs on a computer on the UGV. As +such, it is necessary for the networking setup on the UGV to be complete +and for all related hardware to be powered on. + +:::note + +In the case of Clearpath Robotics OutdoorNav Hardware, ensure that the +Base Station is powered ON. + +::: + +Follow the steps below to connect to the Web UI. + +1. Connect your computer to the same network as the UGV. + + :::note + + For Clearpath Robotics OutdoorNav Hardware, use the Base Station + network. Enter the network list and find the wireless network + related for your UGV. The SSID of the network is located in the + Robosmith manual that was shipped with your UGV. + + ::: + +2. Open an Internet browser (preferably Chrome) on your computer. + +3. Enter the UGV's IP address followed by a forward slash in the + search bar. A bookmark of this page can also be created for future + sessions. + + :::note + + For Clearpath Robotics OutdoorNav Hardware, this will be + **192.168.131.1/** for normal use cases and **192.168.131.5/** for + systems with a separate OutdoorNav computer (including the + OutdoorNav Starter Kit and the OutdoorNav Backpack. + + ::: + +The above steps will open the Web UI, which will allow the user to +operate the UGV in Manual Mode (teleoperation) or in Autonomous Mode +(missions). + +## Loading Map Tiles {#loading_map_tiles} + +The Web UI does not cache map tiles on the browser; therefore, the user +will need to ensure their computer has a connection to an Internet +source to load the map tiles. There are a several options to achieve +this: + +1. If the system includes a Base Station that is connected to the + Internet, you will be able to access the Internet and therefore map + tiles over the base station network without needing any further + updates. +2. Connect your phone via USB to your computer (or tablet) and enable + USB tethering on your phone to share the Internet from your phone. +3. Switch your computer (or tablet) to a network that is connected to + the Internet, zoom in/out of the map to load the tiles then switch + back to the original network. + +## Survey Base Station {#survey_base_station} + +If your system includes a Base Station, it must be surveyed using the +steps below to be able to to operate the UGV autonomously. + +1. Access the Menu → Settings → Map. +2. In the **Survey Base Station** section, click the **Start** button + begin the surveying process. + +During surveying, the Status Indicator will turn orange +and return to its green default state when surveying is +done . +Only then should the UGV be sent on autonomous missions. +The entire surveying will take approximately 5 minutes. A feedback bar +will also be displayed showing the current progress of the surveying. Do +not refresh the page or you will lose the feedback bar. + +:::warning + +For an accurate survey, do NOT move the Base Station during this +process. After the surveying has completed, the Base Station should not +be moved unless required. If you need to move the Base Station or it has +been moved accidentally, the surveying process needs to be run again. + +::: + +## Set Datum + +Before operating the UGV autonomously, the user will need to set the +datum, which is the reference point in the world coordinate frame. + +1. Access the Menu → Settings → Map. + +2. In the **Change Datum** section, enter the latitude and longitude of + a location close to the test site (within 10km). Decimal lat/lon are + expected. Use a minimum of 6 decimal places. + +3. Click **Set Datum** button to set the new datum. + + The user should see the blue dot (datum) and the blue arrow (UGV) + move to the test site. If the GPS status indicators are green, the + UGV should be at its correct position on the map as well as facing + in the correct direction. + +## Set Dock Location + +:::note + +If the Clearpath Robotics autonomous docking package has been purchased, +follow these instructions to set up the dock location. Otherwise, this +section can be skipped. + +::: + +:::warning + +Keep the area around the dock free of objects and people. There is no +obstacle detection between the pre-docking point and the dock; +similarly, there is no obstacle detection during the undocking +operation. + +::: + +
+
+ +
Autocharge Dock
+
+
+ +Before being able to dock the UGV autonomously, set up the dock +location. Follow these steps to position the UGV in its correct position +and orientation. + +1. Power ON the UGV and computer and wait for the system to finish + booting. For example, on the Clearpath Robotics Husky, booting is + complete when the COMM indicator turns green. + +2. Start by manually driving the UGV to the dock target and align it as + straight and centered as possible so that it begins charging. The + Wibotic receiver on the UGV should be centered longitudinally and + laterally with the circle on the Wibotic transmitter (TR-300). + +3. Let the UGV sit in this position for 2 minutes to acquire an RTK GPS + fix. The POS (position) and DIR (heading) GPS status indicators on + the UI should read as follows: . + + **If the GPS status indicators are yellow or red, the selected + location of the dock is NOT appropriate. Please change the dock + location such that the GPS antennas have a clearer visibility.** + +4. On the UI, access the drop down menu on the top-left of the page, + select **Settings** and click the **Add New Dock Location** button. The + dock location will be stored in 5 - 10 seconds as data is collected. + +If the Base Station has been moved (and therefore been resurveyed), or +if the dock has been moved to a new location, the user will need to +reset the location of the dock. This is done in the following manner: + +1. Repeat the previous set of instructions from step 1 to 4. + +2. While in **Edit Mode** select the dock on the UI. A drop down should appear + with the option to reset the dock location. Select that option. + +3. After approximately 5 - 10 seconds the dock location should be updated and the UI will + reflect the change accordingly. + +## Checking GPS RTK Fix {#checking-gpt-rtk-fix} + +Each time the UGV has been powered up (or moved from a GPS-denied +environment to a GPS-available environment), let the UGV sit in this +position for 2 minutes to acquire an RTK GPS fix. The POS (position) and +DIR (heading) GPS status indicators on the UI should be green: . + +**If the GPS status indicators are yellow or red, the selected location +does not have an adequate GPS signal. Move the UGV such that the GPS +antennas have a clearer visibility.** + +If using Switft Navigation Duros and/or a Clearpath Robotics Base +Station, each of these will have a solid blue LED on all of them when +the RTK GPS fix is acquired. + +## Recording a Rosbag + +See the [ROSbag Recorder](../features/rosbag_recorder) section for details on recording ROS data either. + +## Subsequent Sections + +The following sections of this manual will outline the instructions for +different tasks that can be accomplished while operating the UGV. + +1. **Web User Interface:** + - Overview of the Web UI components as well as the available views + and icons/buttons associated with them. + + - Overview of the buttons required to operate the UGV in Manual + Mode (teleoperation). + + - Instructions to send the UGV on autonomous navigation missions, + including: + + > - Adding Waypoints to the map + > - Creating missions + > - Viewing and updating missions + > - Adding task to missions, such as **Move PTZ** camera, + > **Save Image**, **Dock/Undock** UGV, **Wait**, etc.... + > - Start/Stop/Pause missions + + - Description of the docking procedures allowing the user to dock + and undock the UGV autonomously. Recovery instructions are also + described. +2. **Application Programming Interface:** Details on how to control the + UGV programmatically. +3. **OutdoorNav Features** Details on the features available as part of the + navigation software. +4. **Simulation:** Details on how to simulate autonomous operation of + the UGV. +5. **FAQs:** A list of frequently asked questions. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/terminal_interface.mdx new file mode 100644 index 00000000..43e9dedc --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/terminal_interface.mdx @@ -0,0 +1,141 @@ +--- +title: Terminal Interface +sidebar_label: Terminal Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Command Line Operation + +By default the OutdoorNav Software, including the Navigation component, +begins automatically when the system is powered on. This section +outlines the commands that can be used by developers who are debugging +the system or who want more precise control for managing the Navigation +component. + +### Connecting to the OutdoorNav Computer {#connecting-to-outdoornav-computer} + +To connect to your UGV, consult its corresponding user manual. + +If you are using a Clearpath Robotics UGV with a seperate OutdoorNav computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. If you have a wired connection to the Clearpath Robotics UGV, +use the following command. If using wifi, you can replace the IP address +with the wifi-assigned IP address or the hostname of the UGV. + +``` bash +ssh administrator@192.168.131.1 +``` + +Then, connect to the OutdoorNav Computer: + +``` bash +ssh administrator@192.168.131.5 +``` + +### Starting the Navigation Software {#starting-outdoornav} + +Begin by connecting to the OutdoorNav Computer as outlined above. + +On UGV startup, all the sensors, the user interface, as well as the +Navigation software are set to start automatically through a Docker +container. You can check the Docker container's status by running +`docker ps` and checking for: + +- onav-web (Docker image containing the web interface) +- onav-web-ros (Docker image containing the ROS web bridge nodes) +- onav-sensors (Docker image that launches the ROS sensor drivers) +- onav-power (Docker image that launches the ROS nodes related to + the power system of the UGV) +- onav-autonomy (Docker image that launches the ROS nodes related + to the autonomy) + +The docker compose file located at `~/cpr_outdoornav_launch/docker-compose.yml` +provides the description for each the docker images that are being generated +on startup. In here, you can find that there are profiles set up as part of the +docker compose structure. They are: + +- ui: starts the onav-web and onav-web-ros containers +- sensors: starts the onav-sensors container +- power: starts the onav-power container +- autonomy: starts the onav-autonomy container +- outdoornav: starts all of the containers +- teleop: start only the ui and sensor related containers (no autonomy) + +If the Docker containers are not running, they can all be started with: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav up -d +``` + +### Stopping/Restarting all of OutdoorNav + +Each individual profile can also be brought down. For example to use the UGV without +the OutdoorNav software. The following command brings down OutdoorNav and is persistent +accross reboots/power cylces. + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav down +``` + +If the OutdoorNav software has been brought down, it can be restarted by running: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav up -d +``` + +### Stopping/Restarting the Autonomy + +To use the UGV without the autonomy core of OutdoorNav, use these +commands to stop the nodes and prevent them from automatic startup: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile autonomy down +``` + +The autonomy core can be restarted by running: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile autonomy up -d +``` + +### Stopping/Restarting the Sensors + +To use the UGV without the sensors, use these commands to disable the +nodes and prevent them from automatic startup: + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile sensors down +``` + +::: note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNv software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars) + +::: + +### Accessing the Navigation Software Logs + +To check the logs of the Navigation software: + +``` bash +cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml +docker compose logs -f +``` + +Optionally, specify the specific container you would like to view logs for: + +``` bash +cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml +docker compose logs -f onav-autonomy +``` \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/tf_validation.mdx new file mode 100644 index 00000000..5ba3bab4 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/getting_started/tf_validation.mdx @@ -0,0 +1,80 @@ +--- +title: TF Validation +sidebar_label: TF Validation +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Sensor transform (TF) validation should only be required if the performance +is noticeably poor, such as when the UGV drifts off of the planned path or +oscillations occur around the path). + +::: + +The coordinate transformation of the two GPS antennas, the IMU, the 2D +and 3D Lidars to the base_link of the UGV should have already been set +prior to receiving the UGV. However, ensure that they are set correctly. + +The ROS coordinate frame base_link, shown in the figure below, is +located at the center of the bottom plate of the UGV. The environment +variables below should be taken with respect to this coordinate frame. +The X axis is in red (and pointing towards the front of the UGV), Y in +green (pointing towards the left of the UGV) and Z in blue (pointing +towards the sky). + +You can check the current value of the environment variables by running +the following on the robot (host) computer (and setting +to the names listed in the table below). + +``` bash +printenv | grep +``` + +The environment variables for the position and orientation of each +sensor are provided in the table below. + +_OutdoorNav sensor position and orientation environment variables_ + +| Environment Variable | Function | +|----------------------|---------------------------------------| +| POSITION_GPS_XYZ | [X,Y,Z] position, in meters, of the position GNSS antenna with respect to the base_link coordinate frame. | +| POSITION_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the position GNSS antenna with respect to the base_link coordinate frame. | +| HEADING_GPS_XYZ | [X,Y,Z] position, in meters, of the heading GNSS antenna with respect to the base_link coordinate frame. | +| HEADING_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the heading GNSS antenna with respect to the base_link coordinate frame. | +| MICROSTRAIN_XYZ | [X,Y,Z] position, in meters, of the IMU with respect to the base_link coordinate frame. | +| MICROSTRAIN_RPY | [Roll,Pitch,Yaw], in radians, of the IMU with respect to the base_link coordinate frame. | +| VLP_XYZ | [X,Y,Z] position, in meters, of the 3D Lidar with respect to the base_link coordinate frame. | +| VLP_RPY | [Roll,Pitch,Yaw], in radians, of the 3D Lidar with respect to the base_link coordinate frame. | +| LMS1XX_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| LMS1XX_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | +| HOKUYO_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| HOKUYO_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | +| D435_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| D435_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | + +There may also be 2 of each of these detection sensors. The corresponding environment +variable is prefixed with `REAR_`. + +:::note + +When the printed Y axis on the IMU is pointing towards the front of the +robot (i.e., aligned to X axis of base_link), MICROSTRAIN_RPY = [0, 0, 0]. + +::: + +:::warning + +If you decide to move any of these sensors, you must modify these +variables accordingly in the `/opt/onav/outdoornav_host_setup.sh` file (on the host). + +
+
+ +
base_link coordinate frame
+
+
+ +::: diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/index.mdx new file mode 100644 index 00000000..09a63a7f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/index.mdx @@ -0,0 +1,18 @@ +--- +title: OutdoorNav User Manual +sidebar_label: OutdoorNav User Manual +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +
+
+ +
+
+ +OutdoorNav is an outdoor autonomy software platform designed for vehicle developers, +OEMs and robotics researchers. Compatible with Clearpath outdoor mobile platforms +and third-party vehicles, OutdoorNav provides reliable, industry-leading GPS-based +navigation for faster, more efficient autonomous vehicle development. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/_category_.json new file mode 100644 index 00000000..e9e0ff1d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Appendix A: UGV Integration Requirements", + "position": 12 +} \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/_category_.json new file mode 100644 index 00000000..75ebaf1b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Hardware Kit Installation", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx new file mode 100644 index 00000000..4231afc9 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx @@ -0,0 +1,19 @@ +--- +title: "Custom Kit Hardware Checklist" +sidebar_label: "Custom Kit Hardware Checklist" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +To integrate the custom hardware kit from Clearpath Robotics onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav +software. + +| | Requirement | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | All sensors have been mounted to the UGV with fixed brackets. Ie. the sensor should not move or rotate relative to the UGVs `base_link`. | +| | Spacing between the GNSS antennas is greater than 0.7 m. | +| | SwitfNav Piksi/Duro GNSS units, 2D/3D LiDAR units (Velodyne, Sick, Hokuyo) and Axis cameras have been configured to communicate over ethernet (IP). IP sensors are assigned within the following ranges on the `192.168.131.XXX` subnet and recorded in the table below.
**Cameras**: 192.168.131.10-19, **LiDARs**: 192.168.131.20-29, **GNSS**: 192.168.131.30-39, **Wireless**: 192.168.131.50-59

SensorSensor IPSensorSensor IP
| +| | For each sensor that is to be integrated, measure the XYZ position, in metres, and RPY (roll/pitch/yaw) orientation, in radians, relative to the robot's [base_link frame](./#base-link-frame). Record the XYZ and RPY values in the table below.

SensorXYZRPY
| + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx new file mode 100644 index 00000000..5b803fd0 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx @@ -0,0 +1,44 @@ +--- +title: "Hardware Kit Installation Requirements" +sidebar_label: "Hardware Kit Installation Requirements" +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Several hardware configurations are compatible with OutdoorNav Autonomy Software. +Select the checklist below that corresponds to your hardware kit. + +- [OutdoorNav Standard Kit Hardware Checklist](./standard_kit_hardware_checklist) +- [OutdoorNav Starter Kit Hardware Checklist](./starter_kit_hardware_checklist) +- [OutdoorNav Custom Kit Hardware Checklist](./custom_kit_hardware_checklist) + +In addition, if the OutdoorNav software is not running on the UGV computer itself, which is the case with the Starter Kit and some custom integrations, ensure that the UGV computer is configured correctly by reviewing the following checklist. + +- [UGV Computer Checklist](../platform_computer_checklist) + +## Notes on Measuring Frame Relationships + +### `base_link` Frame {#base-link-frame} + +For mobile robots, `base_link` should be rigidly attached to the mobile UGV. +It can be attached at any position of the UGV to provide a point of reference. +We also expect the orientation of `base_link` to be in the NWU convention. +ROS standards for `base_link` can be found in [REP-103](https://www.ros.org/reps/rep-0103.html#axis-orientation) and [REP-105](https://www.ros.org/reps/rep-0105.html#base-link). + +### Starter Kit Frame {#starter-kit-frame} + +The starter kit frame (`starter_kit_link`) is located at the center of the bottom plate of the enclosure. +Its orientation is also in the NWU convention with the X-axis of the frame pointing out of the front RealSense camera and the Y-axis coming out of the side of the enclosure **without** the power and Ethernet breakouts. + +### Sensor Frame + +The sensors frame for each sensor will vary. Please consult the documentation for the specific sensor. + +### Measuring Relative Pose + +Consider frame A (eg. `starter_kit_link`) and frame B (eg. `base_link`), rigidly attached to the UGV. +The relationship of A relative to B consists of two parts, the relative position and relative orientation. +The position of A relative to B can be obtained by measuring the distance (in X, Y, Z axes) from frame B to frame A, and providing that value in frame B's coordinate frame. +The orientation of A relative to B is obtained by rotating the axes of frame B until they line up with frame A, noting that results in each axis are the rotation angles of the orientation. +A trick for the orientation's sign is to remember that if you rotate the X-axis towards the Y-axis or Z-axis the rotation will be positive and that if you rotate away from the Y-axis or X-axis, it results in negative rotations. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist.mdx new file mode 100644 index 00000000..d179bbb0 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist.mdx @@ -0,0 +1,24 @@ +--- +title: "Standard Kit Hardware Checklist" +sidebar_label: "Standard Kit Hardware Checklist" +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav Standard Kit from Clearpath Robotics contains: + +- SwiftNav Piksi/Duro GNSS (x2) +- Microstrain GX5-25 AHRS +- Velodyne Puck (VLP-16) 3D LiDAR + +To integrate this kit onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav software. + +| | Requirement | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | All sensors have been mounted to the UGV with fixed brackets. Ie. the sensor should not move or rotate relative to the UGVs base_link. | +| | Spacing between the GNSS antennas is greater than 0.7 m. | +| | SwitfNav Piksi/Duro GNSS units and Velodyne LiDAR unit have been configured to communicate over ethernet (IP). IP sensors are assigned within the following ranges on the `192.168.131.XXX` subnet and recorded in the table below.
**LiDARs**: 192.168.131.20-29, **GNSS**: 192.168.131.30-39, **Microhard**: 192.168.131.50-59

SensorSensor IP
SwiftNav Piksi/Duro (Reference)
SwiftNav Piksi/Duro (Attitude)
Velodyne VLP-16
Microhard Wireless (Base Station)
Microhard Wireless (UGV)
| +| | For each sensor that is to be integrated, measure the XYZ position, in metres, and RPY (roll/pitch/yaw) orientation, in radians, relative to the robot's [base_link frame](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements#base-link-frame). Record the XYZ and RPY values in the table below.

SensorXYZRPY
GNSS Antenna (Reference)0.00.00.0
GNSS Antenna (Attitude)0.00.00.0
Velodyne VLP-16
Microstrain GX5­-25 AHRS
| + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx new file mode 100644 index 00000000..6508097f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx @@ -0,0 +1,51 @@ +--- +title: "Starter Kit Hardware Checklist" +sidebar_label: "Starter Kit Hardware Checklist" +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav Starter Kit from Clearpath Robotics contains: + +- Ublox F9P GNSS +- Phidget Spatial 3/3/3 IMU +- RealSense D435f (x2) Depth Camera + +To integrate this kit onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav software. +Refer to the [OutdoorNav Starter Kit](/docs/robots/accessories/add-ons/outdoornav_starter_kit) for additional +integration details. + +
+
+ +
Starter Kit Integration
+
+
+ +To integrate this kit onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav software. + +| | Requirement | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | The Starter Kit should be rigidly fixed to the UGV. Ie. It should not move or rotate relative to the UGVs base_link. | +| | Once mounted, the XYZ position of the [Starter Kit frame](./#starter-kit-frame) relative to the [base_link frame](./#base-link-frame) has been noted here:
X: , Y: , Z: | +| | The Starter Kit is connected to the base robot computer via a gigabit ethernet cable (Cat6(a) minimum). | +| | The Starter Kit is power by an **18 - 75 V** source supplied by the UGV. | + +Should any of the external sensors positions need to be moved, the following constraints should be followed: + +- The GNSS antenna is to be placed upright, on an unobstructed part of the UGV with clear visibility. +- The RealSense D435f cameras should be placed with a minimal amount of their field of view (FoV) obstructed by the UGV body. + + The new XYZ position of the GNSS antenna and/or the Realsense D435f cameras relative to the [Starter Kit Frame](./#starter-kit-frame) are noted below: + + | Sensor | X | Y | Z | R | P | Y | + | ----------------------- | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | + | **GNSS Antenna** | | | | **0.0** | **0.0** | **0.0** | + | **RealSense D435f (front)** | | | | | | | + | **RealSense D435f (rear)** | | | | | | | + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/integration_overview.mdx new file mode 100644 index 00000000..00cf8a07 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/integration_overview.mdx @@ -0,0 +1,34 @@ +--- +title: "Integration Overview" +sidebar_label: "Integration Overview" +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The scope of work to transform a non-autonomous UGV into an autonomous +one will vary depending on the exact hardware capabilities and software +interfaces of the UGV. Development work will be required by Clearpath +Robotics, the end user, or a third party developer to bring the UGV into +compliance with the requirements listed in the table below. This may +involve implementing encoders and controllers to provide velocity +control of the UGV and implementing a CAN bus to ROS interface with +kinematic control. The table below provides a general outline of the +requirements; the detailed requirements are covered in the following +sections. + +_Navigation hardware and software general integration scope of work_ + +| \# | Task | Note | +|-----|----------------------------------|---------------------------------| +| 1 | **Convert UGV to drive by wire** | If required; can be a significant electromechanical integration | +| 1.1 | Implement actuated steering and throttle control if necessary | | +| 1.2 | Implement the encoder and controller hardware to provide wheel velocity control and odometry feedback | May require electronic power steering position feedback and controller | +| 2 | **Create a ROS interface** | | +| 2.1 | Commission an OutdoorNav computer running Ubuntu 20.04 and ROS Noetic | | +| 2.2 | Create a ROS interface to the UGV Often interfacing via CAN bus motor controllers and UGV controller | | +| 2.3 | Create a ROS driver including UGV kinematics with ROS-control | Accepts velocity input, commands motor controllers, provides other status feedback | +| 3 | **Install and configure OutdoorNav Hardware and Software** | | +| 3.1 | Install OutdoorNav computer and sensors on the UGV | Provide mechanical mounting, power and ethernet communication to UGV computer | +| 3.2 | Install, update and configure OutdoorNav Software on computer | Configure for sensor mounting locations, UGV kinematics and data topics. Can be done remotely with assistance from Clearpath Robotics Engineering. Approximately 1-2 days. | +| 3.3 | Tune the path planning and following controllers for new UGV | Can be done at a Clearpath Robotics facility. Can often be done at end user facility via remote login from Clearpath Robotics Engineering. Approximately 2-5 days. | diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/interface_control_requirements.mdx new file mode 100644 index 00000000..e22530ca --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/interface_control_requirements.mdx @@ -0,0 +1,119 @@ +--- +title: "ROS Interface Control Requirements" +sidebar_label: "ROS Interface Control Requirements" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## ROS Interface Control Checklist + +Prior to the installation and tuning of Clearpath Robotics (CPR) +OutdoorNav software on your platform (robot computer), CPR requires that the platform's +ROS interface satisfies the conditions listed below. Ensure that all of the requirements +are satisfied for a smooth installation and tuning process. + +![](/img/outdoornav_images/onav_interface_control.png) + +| | Requirement | +|------|------------------------------------------------------------------| +| | The platform computer is on the 192.168.131.xxx subnet (ideally in the range 1-4). | +| | The platform computer has an installation of [ROS 1 Noetic](http://wiki.ros.org/noetic/Installation). | +| | A URDF is supplied to CPR by the customer, in which the `base_link` coordinate frame is defined according to the [REP-105 base-link](https://www.ros.org/reps/rep-0105.html#base-link) ROS standard. | +| | The platform outputs [tf2_msgs/TFMessage](http://docs.ros.org/en/jade/api/tf2_msgs/html/msg/TFMessage.html) messages on the ROS standard `/tf` topic, at a minimum rate of **30 Hz**. | +| | The platform outputs a latched [tf2_msgs/TFMessage](http://docs.ros.org/en/jade/api/tf2_msgs/html/msg/TFMessage.html) message on the ROS standard `/tf_static` topic. This should include any fixed frames of ROS enabled devices/sensors that are available on your platform. | +| | The platform computer has a velocity controller that accepts, as input, [geometry_msgs/Twist](http://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/Twist.html) messages on the ROS standard `/cmd_vel` topic, at a minimum rate of **10 Hz**. | +| | The platform computer has a velocity controller that tracks the input velocity and outputs the resulting platform velocity on the `/platform/cmd_vel` topic. | +| | The platform outputs [nav_msgs/Odometry](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html) messages on the `/platform/odom` topic, at a minimum rate of **10 Hz**. | +| | The `/platform/odom` topic publishes its data with the header.frame_id = `odom` and the child_frame_id = `base_link`, as per the [REP-105 odom](https://www.ros.org/reps/rep-0105.html#odom) ROS standard. **IMPORTANT**: The platform should however not broadcast the `odom` --> `base_link` transformation since the OutdoorNav software will do so. | +| | If available, the platform odometry output has less than ±5% linear position error. | +| | If available, the platform odometry output has less than ±5% orientation error. | +| | The platform outputs [std_msgs/Bool](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/Bool.html) messages on the `/platform/emergency_stop` topic, at a minimum rate of **5 Hz**, indicating whether or not the platform is in a stopped state. | +| | Perform the validation tests described in [Interface Control Validation Test](#interface-control-validation) section and [record a rosbag](http://wiki.ros.org/rosbag/Commandline#rosbag_record) of all of your topics. The linear and angular velocities of the three trial runs recorded should be noted here:

Trial #1: Linear x: , Angular z:
Trial #2: Linear x: , Angular z:
Trial #3: Linear x: , Angular z:
| + +:::note + +Consult the [Platform API](../api/api_endpoints/platform_api#topics-published-by-platform) for +detailed information on the published/subscribed platform topics. + +::: + +If the platform is an Ackermann (or double Ackermann) drive vehicle: + +| | Requirement | +|------|------------------------------------------------------------------| +| | A conversion from [geometry_msgs/Twist](http://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/Twist.html) messages to Ackermann inputs is provided. | + +:::note + +Ackermann drive platforms require both steering and throttle inputs to +drive the platform. It is required that our OutdoorNav output `/cmd_vel` +be converted into a message suitable to your platform. An example of an +Ackermann message type can be found +[here](http://wiki.ros.org/teb_local_planner/Tutorials/Planning%20for%20car-like%20robots). +This may satisfy your particular platform, and is only a starting point +on how to do this conversion. + +::: + +If the platform computer is running a version of ROS 2: + +| | Requirement | +|------|------------------------------------------------------------------| +| | The platform computer has a [ROS 2 to ROS 1 bridge](https://github.com/ros2/ros1_bridge) is installed to enable the exchange of messages between the two ROS versions. | + +Signature: Date: + +## Interface Control Validation Test {#interface-control-validation} + +The following test is designed to validate the platforms velocity +controller. It will be required that you command the robot to drive in +three circles, of varying radii, by applying the following command to +the platform. + +``` bash +rostopic pub -r 10 /cmd_vel geometry_msgs/Twist "linear: +x: ___ +y: 0.0 +z: 0.0 +angular: +x: 0.0 +y: 0.0 +z: ___" +``` + +The three trials that we request will vary between platforms depending +on the its maximum linear $(v_{max})$ and angular velocities +$(\omega_{max})$, minimum linear $(v_{min})$ and angular velocities +$(\omega_{min})$, as well as limitations due to the minimum allowable +turning radius $(r_{min})$. Of these three trials, we would like to see +data within three linear velocity bands, as seen in the table below, +resulting in three different turning radii. For the purpose of these +tests, the following formula can be used when determining the required +linear and angular velocities to apply: $r = v/\omega$. + +| Trial \# | Linear X Bands \[m/s\] | Example Linear X Band \[m/s\] | +| ---------|--------------------------------------------|-------------------------------------| +| 1 | $v_{min} \cdot [1.0, 1.5]$ | $[0.5, 0.75]$ | +| 2 | $((v_{max} - v_{min})/2) \cdot [0.9, 1.1]$ | $[2.025, 2.475]$ | +| 3 | $v_{max} \cdot [0.9, 1.0]$ | $[4.5, 5.0]$ | + +As an example, a platform with specs $v \in [0.5, 5.0]$, $r_{min} = 3$ +would have linear x velocity bands as listed in the table above. The +trials could then be as outlined in the table below. + +| Trial \# | Linear X \[m/s\] | Angular Z \[rad/s\] |Turn Radius \[m\] | +|-----------|--------------------|---------------------|------------------| +| 1 | 0.75 | 0.25 | 3 | +| 2 | 2.25 | 0.5 | 4.5 | +| 3 | 4.5 | 0.75 | 6 | + +Finally, the test data in the collected ROSbag should include the +following: + +1. `/tf` and `/tf_static` +2. `/platform/cmd_vel` +3. `/platform/odom` +4. `/cmd_vel` +5. `/platform/emergency_stop` (if available) +6. raw NavSatFix data from a GPS unit (if possible). diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/platform_computer_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/platform_computer_checklist.mdx new file mode 100644 index 00000000..343a813d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/platform_computer_checklist.mdx @@ -0,0 +1,24 @@ +--- +title: "Platform Computer Checklist" +sidebar_label: "Platform Computer Checklist" +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- + +The following instructions are only required if intending to install the OutdoorNav software on a secondary or Starter Kit computer, henceforth named the **hardware kit**. If installed on the platform computer, please proceed to the [Interface Control Checklist](./interface_control_requirements). + +In addition to the electromechanical installation of the hardware kit, software updates are required to the platform computer, as outlined below. + +| | Requirement | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | Connect an ethernet cable between the platform computer and the hardware kit, either directly between them or via an ethernet switch. Make note of which port was used on the platform computer so that it's IP address can be configured in the next step. | +| | Ensure network connectivity between the platform computer and the hardware kit on the `192.168.131.XXX` subnet. Configure the platform computer to have a static IP assigned on the interface that is used to connect to the hardware kit. Ideally this IP address will be `192.168.131.1`, but it can be in the `192.168.131.1-4` range. In some cases, this may require the creation of a virtual interface. Record the platform computer IP address.
Platform Computer IP Address: | +| | On the platform computer, add the following line to the `/etc/hosts` file:
`192.168.131.5 cpr--onav>` | +| | On the platform computer, run `ping cpr--onav>` and confirm it is successful. | +| | On the platform computer, [Install ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu) if not already installed (the `ros-noetic-ros-base` version is sufficient). | +| | On the platform computer, configure ROS Noetic so it is running with the `ROS_MASTER_URI` set to the base platform computer. Note that `localhost:11311` is acceptable only if the primary subnet on the platform computer is the `192.168.131.XXX` subnet. | +| | Restart both the platform computer and the hardware kit, then run `rostopic list` on the platform computer and confirm that it includes the OutdoorNav topics. | +| | On the platform computer, complete all checks in [Interface Control Checklist](./interface_control_requirements) and confirm that all listed ROS topics are publishing as expected. | + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/software_integration_instructions.mdx new file mode 100644 index 00000000..29431e38 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/software_integration_instructions.mdx @@ -0,0 +1,145 @@ +--- +title: "Software Integration Instructions" +sidebar_label: "Software Integration Instructions" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import versions from "@site/static/versions.js" + +Prior to installing the OutdoorNav software, ensure that you have completed the relevant [Hardware Kit Checklist](./hardware_integration_requirements). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](./interface_control_requirements) + +All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. + +### Clone OutdoorNav Repository {#clone-install-repo} + +The following repository is required to run the instructions in the subsequent sections. + + +{` +cd ~/ +git clone -b ${versions.outdoornav} https://gitlab.clearpathrobotics.com/cpr-outdoornav/cpr_outdoornav_launch.git +`} + + +For remote installations, please contact Clearpath Robotics customer support in order to obtain the relevant information required to proceed. + +### Install Docker {#install-docker} + +``` bash +cd ~/cpr_outdoornav_launch/scripts/ +./install_docker.sh +``` + +### Configure OutdoorNav Sensors {#configure-outdoornav-sensors} + +Prior to configuring the sensors, ensure that you have measured the position (XYZ) and orientation (RPY) of each of your sensors with respect to the `base_link`. See your results from the [Integration Requirements](./hardware_integration_requirements). + +``` bash +cd ~/cpr_outdoornav_launch/scripts/ +./configure_outdoornav.sh +``` + +### Finalize Setup {#final-setup} + +The script in the sections below will reboot the computer it is run on. + +##### UGV Computer + +For installations of the OutdoorNav software on the UGV computer (not a secondary or Starter Kit computer), run the following: + +``` bash +cd ~/cpr_outdoornav_launch/scripts +sudo ./setup_computers.sh +``` +##### Secondary or Starter Kit Computer + +Prior to running the script on the secondary or Starter Kit computer, ensure that you have the user and IP of the UGV computer that the secondary/starter kit computer is connected to. Run the following: + +``` bash +cd ~/cpr_outdoornav_launch/scripts +sudo ./setup_computers.sh -b +``` + +### Install OutdoorNav Software {#install-outdoornav} + +``` bash +cd ~/cpr_outdoornav_launch/scripts/ +docker compose --profile outdoornav pull +``` + +:::note +If you are installing the OutdoorNav software on a secondary or Starter Kit computer, you must also complete the [UGV Computer Checklist](./platform_computer_checklist) +::: + +### Configure UGV Footprint {#configure-platform-footprint} + +If the UGV has sensors and/or parts that protrude outside of the UGV body, then a few environment variables will need to be modified to adjust the footprint of the robot. Things that could be extending past the footprint could include but are not limited to: + +- GPS antennae, +- Charging receivers, +- Arms, +- etc... + +Change the environment variables from the Table below, in the following file: + +``` +cd ~/cpr_outdoornav_launch +nano outdoornav_tuning.env +``` + +| Environment Variable | Description | Default | +|-----------------------------|----------------------------------------|---------| +| **FOOTPRINT_OFFSET_POS_X** | Distance from base_link to the furthest edge of any part/sensor at the front of the robot | 0.5 | +| **FOOTPRINT_OFFSET_NEG_X** | Distance from base_link to the furthest edge of any part/sensor at the rear of the robot | -0.5 | +| **FOOTPRINT_OFFSET_POS_Y** | Distance from base_link to the furthest edge of any part/sensor at the left of the robot | 0.35 | +| **FOOTPRINT_OFFSET_NEG_Y** | Distance from base_link to the furthest edge of any part/sensor at the right of the robot | -0.35 | + + + +### Start OutdoorNav + +``` bash +cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml +docker compose --profile outdoornav up -d --build +``` + +### Test OutdoorNav Installation + +1. Ping all of the network sensors to ensure proper communication with the UGV or secondary computer. + +2. Check the following topics and make sure there is data being published to them: + +``` bash +rostopic echo -n 1 /platform/odom +rostopic echo -n 1 /platform/cmd_vel + +# IMU 1 (if included) +rostopic echo -n 1 /sensors/imu_0/data + +rostopic echo -n 1 /localization/odom + +# Velodyne/Ouster/LMS1XX/Hokuyo/OutdoorScan (if included) +rostopic echo /sensors/lidar_/pointcloud +rostopic echo /sensors/lidar_/scan + +# Realsense D435 Front (if included) +rostopic echo -n 1 /sensors/stereo_0/pointcloud +rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw + +# Realsense D435 Rear (if included) +rostopic echo -n 1 /sensors/stereo_1/pointcloud +rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw +``` + + will be the number of the sensor as it was loaded into the software. Eg. If you have a VLP and an LMS1XX, then the VLP will be lidar_0, and the LMS1XX will be lidar_1. If we only have an LMS1XX, then it would be lidar_0. Ie. the 3D lidars have a higher "priority" and therefore will be loaded first. + +:::note + +The 2D LiDARs (LMS1XX, Hokuyo) will not have a pointcloud topic. + +::: + +Once installation is complete, you can proceed to [Getting Started](../getting_started/system_setup) to start using the software. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/_category_.json new file mode 100644 index 00000000..663e4088 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_hardware_requirements.mdx new file mode 100644 index 00000000..02c52263 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_hardware_requirements.mdx @@ -0,0 +1,44 @@ +--- +title: Hardware Requirements +sidebar_label: Hardware Requirements +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +OutdoorNav Software works with compatible UGVs, either from Clearpath +Robotics or third parties. High level requirements for compatible UGVs +are outlined below. Detailed qualification requirements are outlined in +[UGV Integration Requirements](../integration_requirements/integration_overview). + +## Requirements + +OutdoorNav software does not communicate directly with the UGV motors. +Rather, it publishes target linear and angular velocities packaged in +the [ROS Twist message](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) +format and relies on the low level velocity controller of the vehicle to +translate these velocities into correct motor control commands. +Therefore, OutdoorNav Software requires that the UGV must accept the +control commands sent in the [ROS Twist message](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) +format. More detailed requirements are outlined in the following table. + +| # | Requirement | Notes | +| - | --------------------------------- | ----------------------------------- | +| 1 | The UGV must be a differential drive or Ackermann drive configuration | Ackerman drive is currently available as a custom implementation; standard in 2023 | +| 2 | The UGV must have velocity control of the wheels and provide kinematic control of the platform | | +| 3 | The UGV shall provide odometry feedback of the wheel direction and velocities and/or steering position | Recommended encoder resolution of 500 ticks per revolution or greater | +| 4 | The UGV should have an emergency stop system with status feedback | | +| 5 | The UGV must accept ROS 1 Twist Commands on the `/cmd_vel` topic | See [API Endpoints](../api/api_endpoints); ROS 2 interface available in future release | +| 6 | The UGV must provide odometry and status feedback through ROS topics | See [API Endpoints](../api/api_endpoints) | + +## Typical Hardware + +While a variety of different sensors and equipment can be used with +OutdoorNav Software, the following are used most commonly: + +- Clearpath Robotics UGV: Jackal, Husky or Warthog +- GPS System: Dual DURO RTK system or NovAtel Terrastar +- IMU: Microstrain 3DM-GX5-25 +- 3D Laser Sensor: Velodyne VLP-16 +- Tablet Computer: Getac F110 +- Clearpath Long Range Network Station with RTK corrections ("Base Station") diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_introduction.mdx new file mode 100644 index 00000000..83bfa1d6 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_introduction.mdx @@ -0,0 +1,93 @@ +--- +title: Introduction +sidebar_label: Introduction +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Summary + +OutdoorNav Software is a software package developed by Clearpath +Robotics for autonomous and manual navigation of Unmanned Ground +Vehicles (UGVs) in outdoor environments. + +
+
+ +
Web UI Mission Planning View
+
+
+ +
+
+ +
Web UI Front Camera View
+
+
+ +## Compatible Platforms + +While it has been optimized for use with OutdoorNav Hardware from +Clearpath Robotics +([Husky](https://clearpathrobotics.com/husky-unmanned-ground-vehicle-robot/), +[Jackal](https://clearpathrobotics.com/jackal-small-unmanned-ground-vehicle/), +and +[Warthog](https://clearpathrobotics.com/warthog-unmanned-ground-vehicle-robot/)), +it has been designed so that it can be added easily to third-party UGVs. + +
+
+ +
Clearpath Robotics Warthog UGV with navigation equipment and operator control unit
+
+
+ +## Key Features + +Key features of OutdoorNav Software include: + +- Mission Planning and Autonomous Navigation + + - Robust GPS-based localization with sensor fusion of IMU, LiDAR + and platform odometry + - Autonomous path following via waypoints + - Obstacle Detection and Avoidance: Stop and wait or + autonomously plan a collision-free path around obstacles + without the need to stop + +- Teleoperation + + - Operate the robot remotely using an on-screen or physical + joystick + - Visualize what the robot sees by displaying its network + cameras and LiDAR data + +- Web User Interface (Web UI) + + - Build missions containing sets of paths, with optional task + execution on each path; tasks can be standard tasks (eg. save + camera image) or user provided functions + - View the robot's live position and attitude on the map + - Display robot data such as velocity, signal strength, status + of the motion stop, status of navigation system, and battery charge + - Save and export Missions + +- Application Programming Interface (API) + + - Build your own application and UI by accessing the navigation + API to control the UGV through software or implement fleet + management by accessing the mission API + +- Simulation + + - Begin development of your application prior to purchasing + licenses or commissioning hardware with OutdoorNav software and + the ROS Gazebo simulator + +- Third Party Integration + + - The Web UI and API can be accessed through a network connection; + cloud-based services are available from third parties to + facilitate remote connections and networking to robot hardware + such as Formant.io and Freedom Robotics diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_operating_conditions.mdx new file mode 100644 index 00000000..c02228aa --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_operating_conditions.mdx @@ -0,0 +1,177 @@ +--- +title: Operating Conditions +sidebar_label: Operating Conditions +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +OutdoorNav Software is designed and tested for use in rugged outdoor +environments. + +## Operating Conditions + +### Terrain + +OutdoorNav Software is compatible with terrains in which the UGV can be +driven manually without excessive slipping. The performance limits will +be a function of the base UGV traction. + +Using Clearpath Robotics Husky, Jackal, and Warthog as a the base UGV, +OutdoorNav Software is suitable for use in the following terrains: + +- asphalt +- concrete +- grass +- snow + +:::note + +Grass should not exceed 30 cm in height if collision avoidance is +enabled. + +::: + +:::note + +Winter/studded tires may be required for proper traction on snow. + +::: + +OutdoorNav Software is currently **not** suitable in the following +terrains: + +- ice +- loose gravel + +:::note + +Support for loose gravel environments is currently being tested and is +expected to be available in late 2023. + +::: + +The terrain capabilities of third-party UGVs will be dependent on a +variety of factors including the vehicle mass, the tire treading, and +motor power. + +### Environment + +OutdoorNav Software is suitable for use in the following environmental +conditions: + +- light rainfall (drizzle) +- light snowfall (powdery snow) + +:::note + +If erratic behavior, such as frequent replanning, is perceived in these +light precipitation conditions, disabling the "continuous planning" +feature may help. + +::: + +OutdoorNav Software is **not** suitable for use in the following +environmental conditions: + +- heavy rainfall +- heavy snowfall + +:::note + +If navigation is required in heavy rain or snow, disabling the collision +avoidance feature will allow the UGV to navigate properly. This should +be done with caution. + +![](/img/outdoornav_images/gps_danger.png) + +::: + +## Performance + +The performance of the system is highly dependent on both the base UGV, +the sensors, the system integration details, and the environment. The +following table provides typical performance metrics for Clearpath +Robotics Jackal and Husky UGVs. + +_System Performance for Husky/Jackal with Typical Sensors_ + +| | Starter Sensor Kit | Standard Sensor Kit (No RTK) | Standard Sensor Kit (RTK) | +|----------------------------------------|-----------------------------------|----------------------------------|----------------------------------| +| GPS sensors | UBlox F9P | 2x SwiftNav Duro | 2x SwiftNav Duro | +| Location accuracy (position & heading) | Less than 60 cm
Less than 10° | Less than 30 cm
Less than 5° | Less than 5 cm
Less than 2° | +| Path tracking accuracy (approximate) | 20 cm | 15 cm | 10 cm | + +## Limitations + +While OutdoorNav Software operates effectively in a range of rugged +outdoor environments, the operator should be aware of the following +limitations and plan accordingly. + +_OutdoorNav System Limitations_ + +| Limitation | Details | +|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| RTK accuracy | Localization accuracy for the Standard (RTK) configuration assumes the base station location has been accurately surveyed. | +| Localization accuracy | Localization accuracy is influenced by the quality of GNSS data that is available. Navigating in GNSS denied areas (e.g., under bridges, near tall buildings, etc.) will cause degradation in localization performance. | +| Negative obstacle detection not present | Outdoor Navigation Software does not have negative obstacle detection capability. Your UGV will not detect stairs, cliffs, potholes, depressions or edges and may drive into these obstacles causing harm to people or property. | +| Limited obstacle detection in vertical dimension | The small vertical field of view of 3D LiDARs limits the vertical obstacle detection capability of the OutdoorNav Software. See [Obstacle Detection Limitations](#obstacle-detection-limitations) for details. | +| Low traction may cause UGV to get stuck | Your UGV may navigate itself into a situation where wheels slip or do not make contact with the ground. | +| Rain and snow may affect obstacle detection | Adverse weather conditions may obscure obstacle detection and avoidance data from the VLP-16 LiDAR. Obstacle detection and avoidance may not function in all weather conditions and must be disabled to navigate in heavy snow or rain. | +| Maximum distance between two Viapoints | Distance between any two consecutive Viapoints of a Mission should be less than 20 meters. This will ensure that the global planner can find a valid path to the next Viapoint for the UGV in case there is an obstacle on the path of the UGV. | +| WiFi range limits | The current configurations of the OutdoorNav Software will continue navigation if the WiFi disconnects or goes out of range. The Web UI will reconnect once the WiFi has reconnected but certain functions of the UI may be limited such as the ability to issue a pause/stop commands or sending new missions to the UGV. | +| Wireless motion stop range limits | The UGV will motion stop if the UGV is driven out of range of the wireless motion stop device. | +| RTK GPS limited by WiFi range | If WiFi goes out of range, your UGV will not receive RTK corrections from the Base Station. This can potentially decrease the accuracy of the GPS signal which can subsequently degrade path following performance of your system. | +| Obstacle detection may cause UGV to become stuck | The UGV may stop and become stuck if obstacles are detected and not cleared from its path. If obstacle avoidance is enabled, it may not be able to calculate an acceptable path to the next Viapoint or Goal Point under all circumstances. This will result in the UGV becoming stuck and failing its Mission. | +| Failure to set Datum causes undefined behavior | If the Datum is not set or is not synchronized with the navigation module, the UGV's driven path is undefined and will move unpredictably if Missions are sent in this state. | +| Zones are not currently supported | It is not possible to define “keep-out” or “unsafe” zones that the UGV needs to avoid. Rather, careful use of Waypoint placement by the operator can be used to keep the UGV at a safe distance from unsafe zones. | +| No collision avoidance during teleoperation mode | When operating in Manual Mode (Teleoperation), no collision avoidance is enabled. The operator is responsible for avoiding collisions. | + +### Obstacle Detection Limitations {#obstacle-detection-limitations} + +The maximum collision avoidance range for the OutdoorNav Software is +UGV-dependent and is related to the maximum speed of the UGV. These +ranges for Clearpath Robotics UGVs are: + +- Jackal UGV: 4.5 meters +- Husky UGV: 4.5 meters +- Warthog UGV: 15.0 meters + +While the sensors are able to detect objects at further distances, the +OutdoorNav Software only considers obstacles detected within these +distances for collision avoidance. That is, the UGV will only begin to +decelerate as it detects obstacles within this range. + +The detection itself is also related to the horizontal size +(width/diameter) of the obstacle. The limitations in detecting objects +with small horizontal size are described in the table below. + +_Maximum Reliable Obstacle Detection Distance from UGV, according to Obstacle Horizontal Size_ + +| Object Size (Horizontal) | Starter Sensor Kit | Standard Sensor Kit | +|--------------------------|----------------------------------------------------------------|----------------------------------------------------------------| +| Less than 0.6 cm | No reliable detection | No reliable detection | +| 0.6 to 1.0 cm | 0.8 m | No reliable detection | +| 1.0 to 3.0 cm | 2.0 m | 1.75 m | +| Greater than 3.0 cm | Maximum collision avoidance distance (UGV-specific; see above) | Maximum collision avoidance distance (UGV-specific; see above) | + +Finally, the OutdoorNav Software bounds the obstacle detection to +prevent ground hits and to remove detections above the UGV body. The +following bounds are relative to the ground, assuming a flat surface. +Obstacles that are entirely below the lower bound or entirely above the +upper bound are not considered obstacles and will not be avoided. + +_Obstacle Detection Vertical Bounds_ + +| Vertical Bound | Jackal UGV | Husky UGV | Warthog UGV | +|-----------------------|------------|-----------|-------------| +| Lower Detection Bound | 0.3 m | 0.3 m | 0.3 m | +| Upper Detection Bound | 0.8 m | 1.3 m | 1.8 m | + +:::note + +The vertical detection bounds above are for the Standard Sensor Kit or a +custom sensor configuration that includes a Velodyne. The vertical +detection bounds for the Starter Sensor Kit have yet to be determined. + +::: \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_scope.mdx new file mode 100644 index 00000000..13f8b9af --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/overview/overview_scope.mdx @@ -0,0 +1,15 @@ +--- +title: Scope +sidebar_label: Scope +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +This documentation focuses on the OutdoorNav Software itself, including +hardware dependencies and integration, but not the specifics of UGV +hardware. For details on compatible Clearpath Robotics UGVs and custom +hardware integrations, contact or check +out our [YouTube channel](https://www.youtube.com/channel/UCNPP3C-ZK3mwpG2x89VE-2Q). + + diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/release_notes.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/release_notes.mdx new file mode 100644 index 00000000..75bef2a4 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/release_notes.mdx @@ -0,0 +1,216 @@ +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler)) +- Added in support for BulletCat12 Microhard WiFi and Cellular connections +- Allow Audio recording as both tasks and manual operations if UGV has Microphones +- Create custom tasks that can be run during missions (see [Custom Tasks](./features/custom_tasks)) +- If installed with PDU, UGV can be set to Low Power mode to better conserve power +- New navigation topics added to ROS Autonomy API (see [API Endpoints](./api/api_endpoints/autonomy_api)): + - /navigation/progress + - /navigation/motion_state + - /navigation/metrics +- Improved precision of docking +- Improved autonomy feedback when something goes wrong in the mission to increase the diagnosability of the error +- Updated Navigation features available to the customer: + - Continuous Replanning renamed to Continuous Planning and is always enabled. + - Constrained Planning is always enabled. Environment Variable to update the path constraint has been modified + (see [Navigation](./features/navigation)) + - Removed Obstacle Avoidance Mode. The UGV will always attempt to avoid obstacles. + - Removed Path Smoothing. This is always enabled. + - Docking feature added for customers who have purchased a dock. + +### Bug Fixes + +- 1324: Allow single Waypoint missions and/or tasks on first waypoint (required for undocking through tasks). +- 1340: Undocking not working through tasks +- 1607: Fixed MovePTZ task failures + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint. +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location. + +## 0.8.0 + +### New Features + +- Inertial Measurement Units (IMUs) integrated into localization. +- Added localization status topic (see [API Endpoints](./api/api_endpoints/autonomy_api#localizationstatus)). +- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions#srv-reset-localization)). +- Additional diagnostic information in the status view. +- Docking improvements including: multiple docks, visual representation of docks on map, + local docking/undocking through teleop view. Docking only functional with 2D LiDARs. +- Customization & Tuning Appendix C added. Lists of tuning parameters for navigation + and collision avoidance are now available. As well as, instructions/process on how to + tune UGVs with differential drive dynamics. Instructions for UGVs with Ackermann dynamics + are on their way. + +### Bug Fixes + +- 1134: Display/Hide Datum Point not working. +- 1139: Issues with non-husky platforms. +- 1137: Refreshing page re-enables edit button while mission running. +- 1276: Feedback added for incorrect first Waypoint placement. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1138: Issues with greying out Waypoints in edge cases. +- 1324: Allow single Waypoint missions and/or tasks on first waypoint (required for undocking through tasks). +- 1340: Undocking not working through tasks. + +## 0.7.0 + +### New Features + +- Goal terminology has been removed from the mission generation nomenclature (see + [Definitions](./web_user_interface/ui_autonomous_mode#definitions)) + Users can now add tasks, apply final headings, and set navigation tolerances + to any Waypoint in a Mission. +- Drag and Drop of Waypoints now available in Edit Mode. +- New Waypoints can be inserted between existing Waypoints in a Mission. +- Mission API now available to create/edit/load missions, waypoints and tasks. +- Mission execution via mission ID is now available. +- The base station location is now displayed in the UI after carrying out an automated survey. +- New coloring scheme for GNSS status icons to provide more accurate information. + +### Bug Fixes + +- 996: Axis camera missing ptz_state + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1134: Display/Hide Datum point not working. +- 1137: Refreshing page re-enables edit button while mission running. +- 1138: Issues with greying out Waypoints in edge cases. + +## 0.6.0 + +### New Features + +- OutdoorNav ROS API updated. API now divided into Platform and + Autonomy sections. See [API Overview](./api/api_overview) + for more details. +- Simulation environment created with charge dock, base station and + camera plugins. +- Added deviation path visualization to UI when constrained replanning + is enabled. +- Modified goalpoint icons to reflect tasks assigned to them. +- Added the ability to record rosbags from UI. +- Added GPS signal strength to status page. +- Added improvements to PTZ controls (cosmetic changes, ability to + disable zoom, added a reset mark). +- User can set map source from OpenStreet, MapBox, Bing Maps, or + custom map tiles through UI. + +### Bug Fixes + +- 632: Prevent users from changing mission while a mission is running. +- 661: Removed map view when no map is provided in default-state.json. + file. +- 712: Fixed front end hanging when user opens menu from any view + other than main view. +- 716: Removed connecting lines from disabled goals. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 756: Waypoints stop turning grey when they are hit if a waypoint is + skipped. + +## 0.5.0 + +### New Features + +- Sensor Kit Options: Starter, Standard, Backpack. +- New localization module. +- Added support for UBlox F9K and F9P GNSS receivers in the + localization module. +- Added support for either single or dual Swiftnav Duro/Piksi GNSS + receiver(s) in the localization module. +- Added support for Realsense D435 camera in collision avoidance + module. +- New/updated user modifiable environment variables for sensor and + navigation tuning. +- Added a Virtual Guided tour of the application for first time users. +- Added StreetView and Bing map tiles (to existing MapBox tile). +- Allow users to specify custom map tile source. +- Added cosmetic changes to traversed waypoints as well as a robot. + status icon with ROS topic health information. + +### Bug Fixes + +- 253: Replace default camera image for camera views when stream is + unavailable. +- 281: Fixed navigation latched in a PAUSE state. +- 574: Fixed map settings page to not rerender when robots position + changes. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. + +## 0.4.0 + +### New Features + +- Improved wireless charger docking workflow and added ROS Noetic + docking support. +- Added option to record videos from cameras. +- Improved Docker setup to allow concurrent installation with + IndoorNav. +- Added initial support for integration with + [Formant](https://formant.io/). +- Added Docker installation support for Jackal and Warthog robots. + +### Bug Fixes + +- 480: Added rate limiter for continuous planner. +- 490: Fixed base station survey pop up to better reflect survey time. + +### Known Issues + +- 131: Software upgrade process not documented fully. + +## 0.3.0 + +### New Features + +- Upgraded from ROS Melodic to ROS Noetic. +- Published initial performance metrics. +- Updated system architecture to work in Docker containers. + +### Bug Fixes + +- 266: Allowed map offsets to be set more than once without needing to + reset them back to zero. +- 365: Updated costmap to handle large stop distances properly. +- 377: Fixed handling of goal tolerances of 0.02m or less. +- 389: Fixed issue with goal being skipped in some cases where final + heading was specified. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 150: Docking not yet implemented in Noetic. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/safety.mdx new file mode 100644 index 00000000..ea70a51b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/safety.mdx @@ -0,0 +1,144 @@ +--- +title: Safety +sidebar_label: Safety +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Important Safety Information + +The use of Unmanned Ground Vehicles (UGVs) can result in unexpected and +dangerous behavior. Although Clearpath Robotics endeavors to create safe +and reliable software and systems, autonomous outdoor UGVs should not be +considered safe for unsupervised use around humans or other obstacles. +No level of safety and reliability of software and non-safety rated +hardware components is guaranteed. + +Clearpath strongly recommends that users carry out a risk assessment +related to their application and deployment of autonomous UGVs. The +ISO-12100 standard [Risk assessment and risk reduction](https://www.iso.org/standard/51528.html) provides guidance on +performing risk assessments. + +Functional safety in robotics is often achieved through the use of +safety related parts and control systems to minimize risks such as +safety LiDARs for obstacle detection. These hardware components must be +designed into the UGV hardware and can be tightly integrated with +navigation software. Clearpath Robotics recommends that this process be +undertaken after the product or process has been fully defined. It can +be a significant design effort. + +## Safety Notice Levels + +For Clearpath Robotics hardware and software, the risk level is captured +using the following types of labels. + +![](/img/outdoornav_images/safety_information.png) + +## General Hazard Labels + +Review the following to learn more about the labels that may be used on +Clearpath Robotics products. Hazards can also apply to attachments and +accessories used in conjunction with a Clearpath Robotics product. UGVs +from other providers may present additional hazards and risks. + +_General Hazards_ + +| Label | Label Title | Label Description | +|--------------------------------------------------------------------------------------|----------------------|------------------------------------------| +|
| Automatic Motion Hazard | Clearpath Robotics UGVs may begin moving suddenly, either autonomously or when being driven manually. Always be aware of Clearpath Robotics products and their potential for movement. | +|
| Crushing Risk | Objects or personnel can be crushed between the Clearpath Robotics UGV and another object. Keep hands and other objects clear of crush points at all times. Keep clear of all docking Clearpath Robotics UGVs. | +|
| Electrical Shock Risk | Clearpath Robotics UGVs contain circuitry and batteries that may cause electrical shock if not properly insulated. | +|
| Entanglement Risk | Clearpath Robotics UGVs as well as their cameras can lead to entanglement of hair or dangling materials during their rotation. Keep hair and dangling materials away from Clearpath Robotics UGVs during motion. | +|
| Environmental Hazard | Clearpath Robotics UGVs contain batteries and materials that may require special disposal methods. Consult local regulations. | +|
| Falling Object Risk | Beware of objects that may have shifted in any Clearpath Robotics UGV crate as they pose a risk of falling when opened. | +|
| High Surface Temperature Risk | UGV computer heat sinks and UGV motors can become extremely hot during operation. | +|
| Impact Risk | Clearpath Robotics UGVs travelling through a facility can potentially impact objects and personnel. Keep clear of all docking Clearpath Robotics UGVs. | +|
| Laser Radiation Risk | Clearpath Robotics UGVs may use Class 1 laser products. These provide no hazard during normal use, however it is not recommended to stare directly into the beam(s). | +|
| Material Hazard - Lithium | Lithium UGV batteries contain harmful material. Always use proper handling procedures when handling UGV batteries. | +|
| Manual Load Lifting Risk | Always use ergonomic techniques when manually lifting loads. | +|
| Pinching Risk | Keep hands and other objects clear of pinch points at all times. Keep clear of all docking Clearpath Robotics UGVs. | +|
| Radio Frequency Risk | Clearpath Robotics UGVs and/or accessories may use radio frequency (RF) radiating antennas. These provide no hazard during normal use, however prolonged exposure around the antenna is not recommended. | +|
| Tripping Hazard | Clearpath Robotics products may pose a tripping hazard. | + +## Safety Awareness + +Personnel present during the operation of an Unmanned Ground Vehicle +(UGV) need to be made aware or be accompanied by personnel who are +familiar with the specific risks and hazards associated with autonomous +mobile robots (AMR). The following checklist identifies basic topics +that should be addressed by site-specific worker and visitor safety +orientation training. + +
+ +
+ +- Proper PPE must be worn, including safety footwear (ie. steel toe). +- Crossing into the path of a moving UGV should be avoided, as well as + placing or throwing obstacles into the path of a moving UGV. + +
+ +
+ +- Be aware that a UGV can be anywhere in the operating area of the + facility at any time, and may pose a tripping hazard even when not + in motion. +- Personnel need to be aware of the UGV docking and charging areas, + where detection fields are reduced. +- Personnel should be aware that Clearpath Robotics UGVs LiDAR safety + scanners use a class 1 laser and high intensity LED. +- Personnel should keep all loose clothing and body parts away from + UGVs, accessories, attachments, and payloads, while they are in + autonomous operation. Using an Emergency Stop button is the only + acceptable manner of interacting with a Clearpath Robotics UGV or + attachment while it is being operated autonomously. + +In addition to the preceding basic items for all workers and visitors, +the following should be considered for facility personnel, including +drivers of other UGVs: + +- When required to move a product manually, personnel must ensure it + is in an Emergency Stop state or shut down completely and should not + push manually for prolonged periods. +- Alert personnel that while operating a Clearpath Robotics UGV + outside of the Autonomy State, they are solely responsible for + obstacle and collision avoidance. +- Maintenance of a Clearpath UGV not outlined in either this document + or the operations and maintenance manual can only be performed by a + Clearpath Robotics Authorized Personnel. + +To reduce the risk of harming people or damaging properties, a trained +operator must monitor the behavior of the UGV under autonomous +navigation mode at all times. The operator should use the wireless +emergency stop device to immediately avert any possible damaging or +dangerous behavior from the UGV. Failure in proper use of the software +might result in collision of the UGV into objects. + +- The minimum height for detecting obstacles under ideal operation + conditions (flat ground, no snow/rain/fog, normal operation of the + LiDAR, etc) when using the standard Clearpath Robotics OutdoorNav + Hardware package on a Husky is typically 0.2 meters high at 2.3 + meters distance away from the UGV. Your UGV may differ. Ensure that + low-height obstacles are removed from the potential path of the UGV + prior to operation. +- OutdoorNav Software does not have negative obstacle detection + capability. This means that your UGV will not detect stairs, cliffs + or edges and may drive off these obstacles causing harm to people or + properties as well as potentially damage the UGV. +- Adverse weather conditions may obscure obstacle detection and + avoidance data from the VLP-16 LiDAR. Obstacle detection and + avoidance may not function properly in snow, rain or fog. +- The current configurations of the OutdoorNav Software will continue + navigation if the WiFi disconnects or goes out of range. The Web UI + will reconnect once the WiFi has reconnected but certain functions + of the Web UI may be limited such as the ability to issue a stop + command or send new missions to the UGV. +- If connection of the UGV to the base station is lost (e.g., WiFi + goes out of range, low battery level, etc), UGV will not receive RTK + corrections from the base station. This can potentially decrease the + accuracy of the GPS signal which can subsequently degrade path + following performance of your system. +- Obstacle detection and avoidance is disabled during the docking and + undocking operations. Keep this area clear of people and objects. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/simulation.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/simulation.mdx new file mode 100644 index 00000000..44cff5f7 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/simulation.mdx @@ -0,0 +1,20 @@ +--- +title: Simulation +sidebar_label: Simulation +sidebar_position: 9 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Simulation with OutdoorNav Software can be useful in several ways. + +- It provides an easy (and low cost!) way of evaluating the main + features in OutdoorNav Software prior to purchasing. +- It allows missions to be planned, executed, and refined in a + repeatable way prior to deployment on UGV hardware. This can be + particularly helpful when integrating OutdoorNav into a larger + software solution, such as a fleet manager. + +At present, OutdoorNav Software simulation is restricted to internal +Clearpath Robotics development and select partners, but is planned for +full deployment. Check back soon for further details. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/support.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/support.mdx new file mode 100644 index 00000000..9212d99f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/support.mdx @@ -0,0 +1,11 @@ +--- +title: Support +sidebar_label: Support +sidebar_position: 11 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import OutdoorNavSupport from "/components/support_outdoornav.mdx"; + + \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/_category_.json new file mode 100644 index 00000000..a07ca158 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Web User Interface", + "position": 6 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_autonomous_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_autonomous_mode.mdx new file mode 100644 index 00000000..66bd7d4d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_autonomous_mode.mdx @@ -0,0 +1,369 @@ +--- +title: Web UI Autonomous Mode +sidebar_label: Web UI Autonomous Mode +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +![](/img/outdoornav_images/gps_danger.png) + +Ensure that the [Safety](../safety) document has been +read and the user is aware of possible hazards when using this product as well as the safety +methods that can be used to stop the moving UGV. + +The Autonomous Mode of OutdoorNav Software is a set of robotic +navigation modules that enables robotics developers to define and then +autonomously execute missions on UGVs, getting work done without +requiring direct operator action. This software is composed of four main +modules: localization, navigation, safety monitoring and user control +unit. This a combination of Clearpath's proprietary packages and custom +configured open-source packages from ROS community. Please see the +software architecture section for more information. + +## Definitions {#definitions} + +The list below defines what a "Mission" is as well as its components. +These components are referred to throughout this manual. + +- **Mission** A Mission is a set of one or more Waypoints. +- **Path** The list of Waypoints that will determine the path + for the specific Mission. +- **Waypoint** A Waypoint is any geographical point referenced by its + position relative to the datum in meters. +- **Task** A Task is an automated activity or wait time implemented as + a ROS action at a specific Waypoint. Tasks are called in the order they are + added to a Waypoint. +- **Ghost Waypoint** A transparent waypoint that is not part of the mission. This + Waypoint appears between two other waypoints when in edit mode. The user can + drag and drop this ghost waypoint to add a new waypoint to the mission between + the other two waypoints. + +## Map Settings + +
+
+ +
Map settings
+
+
+ +To access the Map Settings: Menu → Settings → Map: + +1. **Map Offset:** The map tiles used in this software are not + perfectly aligned with the real world. Therefore, the user may need + to apply an offset to the map so that the UGV's position in the + real world matches its position on the map. +2. **Change Datum:** The datum is represented by a blue marker on the + map and should be set to a location within 10km of the test site. + The user can change this value in the Map Settings page. Enter the + new values and click the "Set Datum" button. + +## Mission Creation + +To create a new Mission first ensure that the UI is in "Edit Mode" ( +select the pencil icon in the bottom bar). Then open the drop down menu in the bottom +bar and select the "Add Mission" option. This will allow the user to create a new mission +which can then be defined with Waypoints. + +### Waypoint Mode + +To add new Waypoints to a mission while edit mode is enabled select the +"Waypoint Mode" button. This will allow the user to place Waypoints at +locations where the user clicks on the map. These will appear as red +Waypoints with the exception of the first waypoint (green) and the last waypoint (yellow). + +:::note + +**The first Waypoint in the mission must be within 3.0 meters of the UGV's current position.** + +::: + +As Waypoints are placed, a "ghost waypoint" will appear between each pair of real +Waypoints and can be dragged to a new spot to insert a real Waypoint +between them. Waypoints can also be dragged and dropped on the map to +modify their positions. + +### Waypoint Panel + +
+
+ +
Waypoint Panel
+
+
+ +Enable the "Waypoint Panel" toggle to open the list of available Waypoints +within the selected Mission as shown in the figure above. The user can +now rearrange the list, rename Waypoints, add Tasks to the Waypoints, +and modify the final heading and/or tolerance of each Waypoint. + +### Rearrange List of Waypoints + +Waypoints can be rearranged in order of operation in the list. To do this, +enable the "Waypoints Panel" toggle to access the list of Waypoints. Here, the +user will be able to drag and drop the Waypoints to reorder them. + +### Rename Waypoint + +By default, once Waypoints are created they are assigned a default name +which is the word "Waypoint" followed by a numeric value representing the +the number of Waypoints that have been created plus one. The user has the +option to rename these Waypoints in order for them to have more descriptive +meaning. + +To rename a Waypoint follow these steps: + +1. Enable the "Waypoint Panel" toggle. See [Waypoint Panel](#waypoint-panel) + for further details. +2. Click the name of the Waypoint which the user wants to rename. +3. Erase the current name and type the new name. + +### Add Task to Waypoint {#add-task} + +
+
+ +
Add Task to Waypoint
+
+
+ +To add a Task to the end of a Mission: + +1. Click the "+" icon (beside the Gear icon) in the Waypoint Row the Task is + to be added to. + +2. Click the "Add Task" Button that has appeared. + +3. Select the Task from the dropdown list. Standard waypoint icons will be + replaced accordingly depending on the task selected (waypoint icons will keep the colours + assigned to them based on placement). + + - Dock UGV: + Will dock the UGV to begin charging the UGV's + battery. See [Autonomous Docking](#autonomous-docking) + for more information on the autonomous docking feature. + + - Move PTZ: + Will move the PTZ camera to the position selected + in the task settings. + + Settings: Select the camera position. See + [Pan-Tilt-Zoom (PTZ) View](./ui_overview#ptz-view) for details on how to + save camera positions. + + - Save Image: + Will save an image using one of the UGV camera(s) + to the **~/clearpath_files** folder and can be retrieved using a tool + such as Filezilla. + + Settings: Select which camera the image will be saved from. + + - Start/Stop Video Recording: + Will start/stop recording video using one of the + UGV camera(s) to the **~/clearpath_files** folder and can be retrieved + using a tool such as Filezilla. + + Settings: Select which camera the recording will come from. + + - Undock UGV: + Will undock the UGV from the autocharge dock. Once + completed, the UGV can be sent on autonomous missions. It is + often recommended to place the undock task first in the list of Waypoints; + that way, the UGV will automatically continue towards its next + Waypoint once undocked. + + - Wait: + Will pause and wait for the specified number of + seconds at the end of the Waypoint. + + Settings: Enter the amount of time to wait, in seconds. + + - New Custom Task: + Creates a new custom task that is defined by the user. +
+
+ +
Custom Task Settings Dialog
+
+
+ + - Task Name: Task name that will show up in the list of available tasks on the UI. + - Action Server Name: The namespace of the custom task action server. + - Float CSV: A list of comma seperated float values that consist of the numerical inputs to the custom task. + - String CSV: A list of comma seperated string values that consist of the semantic inputs to the custom task. + + See the [Custom Tasks](../features/custom_tasks) section + for details on how to develop custom tasks for your application. + +4. Click the Gear icon next to the selected Task to add the required + Settings. + + :::note + + If a waypoint has more than one task assigned to it, the icon will + be replaced with + + ::: + +### Advanced Settings + + + +#### Waypoint Heading + +When creating a Waypoint, the user has the option of setting a final heading +for the Waypoint. For example, when creating a Waypoint at an inspection point, +the user may want the UGV to navigate and stop facing a certain +direction. In [Waypoint Panel](#waypoint-panel), the list of +Waypoints can be seen and the advanced settings of each Waypoint can be accessed +by clicking the "Gear" icon. + +To set the Waypoint's final heading, the user will need to check the +"Final Heading Enabled" checkbox and enter the heading value in +degrees. The heading indicator on the top bar can be used to help set +this value. See the figure below showing the advanced settings. + +
+
+ +
Waypoint Advanced Settings
+
+
+ +The heading that has been entered will only be applied to the Waypoint +(ie. the robot will only align itself with the correct heading at the +Waypoint). If the robot is required to be at specific headings at +other Waypoints the user will need to enter these in for each specific Waypoint. + +#### Waypoint Tolerance + +When creating a Mission, the user has the option of setting a specific +tolerance for each Waypoint. By default, the Waypoint position and orientation +tolerances are 0.3 meters and 180°, respectively. If a specific Waypoint +requires that the tolerances be either increased or decreased, these +values can be modified in the advanced settings. For example, if it's +required that the position and/or orientation at a Waypoint be very accurate, +such as 0.1 meters position and 5° orientation, or looser at 1.0 meter +position, this can be done within these settings. + +In [Waypoint Panel](#waypoint-panel), the list of waypoints can be +seen and the advanced settings of each Waypoint can be accessed by clicking +the "Gear" icon. To set the Waypoint's tolerance, the user will need to +check the "Waypoint Tolerance Enabled" checkbox and enter the position and +orientation values, in meters and degrees, respectively. + +### Constrained Replanning {#constrained_path} + +To enable the visualization of the contrained area of traversal (defined by +the path contraint around the reference path), navigate to the General settings +in the hamburger menu. Enable/disable the visualization of the path ui_route_deviation +distance using the switch button (see image below). + +
+
+ +
General settings
+
+
+ +Once enabled the area of possible deviation will show +over the planned route as can be seen in the following figure. + +
+
+ +
Route with maximum path deviation
+
+
+ +:::note + +If the UGV is manually driven outside of the constrained replanning area +while a Mission is running, the Mission will not be able to be resumed until the +UGV is returned within the navigable area defined by the path contraint. + +::: + +## Mission Execution + +### Start Mission + +At the bottom of the UI, the user has the ability to start the currently +selected Mission by clicking the "Play" button . When the +Mission has been started this button will turn green. + +### Pause Mission + +At the bottom of the UI, the user has the ability to pause the currently +running mission by clicking the "Pause" button . When the +mission has been paused this button will turn yellow. Pausing a mission +allows the user to take time to look around with the camera or to +teleoperate the UGV to a nearby location to perform an inspection. For +ease of operation, the user must PAUSE the active mission if the user +wants to teleoperate the UGV. + +### Cancel Mission/Task + +At the bottom of the UI, the user has the ability to stop the currently +running mission or task by clicking the "Stop" button . When the +mission/task has been cancelled this button will turn red. The name of +the mission/task will be shown to be cancelled in the feedback bar. + +## Autonomous Docking + +
+
+ +
Dock Icon
+
+
+ +### Docking The UGV + +To dock the UGV autonomously, the user should follow these steps: + +- Enable the "Edit Mission" toggle. +- Create a Mission whose Waypoints approach the dock from the front and + whose final Waypoint is within the maximum predock distance which is shown as a circle around the dock. +- Enable the Waypoints Panel toggle to view the list of Waypoints, rename the last + Waypoint to "Dock Waypoint" or something descriptive and add the "Dock + UGV" Task to this Waypoint. If there is more than one dock in the system the user will + have to open the task options and select the dock name from the list. +- Run the Mission. + +### Undocking The UGV + +To undock the UGV autonomously, the user should follow these steps: + +- Enable the "Edit Mission" toggle. Select the "Waypoint Mode" + button. +- Select the Waypoint icon on the bottom bar to create a Waypoint at the + current location of the UGV. This step should either be it's own mission + or it should be the starting point of a mission. +- Enable the Waypoints Panel toggle to view the list of Waypoints, rename this + Waypoint to "Undock Waypoint" or something descriptive and add the + "Undock UGV" task to the Waypoint that was just created. +- Run the Mission. + +### Compatibility with a Doghouse + +In order for the autonomous docking feature to be compatible with a doghouse, the +doghouse must conform to a few specifications: + +- Must be installed on a flat surface, and have no elevation change between the + charge-deck and the outdoor surface (ie. no ramp into the doghouse). +- Must be greater than 1.2 m wide. +- Must be between 1.5 and 2.5 m long. +- Dock target should be installed centered along the back of the doghouse. + +### Recover from Failed Docking or Undocking + +If for any reason, the docking or undocking tasks fail, the user can: + +- Manually drive the UGV towards the dock target, aligning the + charging unit with the receiver on the UGV. +- Manually drive the UGV in reverse away from the dock target. It is + suggested that the user reverse roughly 2-3 meters away from the target, + then wait 1-2 minutes before starting any autonomous navigation + missions. diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_manual_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_manual_mode.mdx new file mode 100644 index 00000000..a18672dc --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_manual_mode.mdx @@ -0,0 +1,49 @@ +--- +title: Web UI Manual Mode (Teleoperation) +sidebar_label: Web UI Manual Mode (Teleoperation) +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Manual Mode in the Web UI allows the user to operate the UGV +remotely (teleoperate) by using sensors on the UGV to visualize the +environment and by using a joystick to control the motion of the UGV. + +![](/img/outdoornav_images/teleop_danger.png) + +Ensure that you have read [Safety](../safety) and are +aware of possible hazards when using this product as well as the safety +methods that can be used to stop the moving UGV. + +
+
+ +
Teleoperation Components
+
+
+ +1. **Speedometer:** An indicator of the UGV's current forward speed. +2. **Joystick:** The joystick will allow the user to move the UGV + manually from the UI. Motion can be sent to the UGV in 360° + directions and the speed can be controlled by the distance of the + joystick from its neutral position. +3. **Sensitivity Scale:** A UGV-specific scale that controls the + maximum allowable UGV velocities at each level. The maximum linear + velocity is 1.0 meters per second and the maximum angular velocity + is 0.5 radians per second. The scale levels are 100%, 80%, 50% and + 20%, with the default set to 80%. +4. **Local Docking Buttons:** The local docking/undocking buttons used + to dock/undock the UGV through the teleop view. To dock, the UGV + must be within the predock distance and facing the dock before the + button is selected. + +## Monitor Wireless Strength + +While teleoperating the UGV, the user will notice that the delay between +the time a command is sent and the time it is executed (and/or visible +on the UI camera views) will increase as the distance increases. This +effect will be further amplified by any obstacles between the UGV and +the base (eg. walls, vehicles, mounds, etc.). It is important to monitor +this delay an be cautious when driving the UGV with larger delay for +risk of crashing into obstacles. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_overview.mdx new file mode 100644 index 00000000..aafe45f2 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/web_user_interface/ui_overview.mdx @@ -0,0 +1,422 @@ +--- +title: Web UI Overview +sidebar_label: Web UI Overview +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Web User Interface (Web UI) provides a easy, graphical, means to +control both manual and autonomous operation of your UGV. The following +sections outline: the components and views of the UI, the details of +operating in manual mode, and the details of operating in autonomous +mode. + +## Main Components + +
+
+ +
UI Main Components
+
+
+ +1. **Menu:** A dropdown menu allowing the user to access the Dashboard + (ie. Home), Settings, Status, Scheduler and Help pages. The Operator + can also run the UI Virtual Tour from this menu. + +2. **Feedback Bar:** The feedback bar will display information + regarding the execution state of the navigation and of any Tasks + being executed. + +3. **Path Progress Meter:** A meter indicating the percentage complete + of a Mission. + +4. **UGV Position:** The UGV's X and Y position in the world frame + relative to the Datum. Can also be shown in Lat/Lon coordinates + +5. **UGV Heading:** The UGV's heading in the world frame. 0 degrees is North, 90 degrees is East, 180 degrees is South and 270 degrees is West. + +6. **Status Indicator:** The status indicator will display information + regarding various UGV status monitors such as the Emergency Stop, + Surveying, etc. When the UGV is fully operational, the indicator + will be green. Operators can click on the status indicator to see more details + pertaining to the current state as well as past messages. + +7. **GPS Status Indicator:** The GPS status indicators will display GPS + signal accuracy for position (POS indicator) and heading (DIR + indicator). Green indicators represent RTK accuracy and are + currently required for accurate autonomous navigation. Yellow and orange + indicators represent SBAS and SPP accuracy respectively and noticeable + oscillations may occur in such cases. Red indicators mean no GPS signal + and autonomous navigation missions should not be started. + +8. **Battery Life Indicator:** The UGV's battery life indicator. + + :::note + + If the indicator is stuck at 50%, that means that your UGV does not + have a supported battery management system and this indicator is not + active. + + ::: + +9. **Wireless Connection Indicator:** The wireless connection indicator + represents the signal strength between the wifi access point + (typically the Base Station) and the UGV. If the system can support + cellular connections a cellular indicator will appear next to the + wifi icon with the currently active connection being highlighted in green. + +10. **Views List:** A dropdown list of available views, detailed later + in this section. Some of the available views are Map, Camera and 3D + views, etc. + +11. **Record Audio:** If the UGV is equipped with a microphone the user + can start/stop recording manually by clicking this icon. + +12. **Mission List:** View the list of Missions that Operator(s) have + created. + +13. **Edit Mission Toggle:** This toggle allows the Operator to start + creating Waypoints for the current Mission. The Operator will also be able to + drag and drop Waypoints in this mode. Once this button is enabled, + the Waypoint Mode will be available for selection. When a Mission is + started this toggle will be disabled (ie. the Operator will not be able + to modify/add Waypoints). + + :::note + + If the toggle is enabled while an autonomous Mission is running, it + will cancel the current Mission. + + ::: + +14. **Waypoint Panel Toggle:** View list of Waypoints in the current Mission. + +15. **Waypoint Drop Button:** The Waypoint indicator marker on the + bottom bar allows the Operator to place a Waypoint at the location of the UGV. + +16. **Start Button:** Start the current Mission. + +17. **Pause Button:** Pause the current Mission. Pressing the start button + while paused will continue the current Mission. + +18. **Stop Button:** Cancel the Mission or Task that is currently being + executed. Pressing the start button while when stopped will restart + the list of steps in the current Mission. + + +By opening the dropdown list "Views", on the right side of the UI, the +Operator can access the following views: + +- Map View +- PTZ Camera View (if available) +- Front/Back Camera View (if available) +- 3D View + +## Map View + +
+
+ +
Map View
+
+
+ +1. **Zoom Buttons:** These buttons allow the user to zoom in/out of the + map levels. +2. **Zoom-to-Fit Button:** This button will zoom the map to where there + is activity (ie. where the datum is set or where Waypoints have been + set on the map. +3. **Pointer Mode Button:** This button allows the user to move the map + and select point on the map to see their coordinate (lat/lon or + x/y). +4. **Waypoint Mode Button:** This button allows the user to place + Waypoints on the map. Users can also select existing Waypoints to + modify/delete them. +5. **UGV:** The blue arrow represents the UGV. Its location is its + position in the world frame and its orientation is the heading in + the world frame. +6. **Base Station:** The yellow antenna icon is the last known location of + the base station based on the last survey performed. By clicking it the + user will be presented with the base station's coordinates, when it was + surveyed, and how many samples were taken during the survey. + +7. **Datum:** The blue Waypoint marker on the map view represents the + location of the reference point (ie. (x,y)=(0,0)) of the world + coordinate system. The world (ie. map) coordinate system is in the + ENU convention. +8. **Scale:** The scale representing the ratio of a distance on the map + to the corresponding distance on the ground. + +## Camera Views + +:::note + +If PTZ and/or Front/Back camera(s) are included on the UGV, their feeds +can be viewed through the UI and the PTZ can be controlled through the +UI. If not, there will not be any PTZ, Front/Back view(s) in the list of +available views. + +::: + +### Pan-Tilt-Zoom (PTZ) View {#ptz-view} + +
+
+ +
PTZ Camera View
+
+
+ +1. **Tilt Slider:** The left slider can be used to tilt the camera in a + vertical motion, (ie. upwards or downwards motion). By default, the + slider is at its neutral ("zero") position. +2. **Pan Slider:** The bottom slider can be used to pan/rotate the + camera, (ie. rotational motion). By default, the slider is at its + neutral ("zero") position. +3. **Zoom Slider:** The right slider can be used to zoom the camera + feed. By default, the slider is at its neutral ("zero") position. +4. **Save Image:** Depending on the current camera view selected, this + button will save an image to the computer/tablet running the UI. + Images will be saved to the location in which your browser saves + files. +5. **Camera Positions List:** Display the list of available camera + positions that have been saved. These camera positions can be + deleted from this list by clicking the "garbage can" icon beside + the corresponding position. +6. **Save Camera Position:** This button will save the camera position + to be used in the "Move PTZ" task. An example use case would be: + 1. Switch to the PTZ camera view. + 2. Teleoperate the UGV to a location at which the user can inspect + something. + 3. Move the camera sliders to orient the camera such that it is + looking at the inspection point. + 4. Click the "Save Camera Position". + 5. When creating an autonomous mission to this inspection point, + add the "Move PTZ" task to a Waypoint. + 6. Click the settings button beside the task and add the camera + position related to the inspection point. + +### Front and Back Views + +
+
+ +
Front View
+
+
+ +
+
+ +
Back View
+
+
+ +## 3D View + +The 3D view allows the user to visualize the pointcloud data being +acquired by the VLP-16 LiDAR. + +
+
+ +
3D View
+
+
+ +## System Configuration + +### General Settings + +The General settings section can be found in through the upper left hand menu and allows the Operator to modify +general features of the UGV. + +
+
+ +
General Settings Page
+
+
+ +#### Coordinates + +The Operator can change the coordinate space from X/Y relative to the Datum to Latitude/Longitude. + +#### Save Image Location + +The Operator can choose to store images saved manually to the robot directly or to download them onto their computer. This +feature only affects the manual save image option found on each relevant camera view. + +#### Robot Internet Connection Type + +If the UGV is equipped with SIM card and can switch between Cellular and WiFi connections, the Operator can manually trigger this +change through the general settings page. This switchover will take approximately 30 seconds and will require a refresh on the UI. + +#### Show Path Deviation Distance + +When a mission is running the UGV will have a maximum path deviation distance that it shouldn't cross if it needs to replan. If this +toggle is set to true, while in edit mode this buffer is shown over top of the path as the Operator creates/edits the mission. This +toggle does not disable the path deviation distance feature. + +#### Low Power Mode + +If the UGV is equipped with a Low Power Module this toggle allows the user to switch the UGV into a low power state that will drastically +limit functionality but help conserve power. This mode is best used to help better facilitate charging while the UGV is not in use. + +### Map Source Configuration + +The Web UI ships with access to free +[OpenStreetMap](https://www.openstreetmap.org/) maps. Aerial view +requires access to third-party aerial maps or your own aerial maps. + +The Web UI is pre-configured to work with +[MapBox](https://www.mapbox.com/) and [Bing +Maps](https://www.bingmapsportal.com/) once a suitable map key has been +acquired. Both services offer a free tier that will be sufficient in +almost all cases. + +#### Using OpenStreetMap Maps + +As no key is required to use +[OpenStreetMap](https://www.openstreetmap.org/) maps, the process to +select these maps in the Web UI is simple. + +1. In the Web UI, from the menu, select **Settings→Map** to bring up + the **Map Settings** page. +2. Select **OpenStreetMap** +3. Click **Ok**. + +
+
+ +
Using Map Settings to select OpenStreetMap
+
+
+ +#### Using MapBox Maps + +Using [MapBox](https://www.mapbox.com/) maps requires a key, which can +then be used by the Web UI. The steps to set up MapBox are outlined +below. + +1. Acquire a MapBox key from the [MapBox + website](https://account.mapbox.com/auth/signup/). Review the + license terms and select the appropriate plan. In most cases, the + free tier will be sufficient. +2. Back in the Web UI, from the menu, select **Settings→Map** to bring + up the **Map Settings** page. +3. Select **MapBox**. +4. Copy the MapBox key from Step 1 into the **Map Key** field. +5. Click **Ok**. + +
+
+ +
Using Map Settings to select MapBox
+
+
+ +#### Using Bing Maps + +Using [Bing Maps](https://www.bingmapsportal.com/) requires a key, which +can then be used by the Web UI. The steps to set up Bing Maps are +outlined below. + +1. Acquire a Bing Maps key from the [Bing + website](https://www.microsoft.com/en-us/maps/create-a-bing-maps-key). + Review the license terms and select the appropriate plan. In most + cases, the free tier will be sufficient. +2. Back in the Web UI, from the menu, select **Settings→Map** to bring + up the **Map Settings** page. +3. Select **Bing Maps**. +4. Copy the Bing Maps key from Step 1 into the **Map Key** field. +5. Click **Ok**. + +
+
+ +
Using Map Settings to select Bing Maps
+
+
+ +#### Using Custom Maps {#using_custom_maps} + +Custom Maps allow you to use another set of maps in XYZ format, either +from a third-party map provider or from maps that you have generated on +your own, such as from drone aerial images. Custom maps can be selected +by using the steps below. + +1. Ensure that the maps are accessible on an internal network or on the + Internet by the device that is being used to display the Web UI, + such as a laptop, tablet, or desktop computer. +2. Ensure that the directory structure for the individual tiles is well + defined. See the section below for details on + [Preparing Custom Map Tiles from Drone Aerial Images](#preparing_custom_map_tiles). +3. In the Web UI, from the menu, select **Settings→Map** to bring up + the **Map Settings** page. +4. Select **Custom**. +5. Enter the network path for the maps into the **Custom URL** field. + If hosting the maps on your local computer, this will be similar to + . Note how the + URL is parameterized with `{z}`, `{x}`, and `{-y}` values. This will + need to be adapted to match the directory structure of your map tile + images. +6. Click **Ok**. + +
+
+ +
Using Map Settings to select Custom maps
+
+
+ +#### Preparing Custom Map Tiles from Drone Aerial Images {#preparing_custom_map_tiles} + +In some cases, it is desirable to create your own maps rather than using +third party maps which might be outdated. One way to do this is to use a +drone to capture aerial images and convert those images into map tiles. +While there are many ways to accomplish this, one approach is outlined +below. + +1. Use a drone to collect top-down photos covering the area of + interest. It is highly recommended to use a drone control app that + allows you to specify the area of interest and desired image overlap + (recommended \~75%) and takes care of coverage planning, drone + control, and image acquisition. + +2. Perform ortho-mosaicing/ortho-rectification to stitch the collected + images together into a single orthographic image. [Open Drone + Map](https://www.opendronemap.org/) is a popular open source project + that Clearpath has used for stitching, but there are also paid + services that automate the process. + +3. Georeference the orthographic image. One way to do this is to define + the locations of well-defined features (sewer grates, utility holes, + etc.) based on their known positions, such as their position data + from an existing mapping service (e.g., Google Maps). Open source + tools, such as [QGIS](https://www.qgis.org/en/site/) can help with + this process. + +4. Generate the map tiles. Using Ubuntu, this can be accomplished with + the following commands, where `GEOREFERENCED_IMG.tif` is the output + of the previous step. + + ``` + sudo apt install gdal-bin + gdal2tiles.py + ``` + +5. Use a web server to host the tiles locally. Using Ubuntu, one way to + accomplish this is to use the commands below, which will make the + tiles available at: . + + ``` + cd /base/directory/of/tiles + python3 -m http.server + ``` + +Once your map tiles are available on the network, you can follow the +steps in [Using Custom Maps](#using_custom_maps) to have the +Web UI use your custom tiles. diff --git a/outdoornav_user_manual_versioned_sidebars/version-0.9.0-sidebars.json b/outdoornav_user_manual_versioned_sidebars/version-0.9.0-sidebars.json new file mode 100644 index 00000000..2782dc0f --- /dev/null +++ b/outdoornav_user_manual_versioned_sidebars/version-0.9.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "sidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/outdoornav_user_manual_versions.json b/outdoornav_user_manual_versions.json index 4f53e144..934bf6ce 100644 --- a/outdoornav_user_manual_versions.json +++ b/outdoornav_user_manual_versions.json @@ -1,4 +1,5 @@ [ + "0.9.0", "0.8.0", "0.7.0", "Legacy" diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 2369b658..12143c64 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -12,7 +12,7 @@ function HomepageHeader() {

Documentation and Tutorials for Robotics Development

diff --git a/src/theme/DocVersionBanner/index.js b/src/theme/DocVersionBanner/index.js new file mode 100644 index 00000000..a1b4d283 --- /dev/null +++ b/src/theme/DocVersionBanner/index.js @@ -0,0 +1,18 @@ +import React from 'react'; +import DocVersionBanner from '@theme-original/DocVersionBanner'; +import { useLocation } from "@docusaurus/router"; + +export default function DocVersionBannerWrapper(props) { + const { pathname } = useLocation(); + + const doesPathnameContainKey = pathname.includes("ros1noetic/robots/solutions/husky_observer"); + if (doesPathnameContainKey) { + return null; + } + + return ( + <> + + + ); +} \ No newline at end of file diff --git a/static/img/outdoornav_images/collision_avoidance_workflow.png b/static/img/outdoornav_images/collision_avoidance_workflow.png new file mode 100644 index 00000000..da7bc695 Binary files /dev/null and b/static/img/outdoornav_images/collision_avoidance_workflow.png differ diff --git a/static/img/outdoornav_images/foxglove_layout.png b/static/img/outdoornav_images/foxglove_layout.png new file mode 100644 index 00000000..8efccbe9 Binary files /dev/null and b/static/img/outdoornav_images/foxglove_layout.png differ diff --git a/static/img/outdoornav_images/scheduler_screen.png b/static/img/outdoornav_images/scheduler_screen.png new file mode 100644 index 00000000..ded7e7ce Binary files /dev/null and b/static/img/outdoornav_images/scheduler_screen.png differ diff --git a/static/img/outdoornav_images/ui_general_settings.png b/static/img/outdoornav_images/ui_general_settings.png index fd528a2d..d0a41d1e 100644 Binary files a/static/img/outdoornav_images/ui_general_settings.png and b/static/img/outdoornav_images/ui_general_settings.png differ diff --git a/static/img/outdoornav_images/ui_main_components.png b/static/img/outdoornav_images/ui_main_components.png index 882d8fc2..76ca0a69 100644 Binary files a/static/img/outdoornav_images/ui_main_components.png and b/static/img/outdoornav_images/ui_main_components.png differ diff --git a/static/img/outdoornav_images/ui_stack_lights.png b/static/img/outdoornav_images/ui_stack_lights.png new file mode 100644 index 00000000..65b21661 Binary files /dev/null and b/static/img/outdoornav_images/ui_stack_lights.png differ diff --git a/static/img/outdoornav_images/ui_wifi_cell_settings.png b/static/img/outdoornav_images/ui_wifi_cell_settings.png new file mode 100644 index 00000000..be5a5132 Binary files /dev/null and b/static/img/outdoornav_images/ui_wifi_cell_settings.png differ diff --git a/static/img/robot_images/husky_observer_images/autocharge_dock.jpg b/static/img/robot_images/husky_observer_images/autocharge_dock.jpg new file mode 100644 index 00000000..f229f941 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/autocharge_dock.jpg differ diff --git a/static/img/robot_images/husky_observer_images/automatic_motion_hazard.png b/static/img/robot_images/husky_observer_images/automatic_motion_hazard.png new file mode 100644 index 00000000..6e654e87 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/automatic_motion_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/autonomous_robot_danger.png b/static/img/robot_images/husky_observer_images/autonomous_robot_danger.png new file mode 100644 index 00000000..bd63bcb8 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/autonomous_robot_danger.png differ diff --git a/static/img/robot_images/husky_observer_images/axis_q62_limits_off.png b/static/img/robot_images/husky_observer_images/axis_q62_limits_off.png new file mode 100644 index 00000000..0f99f6b3 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/axis_q62_limits_off.png differ diff --git a/static/img/robot_images/husky_observer_images/axis_q62_login.png b/static/img/robot_images/husky_observer_images/axis_q62_login.png new file mode 100644 index 00000000..074eb502 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/axis_q62_login.png differ diff --git a/static/img/robot_images/husky_observer_images/axis_q62_set_left_limit.png b/static/img/robot_images/husky_observer_images/axis_q62_set_left_limit.png new file mode 100644 index 00000000..e1665eab Binary files /dev/null and b/static/img/robot_images/husky_observer_images/axis_q62_set_left_limit.png differ diff --git a/static/img/robot_images/husky_observer_images/axis_q62_set_right_limit.png b/static/img/robot_images/husky_observer_images/axis_q62_set_right_limit.png new file mode 100644 index 00000000..96983116 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/axis_q62_set_right_limit.png differ diff --git a/static/img/robot_images/husky_observer_images/axis_q62_settings.png b/static/img/robot_images/husky_observer_images/axis_q62_settings.png new file mode 100644 index 00000000..723a52ea Binary files /dev/null and b/static/img/robot_images/husky_observer_images/axis_q62_settings.png differ diff --git a/static/img/robot_images/husky_observer_images/axis_q62_settings_ptz.png b/static/img/robot_images/husky_observer_images/axis_q62_settings_ptz.png new file mode 100644 index 00000000..1d998492 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/axis_q62_settings_ptz.png differ diff --git a/static/img/robot_images/husky_observer_images/base_platform_power_button.jpg b/static/img/robot_images/husky_observer_images/base_platform_power_button.jpg new file mode 100644 index 00000000..5269c7a6 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/base_platform_power_button.jpg differ diff --git a/static/img/robot_images/husky_observer_images/base_screws_for_fan_maintenance.png b/static/img/robot_images/husky_observer_images/base_screws_for_fan_maintenance.png new file mode 100644 index 00000000..66124867 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/base_screws_for_fan_maintenance.png differ diff --git a/static/img/robot_images/husky_observer_images/base_station_caution.png b/static/img/robot_images/husky_observer_images/base_station_caution.png new file mode 100644 index 00000000..1fcc6ee8 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/base_station_caution.png differ diff --git a/static/img/robot_images/husky_observer_images/battery_level_warning.png b/static/img/robot_images/husky_observer_images/battery_level_warning.png new file mode 100644 index 00000000..54e0f0bb Binary files /dev/null and b/static/img/robot_images/husky_observer_images/battery_level_warning.png differ diff --git a/static/img/robot_images/husky_observer_images/cabinet_screws_for_fan_maintenance.png b/static/img/robot_images/husky_observer_images/cabinet_screws_for_fan_maintenance.png new file mode 100644 index 00000000..1dcf43d9 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/cabinet_screws_for_fan_maintenance.png differ diff --git a/static/img/robot_images/husky_observer_images/caution_awareness.png b/static/img/robot_images/husky_observer_images/caution_awareness.png new file mode 100644 index 00000000..de00d872 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/caution_awareness.png differ diff --git a/static/img/robot_images/husky_observer_images/charge_dock.png b/static/img/robot_images/husky_observer_images/charge_dock.png new file mode 100644 index 00000000..fb676905 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/charge_dock.png differ diff --git a/static/img/robot_images/husky_observer_images/charge_dock_and_robot.png b/static/img/robot_images/husky_observer_images/charge_dock_and_robot.png new file mode 100644 index 00000000..fe33f22e Binary files /dev/null and b/static/img/robot_images/husky_observer_images/charge_dock_and_robot.png differ diff --git a/static/img/robot_images/husky_observer_images/crate_warning.png b/static/img/robot_images/husky_observer_images/crate_warning.png new file mode 100644 index 00000000..82e17021 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/crate_warning.png differ diff --git a/static/img/robot_images/husky_observer_images/crushing_hazard.png b/static/img/robot_images/husky_observer_images/crushing_hazard.png new file mode 100644 index 00000000..650ffa8c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/crushing_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/disposal_warning.png b/static/img/robot_images/husky_observer_images/disposal_warning.png new file mode 100644 index 00000000..8100ca81 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/disposal_warning.png differ diff --git a/static/img/robot_images/husky_observer_images/dock_caution.png b/static/img/robot_images/husky_observer_images/dock_caution.png new file mode 100644 index 00000000..055e8b85 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/dock_caution.png differ diff --git a/static/img/robot_images/husky_observer_images/dock_space_requirements.jpg b/static/img/robot_images/husky_observer_images/dock_space_requirements.jpg new file mode 100644 index 00000000..738407cf Binary files /dev/null and b/static/img/robot_images/husky_observer_images/dock_space_requirements.jpg differ diff --git a/static/img/robot_images/husky_observer_images/dock_weight_caution.png b/static/img/robot_images/husky_observer_images/dock_weight_caution.png new file mode 100644 index 00000000..70d833b1 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/dock_weight_caution.png differ diff --git a/static/img/robot_images/husky_observer_images/electrical_shock_hazard.png b/static/img/robot_images/husky_observer_images/electrical_shock_hazard.png new file mode 100644 index 00000000..17c9c8c1 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/electrical_shock_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/entanglement_hazard.png b/static/img/robot_images/husky_observer_images/entanglement_hazard.png new file mode 100644 index 00000000..81e9cf63 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/entanglement_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/environmental_hazard.png b/static/img/robot_images/husky_observer_images/environmental_hazard.png new file mode 100644 index 00000000..9d412712 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/environmental_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/falling_object_hazard.png b/static/img/robot_images/husky_observer_images/falling_object_hazard.png new file mode 100644 index 00000000..d6caa98c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/falling_object_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/filezilla_connection_details.png b/static/img/robot_images/husky_observer_images/filezilla_connection_details.png new file mode 100644 index 00000000..f4bdb975 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/filezilla_connection_details.png differ diff --git a/static/img/robot_images/husky_observer_images/filezilla_full_view.png b/static/img/robot_images/husky_observer_images/filezilla_full_view.png new file mode 100644 index 00000000..2df3fd65 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/filezilla_full_view.png differ diff --git a/static/img/robot_images/husky_observer_images/front_wireframe_with_labels.png b/static/img/robot_images/husky_observer_images/front_wireframe_with_labels.png new file mode 100644 index 00000000..3f3074f8 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/front_wireframe_with_labels.png differ diff --git a/static/img/robot_images/husky_observer_images/getac.png b/static/img/robot_images/husky_observer_images/getac.png new file mode 100644 index 00000000..9f1513ec Binary files /dev/null and b/static/img/robot_images/husky_observer_images/getac.png differ diff --git a/static/img/robot_images/husky_observer_images/gps_danger.png b/static/img/robot_images/husky_observer_images/gps_danger.png new file mode 100644 index 00000000..71c3127c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/gps_danger.png differ diff --git a/static/img/robot_images/husky_observer_images/handling_danger.png b/static/img/robot_images/husky_observer_images/handling_danger.png new file mode 100644 index 00000000..ca570d5b Binary files /dev/null and b/static/img/robot_images/husky_observer_images/handling_danger.png differ diff --git a/static/img/robot_images/husky_observer_images/high_surface_temp_hazard.png b/static/img/robot_images/husky_observer_images/high_surface_temp_hazard.png new file mode 100644 index 00000000..da553a17 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/high_surface_temp_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/husky_observer_banner.png b/static/img/robot_images/husky_observer_images/husky_observer_banner.png new file mode 100644 index 00000000..bda64c5c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/husky_observer_banner.png differ diff --git a/static/img/robot_images/husky_observer_images/husky_observer_dimensions.png b/static/img/robot_images/husky_observer_images/husky_observer_dimensions.png new file mode 100644 index 00000000..ca8899d8 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/husky_observer_dimensions.png differ diff --git a/static/img/robot_images/husky_observer_images/impact_awareness.png b/static/img/robot_images/husky_observer_images/impact_awareness.png new file mode 100644 index 00000000..ad6bb098 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/impact_awareness.png differ diff --git a/static/img/robot_images/husky_observer_images/impact_hazard.png b/static/img/robot_images/husky_observer_images/impact_hazard.png new file mode 100644 index 00000000..2f477006 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/impact_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/laser_radiation_hazard.png b/static/img/robot_images/husky_observer_images/laser_radiation_hazard.png new file mode 100644 index 00000000..18c3d39c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/laser_radiation_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/main_power_switch.png b/static/img/robot_images/husky_observer_images/main_power_switch.png new file mode 100644 index 00000000..22a2fe5c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/main_power_switch.png differ diff --git a/static/img/robot_images/husky_observer_images/manual_load_lifting_hazard.jpg b/static/img/robot_images/husky_observer_images/manual_load_lifting_hazard.jpg new file mode 100644 index 00000000..ac2161dc Binary files /dev/null and b/static/img/robot_images/husky_observer_images/manual_load_lifting_hazard.jpg differ diff --git a/static/img/robot_images/husky_observer_images/manual_load_lifting_hazard.png b/static/img/robot_images/husky_observer_images/manual_load_lifting_hazard.png new file mode 100644 index 00000000..2ccad88a Binary files /dev/null and b/static/img/robot_images/husky_observer_images/manual_load_lifting_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/material_hazard_lithium.png b/static/img/robot_images/husky_observer_images/material_hazard_lithium.png new file mode 100644 index 00000000..3eec65bd Binary files /dev/null and b/static/img/robot_images/husky_observer_images/material_hazard_lithium.png differ diff --git a/static/img/robot_images/husky_observer_images/microhard_loadbalancer.png b/static/img/robot_images/husky_observer_images/microhard_loadbalancer.png new file mode 100644 index 00000000..a0031cb1 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/microhard_loadbalancer.png differ diff --git a/static/img/robot_images/husky_observer_images/microhard_wwan_settings.png b/static/img/robot_images/husky_observer_images/microhard_wwan_settings.png new file mode 100644 index 00000000..0251b4ca Binary files /dev/null and b/static/img/robot_images/husky_observer_images/microhard_wwan_settings.png differ diff --git a/static/img/robot_images/husky_observer_images/motion_stop_button_locations.png b/static/img/robot_images/husky_observer_images/motion_stop_button_locations.png new file mode 100644 index 00000000..92dc49f2 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/motion_stop_button_locations.png differ diff --git a/static/img/robot_images/husky_observer_images/on_off_switch.png b/static/img/robot_images/husky_observer_images/on_off_switch.png new file mode 100644 index 00000000..79cff934 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/on_off_switch.png differ diff --git a/static/img/robot_images/husky_observer_images/onav_network_base_station_mode.png b/static/img/robot_images/husky_observer_images/onav_network_base_station_mode.png new file mode 100644 index 00000000..7e497214 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/onav_network_base_station_mode.png differ diff --git a/static/img/robot_images/husky_observer_images/onav_network_cellular_only_mode.png b/static/img/robot_images/husky_observer_images/onav_network_cellular_only_mode.png new file mode 100644 index 00000000..b5928e0e Binary files /dev/null and b/static/img/robot_images/husky_observer_images/onav_network_cellular_only_mode.png differ diff --git a/static/img/robot_images/husky_observer_images/onav_network_customer_network_mode.png b/static/img/robot_images/husky_observer_images/onav_network_customer_network_mode.png new file mode 100644 index 00000000..b5cb2be1 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/onav_network_customer_network_mode.png differ diff --git a/static/img/robot_images/husky_observer_images/pinching_hazard.png b/static/img/robot_images/husky_observer_images/pinching_hazard.png new file mode 100644 index 00000000..5c88567e Binary files /dev/null and b/static/img/robot_images/husky_observer_images/pinching_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/power_distribution_terminal_blocks.png b/static/img/robot_images/husky_observer_images/power_distribution_terminal_blocks.png new file mode 100644 index 00000000..0a8725d1 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/power_distribution_terminal_blocks.png differ diff --git a/static/img/robot_images/husky_observer_images/radio_frequency_hazard.png b/static/img/robot_images/husky_observer_images/radio_frequency_hazard.png new file mode 100644 index 00000000..6c9cef51 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/radio_frequency_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/rear_wireframe_with_labels.png b/static/img/robot_images/husky_observer_images/rear_wireframe_with_labels.png new file mode 100644 index 00000000..522885ca Binary files /dev/null and b/static/img/robot_images/husky_observer_images/rear_wireframe_with_labels.png differ diff --git a/static/img/robot_images/husky_observer_images/robot_coordinate_system.png b/static/img/robot_images/husky_observer_images/robot_coordinate_system.png new file mode 100644 index 00000000..72367dd2 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/robot_coordinate_system.png differ diff --git a/static/img/robot_images/husky_observer_images/safety_information.png b/static/img/robot_images/husky_observer_images/safety_information.png new file mode 100644 index 00000000..b5369d0c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/safety_information.png differ diff --git a/static/img/robot_images/husky_observer_images/swift_console_connect.png b/static/img/robot_images/husky_observer_images/swift_console_connect.png new file mode 100644 index 00000000..c1513a7d Binary files /dev/null and b/static/img/robot_images/husky_observer_images/swift_console_connect.png differ diff --git a/static/img/robot_images/husky_observer_images/swift_console_observations.png b/static/img/robot_images/husky_observer_images/swift_console_observations.png new file mode 100644 index 00000000..fb264e7c Binary files /dev/null and b/static/img/robot_images/husky_observer_images/swift_console_observations.png differ diff --git a/static/img/robot_images/husky_observer_images/swift_console_settings_ethernet.png b/static/img/robot_images/husky_observer_images/swift_console_settings_ethernet.png new file mode 100644 index 00000000..05c20957 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/swift_console_settings_ethernet.png differ diff --git a/static/img/robot_images/husky_observer_images/swift_console_settings_ntrip.png b/static/img/robot_images/husky_observer_images/swift_console_settings_ntrip.png new file mode 100644 index 00000000..37cf6993 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/swift_console_settings_ntrip.png differ diff --git a/static/img/robot_images/husky_observer_images/teleop_danger.png b/static/img/robot_images/husky_observer_images/teleop_danger.png new file mode 100644 index 00000000..a5652baa Binary files /dev/null and b/static/img/robot_images/husky_observer_images/teleop_danger.png differ diff --git a/static/img/robot_images/husky_observer_images/tripping_hazard.png b/static/img/robot_images/husky_observer_images/tripping_hazard.png new file mode 100644 index 00000000..fed0bb65 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/tripping_hazard.png differ diff --git a/static/img/robot_images/husky_observer_images/vlp16_fov.png b/static/img/robot_images/husky_observer_images/vlp16_fov.png new file mode 100644 index 00000000..a8f55132 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/vlp16_fov.png differ diff --git a/static/img/robot_images/husky_observer_images/wireless_motion_stop_controller.png b/static/img/robot_images/husky_observer_images/wireless_motion_stop_controller.png new file mode 100644 index 00000000..476decc6 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/wireless_motion_stop_controller.png differ diff --git a/static/img/robot_images/husky_observer_images/wireless_stop_override_keyswitch.png b/static/img/robot_images/husky_observer_images/wireless_stop_override_keyswitch.png new file mode 100644 index 00000000..9c4fa6c1 Binary files /dev/null and b/static/img/robot_images/husky_observer_images/wireless_stop_override_keyswitch.png differ diff --git a/static/img/website_images/logo_black.png b/static/img/website_images/logo_black.png deleted file mode 100644 index 0feea933..00000000 Binary files a/static/img/website_images/logo_black.png and /dev/null differ diff --git a/static/img/website_images/logo_clearpath_by_rockwell_color.png b/static/img/website_images/logo_clearpath_by_rockwell_color.png new file mode 100644 index 00000000..28700499 Binary files /dev/null and b/static/img/website_images/logo_clearpath_by_rockwell_color.png differ diff --git a/static/img/website_images/logo_clearpath_by_rockwell_white.png b/static/img/website_images/logo_clearpath_by_rockwell_white.png new file mode 100644 index 00000000..dc8310ad Binary files /dev/null and b/static/img/website_images/logo_clearpath_by_rockwell_white.png differ diff --git a/static/img/website_images/logo_rockwell_pipe_clearpath_colour.png b/static/img/website_images/logo_rockwell_pipe_clearpath_colour.png new file mode 100644 index 00000000..aadd202f Binary files /dev/null and b/static/img/website_images/logo_rockwell_pipe_clearpath_colour.png differ diff --git a/static/img/website_images/logo_rockwell_pipe_clearpath_white.png b/static/img/website_images/logo_rockwell_pipe_clearpath_white.png new file mode 100644 index 00000000..a650e97f Binary files /dev/null and b/static/img/website_images/logo_rockwell_pipe_clearpath_white.png differ diff --git a/static/img/website_images/logo_white.png b/static/img/website_images/logo_white.png deleted file mode 100644 index 583c65cf..00000000 Binary files a/static/img/website_images/logo_white.png and /dev/null differ diff --git a/static/img/website_images/logo_yellow.png b/static/img/website_images/logo_yellow.png deleted file mode 100644 index 325d972a..00000000 Binary files a/static/img/website_images/logo_yellow.png and /dev/null differ diff --git a/static/img/website_images/logo_yellow_fullsize.png b/static/img/website_images/logo_yellow_fullsize.png deleted file mode 100644 index 8bb42d3e..00000000 Binary files a/static/img/website_images/logo_yellow_fullsize.png and /dev/null differ diff --git a/static/versions.js b/static/versions.js index c3f74784..62feb654 100644 --- a/static/versions.js +++ b/static/versions.js @@ -1,5 +1,5 @@ const versions = Object.freeze({ - "outdoornav": "0.8.0", + "outdoornav": "0.9.0", }); export default versions;