diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..420e14c21 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,19 @@ +# Files determined by git to be text files +# are automatically normalized to LF line endings. +* text=auto eol=lf +# The following files are explicitly set to use LF line endings. +*.mdx eol=lf +*.md eol=lf +*.json eol=lf + +# If there are files which are generated with CRLF line endings, +# it is recommended to set them to CRLF so that there is no unnecessary +# diff when regenerating them. + +# The binary macro is equivalent to the following: +# -text -diff +# Which means that line endings are not normalized and no diff is generated. +*.jpg binary +*.png binary +*.gif binary +*.mp4 binary diff --git a/CODEOWNERS b/CODEOWNERS index eb198f0ea..7a5328314 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,2 +1,2 @@ -# Default all changes will request review from: -* @rhysfaultless-cpr @jhiggins-cpr @tonybaltovski @hilary-luo +# Default all changes will request review from: +* @rhysfaultless-cpr @jhiggins-cpr @tonybaltovski @hilary-luo diff --git a/LICENSE b/LICENSE index 7efe35d00..45dbe4ed7 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,21 @@ -MIT License - -Copyright (c) 2022-2023 Clearpath Robotics Inc. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +MIT License + +Copyright (c) 2022-2023 Clearpath Robotics Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index fbeb007e4..11e4f1b65 100644 --- a/README.md +++ b/README.md @@ -63,12 +63,14 @@ 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. + If you have added a new folder and need to format all files within it you can use the `*` wildcard, for example" `npx prettier --write folder/*` + - 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 you do continue to use this entire repository 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 @@ -254,7 +256,7 @@ This helps Users know where they downloaded the file from later, as the asset is In an `img/` folder next to the markdown files where it will be used. 6. Files larger than 100 MB - + Files added to GitHub must be smaller than 100 MB—_(at time of writing in 2025-04)_. You will be able to commit a large file locally, but the push to GitHub will fail. We are storing large files in an Amazon S3 Bucket, rather than the cpr-documentation repository's `/static/assets` directory. @@ -262,13 +264,12 @@ This helps Users know where they downloaded the file from later, as the asset is To add a file: - * Sign into https://us-east-2.console.aws.amazon.com/s3/ . - * Navigate to the S3 Bucket `cpr-documentation-large-files `. - * Select the `Upload` button, and choose your local file. - * After the file has been uploaded, click on the new object, and copy its `Object URL`. + - Sign into https://us-east-2.console.aws.amazon.com/s3/ . + - Navigate to the S3 Bucket `cpr-documentation-large-files `. + - Select the `Upload` button, and choose your local file. + - After the file has been uploaded, click on the new object, and copy its `Object URL`. This is the public URL to access the file you uploaded. Note that this S3 Bucket is configured so all files' permissions are automatically set to public access. - ## How to merge branches into the Production branch? diff --git a/components/button_download.module.css b/components/button_download.module.css index 2d3bb9b22..9f81a6cfe 100644 --- a/components/button_download.module.css +++ b/components/button_download.module.css @@ -1,5 +1,5 @@ -.buttons { - display: flex; - align-items: center; - justify-content: center; +.buttons { + display: flex; + align-items: center; + justify-content: center; } \ No newline at end of file diff --git a/components/button_download_step.tsx b/components/button_download_step.tsx index ddc544a54..c9e4e9fd9 100644 --- a/components/button_download_step.tsx +++ b/components/button_download_step.tsx @@ -1,12 +1,12 @@ -import styles from "./button_download.module.css"; - -export default function ButtonStepDownload(props) { - return( -
-
- Download STEP Model Of The Robot -
-
-
- ) -} +import styles from "./button_download.module.css"; + +export default function ButtonStepDownload(props) { + return( +
+
+ Download STEP Model Of The Robot +
+
+
+ ) +} diff --git a/components/button_download_wiring_diagram.tsx b/components/button_download_wiring_diagram.tsx index 0b05622bf..180a7a609 100644 --- a/components/button_download_wiring_diagram.tsx +++ b/components/button_download_wiring_diagram.tsx @@ -1,12 +1,12 @@ -import styles from "./button_download.module.css"; - -export default function ButtonDownload(props) { - return( -
-
- Download The Robot's Wiring Diagram -
-
-
- ) -} +import styles from "./button_download.module.css"; + +export default function ButtonDownload(props) { + return( +
+
+ Download The Robot's Wiring Diagram +
+
+
+ ) +} diff --git a/components/common_lighting_states_estop_reset_operational.mdx b/components/common_lighting_states_estop_reset_operational.mdx index 98d7353ba..d0088a54f 100644 --- a/components/common_lighting_states_estop_reset_operational.mdx +++ b/components/common_lighting_states_estop_reset_operational.mdx @@ -1,9 +1,9 @@ -
-
- | Lighting State | Lighting Pattern | - | :----------------------------------- | :--------------------------------------------------------------------------------------: | - | Emergency Stop | | - | Needs Reset _(after Emergency Stop)_ | | - | Operational _(Driving or Idle)_ | | -
-
+
+
+ | Lighting State | Lighting Pattern | + | :----------------------------------- | :--------------------------------------------------------------------------------------: | + | Emergency Stop | | + | Needs Reset _(after Emergency Stop)_ | | + | Operational _(Driving or Idle)_ | | +
+
diff --git a/components/common_risk_assessment_for_integrations.mdx b/components/common_risk_assessment_for_integrations.mdx index f074e3e92..f1d877dab 100644 --- a/components/common_risk_assessment_for_integrations.mdx +++ b/components/common_risk_assessment_for_integrations.mdx @@ -1,9 +1,9 @@ -:::safety-danger - -**Always perform a risk assessment prior to any custom integrations.** - -Custom integrations are outside the scope of the robot's safety assessment, as custom integrations may result in new hazards. - -::: - -
+:::safety-danger + +**Always perform a risk assessment prior to any custom integrations.** + +Custom integrations are outside the scope of the robot's safety assessment, as custom integrations may result in new hazards. + +::: + +
diff --git a/components/common_who_can_maintain_the_robot.mdx b/components/common_who_can_maintain_the_robot.mdx index d839be9a2..01e7aec84 100644 --- a/components/common_who_can_maintain_the_robot.mdx +++ b/components/common_who_can_maintain_the_robot.mdx @@ -1,13 +1,13 @@ -:::safety-danger - -Maintaining robots can be dangerous. -There are hazards from high energy batteries, sharp edges, joints that can shear, and heavy items that can crush. -The robot is intended to be maintained by a technician that is familiar with safe work procedures, and has experience using the required tools. - -Technicians must read and understand this manual. - -Technicians must review and understand their worksite's Risk Assessment and required procedures. - -Contact our [Support Team](#support) if you have any questions. - -::: +:::safety-danger + +Maintaining robots can be dangerous. +There are hazards from high energy batteries, sharp edges, joints that can shear, and heavy items that can crush. +The robot is intended to be maintained by a technician that is familiar with safe work procedures, and has experience using the required tools. + +Technicians must read and understand this manual. + +Technicians must review and understand their worksite's Risk Assessment and required procedures. + +Contact our [Support Team](#support) if you have any questions. + +::: diff --git a/components/common_wireless_emergency_stop_charging.mdx b/components/common_wireless_emergency_stop_charging.mdx index fe15932de..76a389309 100644 --- a/components/common_wireless_emergency_stop_charging.mdx +++ b/components/common_wireless_emergency_stop_charging.mdx @@ -1,41 +1,41 @@ -### Charging The Wireless Emergency Stop Transmitter - -This transmitter is part of the _Wireless Emergency Stop_ upgrade kit for Husky. - -1. Remove the battery from the _Wireless Emergency Stop Transmitter_. -2. Connect the charger's AC cable to an outlet at your worksite. -3. Connect the transmitter's battery to the charger. - -
-
- - -
Wirelesss Emergency Stop Transmitter's Charger
-
-
- -
-
- - -
Removing the Wirelesss Emergency Stop Transmitter's Battery
-
-
- -:::info - -The robot's spare parts kit included a second battery for the transmitter. - -::: +### Charging The Wireless Emergency Stop Transmitter + +This transmitter is part of the _Wireless Emergency Stop_ upgrade kit for Husky. + +1. Remove the battery from the _Wireless Emergency Stop Transmitter_. +2. Connect the charger's AC cable to an outlet at your worksite. +3. Connect the transmitter's battery to the charger. + +
+
+ + +
Wirelesss Emergency Stop Transmitter's Charger
+
+
+ +
+
+ + +
Removing the Wirelesss Emergency Stop Transmitter's Battery
+
+
+ +:::info + +The robot's spare parts kit included a second battery for the transmitter. + +::: diff --git a/components/common_wireless_joystick_ps4.mdx b/components/common_wireless_joystick_ps4.mdx index 358baa741..eed2fa404 100644 --- a/components/common_wireless_joystick_ps4.mdx +++ b/components/common_wireless_joystick_ps4.mdx @@ -1,45 +1,45 @@ -### Connecting And Using The Wireless Joystick {#controller} - -Your robot included a PS4 wireless joystick. -Clearpath's robot builders paired this wireless joystick with your robot computer's Bluetooth. -This means the joystick should always connect to that robot, even if there are other robots nearby. - -To connect the joystick to your robot: - -1. Turn on the robot, and wait till the status lights show that ROS is running. -2. Have the controller within 5 metres of the robot. -3. Press the _PS_ button in the centre of the joystick. -4. The joystick's top LED should start pulsing white or blue. - This means the joystick is attempting to connect. -5. The joysick's top LED should eventually become solid blue, indicating that it has connected to the robot's computer. - - -
-
- -
PS4 Wireless Joystick
-
-
- -:::danger Failing To Connect - -The _Wireless Joystick_ is not connected if its LED does not become solid blue. -Follow the instructions in the [Joystick Controller Pairing](/docs/ros/installation/controller) section to pair the joystick to your robot's primary computer. - -::: - -:::info Driving The Robot - -1. Make sure your worksite is ready to drive the robot, and that the robot will not create hazards for people, animals, or your infrastructure. -2. Make sure the robot's status lights show that it is ready to drive. -3. Make sure the _Wireless Joystick_ is connected to the robot. -4. Hold the joystick's _L1 button_ for slow driving. - _(You can use the R1 button for fast driving once you are comfortable with the robot's dynamics.)_ -5. Use the left joystick to drive the robot. - Pushing the joystick forward and backward will command the robot ±X. - Angling the joystick left and right will command the robot to rotate ±Z. - -::: +### Connecting And Using The Wireless Joystick {#controller} + +Your robot included a PS4 wireless joystick. +Clearpath's robot builders paired this wireless joystick with your robot computer's Bluetooth. +This means the joystick should always connect to that robot, even if there are other robots nearby. + +To connect the joystick to your robot: + +1. Turn on the robot, and wait till the status lights show that ROS is running. +2. Have the controller within 5 metres of the robot. +3. Press the _PS_ button in the centre of the joystick. +4. The joystick's top LED should start pulsing white or blue. + This means the joystick is attempting to connect. +5. The joysick's top LED should eventually become solid blue, indicating that it has connected to the robot's computer. + + +
+
+ +
PS4 Wireless Joystick
+
+
+ +:::danger Failing To Connect + +The _Wireless Joystick_ is not connected if its LED does not become solid blue. +Follow the instructions in the [Joystick Controller Pairing](/docs/ros/installation/controller) section to pair the joystick to your robot's primary computer. + +::: + +:::info Driving The Robot + +1. Make sure your worksite is ready to drive the robot, and that the robot will not create hazards for people, animals, or your infrastructure. +2. Make sure the robot's status lights show that it is ready to drive. +3. Make sure the _Wireless Joystick_ is connected to the robot. +4. Hold the joystick's _L1 button_ for slow driving. + _(You can use the R1 button for fast driving once you are comfortable with the robot's dynamics.)_ +5. Use the left joystick to drive the robot. + Pushing the joystick forward and backward will command the robot ±X. + Angling the joystick left and right will command the robot to rotate ±Z. + +::: diff --git a/components/common_wireless_joystick_ps4_charging.mdx b/components/common_wireless_joystick_ps4_charging.mdx index af87298ad..76744e15f 100644 --- a/components/common_wireless_joystick_ps4_charging.mdx +++ b/components/common_wireless_joystick_ps4_charging.mdx @@ -1,21 +1,21 @@ -### Charging The Wireless Joystick - -There is a micro-USB port on the top of the PS4 controller—near its LED. -A USB cable was included in your robot's spare parts kit. -Connect the controller to a computer, USB hub, or other 5 V USB charger. -The controller's LED should glow yellow when it starts charging. - -
-
- -
-
- -:::info - -The _Wireless Joystick_ will not send driving commands to the robot while the joystick is charging. - -::: +### Charging The Wireless Joystick + +There is a micro-USB port on the top of the PS4 controller—near its LED. +A USB cable was included in your robot's spare parts kit. +Connect the controller to a computer, USB hub, or other 5 V USB charger. +The controller's LED should glow yellow when it starts charging. + +
+
+ +
+
+ +:::info + +The _Wireless Joystick_ will not send driving commands to the robot while the joystick is charging. + +::: diff --git a/components/husky_a300/husky_a300_additional_emergency_stop_devices.mdx b/components/husky_a300/husky_a300_additional_emergency_stop_devices.mdx index 8586a437b..39b2f5527 100644 --- a/components/husky_a300/husky_a300_additional_emergency_stop_devices.mdx +++ b/components/husky_a300/husky_a300_additional_emergency_stop_devices.mdx @@ -1,36 +1,36 @@ -import Admonition from "@theme/Admonition"; - -### Additional Emergency Stop Devices {#husky_external_stop} - -[//]: <> (TODO, add image of the 8 ES positions on the System Interface circuit board) - -The base Husky A300 includes 2 Emergency Stop Buttons, which are connected to the System Interface circuit board. -The System Interface circuit board also includes connector breakouts for 6 more Emergency Stop devices, labelled ES3 through ES8. -The standard Husky A300 has a bypass jumper inserted into each of these unused Emergency Stop breakouts. - -[//]: <> (TODO, add image of a bypass jumper) - -You can use these Emergency Stop breakouts to add more Emergency Stop devices, such as: - -- Emergency Stop buttons -- Safety lidar -- Tape switches -- Limit switches -- Relays or similar PLC components -- Manipulator control cabinets - -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - The Husky AMP and Husky Observer use 2 of these additional breakouts to connect more Emergency Stop buttons. - We discard 2 of the bypass jumpers, and then connect the new Emergency Stop buttons to the System Interface circuit board. -} - - - - | ES Pin | Function / Value | - | :----- | :--------------------------------------------------------------------------------------------------- | - | 1 | Channel 1 Out, _(24 V)_: normally connected to Channel 1 In; disconnect to trigger an emergency stop | - | 2 | Channel 1 In | - | 3 | Channel 2 Out _(24 V)_: normally connected to Channel 2 In; disconnect to trigger an emergency stop | - | 4 | Channel 2 In | - - +import Admonition from "@theme/Admonition"; + +### Additional Emergency Stop Devices {#husky_external_stop} + +[//]: <> (TODO, add image of the 8 ES positions on the System Interface circuit board) + +The base Husky A300 includes 2 Emergency Stop Buttons, which are connected to the System Interface circuit board. +The System Interface circuit board also includes connector breakouts for 6 more Emergency Stop devices, labelled ES3 through ES8. +The standard Husky A300 has a bypass jumper inserted into each of these unused Emergency Stop breakouts. + +[//]: <> (TODO, add image of a bypass jumper) + +You can use these Emergency Stop breakouts to add more Emergency Stop devices, such as: + +- Emergency Stop buttons +- Safety lidar +- Tape switches +- Limit switches +- Relays or similar PLC components +- Manipulator control cabinets + +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + The Husky AMP and Husky Observer use 2 of these additional breakouts to connect more Emergency Stop buttons. + We discard 2 of the bypass jumpers, and then connect the new Emergency Stop buttons to the System Interface circuit board. +} + + + + | ES Pin | Function / Value | + | :----- | :--------------------------------------------------------------------------------------------------- | + | 1 | Channel 1 Out, _(24 V)_: normally connected to Channel 1 In; disconnect to trigger an emergency stop | + | 2 | Channel 1 In | + | 3 | Channel 2 Out _(24 V)_: normally connected to Channel 2 In; disconnect to trigger an emergency stop | + | 4 | Channel 2 In | + + diff --git a/components/husky_a300/husky_a300_amp_check_sensors.mdx b/components/husky_a300/husky_a300_amp_check_sensors.mdx index de29366bd..ddbce4a23 100644 --- a/components/husky_a300/husky_a300_amp_check_sensors.mdx +++ b/components/husky_a300/husky_a300_amp_check_sensors.mdx @@ -1,24 +1,24 @@ -### Check That Sensors Are Functional - -Husky AMP includes several sensors that are used for robot navigation. After connecting -to Husky AMP's network, confirm that each sensor is functional by using the steps below. - -1. Connect to your laptop to the robot using SSH. To do so, execute the following in a terminal window: - ``` - ssh robot@192.168.131.1 - ``` - You will be prompted to enter a password. The default password is `clearpath`. -1. Use the `ping` command to check that each of the [sensors](#ip-addresses) is functional. - For example, to confirm that the front teleop camera (`192.168.131.15`) is working: - ``` - $ ping 192.168.131.15 - PING 192.168.131.15 (192.168.131.2) 56(84) bytes of data. - 64 bytes from 192.168.131.15: icmp_seq=1 ttl=255 time=0.265 ms - 64 bytes from 192.168.131.15: icmp_seq=2 ttl=255 time=0.213 ms - 64 bytes from 192.168.131.15: icmp_seq=3 ttl=255 time=0.282 ms - 64 bytes from 192.168.131.15: icmp_seq=4 ttl=255 time=0.216 ms - ^C - --- 192.168.131.15 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3100ms - rtt min/avg/max/mdev = 0.213/0.244/0.282/0.030 ms - ``` +### Check That Sensors Are Functional + +Husky AMP includes several sensors that are used for robot navigation. After connecting +to Husky AMP's network, confirm that each sensor is functional by using the steps below. + +1. Connect to your laptop to the robot using SSH. To do so, execute the following in a terminal window: + ``` + ssh robot@192.168.131.1 + ``` + You will be prompted to enter a password. The default password is `clearpath`. +1. Use the `ping` command to check that each of the [sensors](#ip-addresses) is functional. + For example, to confirm that the front teleop camera (`192.168.131.15`) is working: + ``` + $ ping 192.168.131.15 + PING 192.168.131.15 (192.168.131.2) 56(84) bytes of data. + 64 bytes from 192.168.131.15: icmp_seq=1 ttl=255 time=0.265 ms + 64 bytes from 192.168.131.15: icmp_seq=2 ttl=255 time=0.213 ms + 64 bytes from 192.168.131.15: icmp_seq=3 ttl=255 time=0.282 ms + 64 bytes from 192.168.131.15: icmp_seq=4 ttl=255 time=0.216 ms + ^C + --- 192.168.131.15 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3100ms + rtt min/avg/max/mdev = 0.213/0.244/0.282/0.030 ms + ``` diff --git a/components/husky_a300/husky_a300_amp_networking_basic.mdx b/components/husky_a300/husky_a300_amp_networking_basic.mdx index f9c96c918..68a397e8d 100644 --- a/components/husky_a300/husky_a300_amp_networking_basic.mdx +++ b/components/husky_a300/husky_a300_amp_networking_basic.mdx @@ -1,19 +1,19 @@ -import Admonition from "@theme/Admonition"; - -### Connecting To Husky AMP's Network {#basic-network-connection} - -To access additional Husky AMP functionality, a network connection to the robot is required. -The easiest way to accomplish this is to connect your laptop to Husky AMP's Wi-Fi -access point using the steps below. - -1. Use your laptop to find and to connect to Husky AMP's Wi-Fi network. The Wi-Fi network name (SSID) will be - `cpr_a300_amp_XXXXX`, where `XXXXX` matches the serial number of the Husky AMP. When - prompted, use the password `clearpath`. - -1. Confirm that your laptop's Wi-Fi network interface is configured to use DHCP and that it - has been assigned an IP address in the `192.168.131.XXX` range. - - - Refer to Robot Network Connection for alternative networking connections. - - +import Admonition from "@theme/Admonition"; + +### Connecting To Husky AMP's Network {#basic-network-connection} + +To access additional Husky AMP functionality, a network connection to the robot is required. +The easiest way to accomplish this is to connect your laptop to Husky AMP's Wi-Fi +access point using the steps below. + +1. Use your laptop to find and to connect to Husky AMP's Wi-Fi network. The Wi-Fi network name (SSID) will be + `cpr_a300_amp_XXXXX`, where `XXXXX` matches the serial number of the Husky AMP. When + prompted, use the password `clearpath`. + +1. Confirm that your laptop's Wi-Fi network interface is configured to use DHCP and that it + has been assigned an IP address in the `192.168.131.XXX` range. + + + Refer to Robot Network Connection for alternative networking connections. + + diff --git a/components/husky_a300/husky_a300_amp_other_documentation_to_review.mdx b/components/husky_a300/husky_a300_amp_other_documentation_to_review.mdx index 56daa111d..303476b6b 100644 --- a/components/husky_a300/husky_a300_amp_other_documentation_to_review.mdx +++ b/components/husky_a300/husky_a300_amp_other_documentation_to_review.mdx @@ -1,5 +1,5 @@ -### Other Documentation To Review - -Refer to our [OutdoorNav software's documentation](/docs_outdoornav_user_manual), as this comes included with Husky AMP and Husky Observer. -OutdoorNav allows you to send your Husky on autonomous missions using the included ROS API, or by using OutdoorNav's web user interface. -OutdoorNav can accomplish these autonomous missions using the Husky AMP's sensors, without making infrastructure updates to your worksite. +### Other Documentation To Review + +Refer to our [OutdoorNav software's documentation](/docs_outdoornav_user_manual), as this comes included with Husky AMP and Husky Observer. +OutdoorNav allows you to send your Husky on autonomous missions using the included ROS API, or by using OutdoorNav's web user interface. +OutdoorNav can accomplish these autonomous missions using the Husky AMP's sensors, without making infrastructure updates to your worksite. diff --git a/components/husky_a300/husky_a300_amp_outdoornav_checks.mdx b/components/husky_a300/husky_a300_amp_outdoornav_checks.mdx index 337ff026e..b95bf8856 100644 --- a/components/husky_a300/husky_a300_amp_outdoornav_checks.mdx +++ b/components/husky_a300/husky_a300_amp_outdoornav_checks.mdx @@ -1,16 +1,16 @@ -### Confirming That OutdoorNav Software Is Functioning - -Husky AMP includes OutdoorNav Software, which allows the robot to be operated autonomously. -Follow the steps below to confirm that OutdoorNav Software is functioning. - -1. [Connect to Web UI](/docs_outdoornav_user_manual/quick_start#connecting_to_web_ui) -1. [Check camera views](/docs_outdoornav_user_manual/quick_start#checking-camera-feeds) -1. [Check system status](/docs_outdoornav_user_manual/quick_start#checking-system-status) -1. [Check GPS RTK fix](/docs_outdoornav_user_manual/quick_start#checking-gpt-rtk-fix) -1. Complete system configuration: - 1. [Load map tiles](/docs_outdoornav_user_manual/quick_start#loading_map_tiles) - 1. [Set dock location](/docs_outdoornav_user_manual/quick_start#set-dock-location), if a dock is included with your system -1. [Create your first map](/docs_outdoornav_user_manual/quick_start#create-your-first-map) -1. [Create your first mission](/docs_outdoornav_user_manual/quick_start#create-your-first-mission) -1. [Execute your first mission](/docs_outdoornav_user_manual/quick_start#execute-your-first-mission) - +### Confirming That OutdoorNav Software Is Functioning + +Husky AMP includes OutdoorNav Software, which allows the robot to be operated autonomously. +Follow the steps below to confirm that OutdoorNav Software is functioning. + +1. [Connect to Web UI](/docs_outdoornav_user_manual/quick_start#connecting_to_web_ui) +1. [Check camera views](/docs_outdoornav_user_manual/quick_start#checking-camera-feeds) +1. [Check system status](/docs_outdoornav_user_manual/quick_start#checking-system-status) +1. [Check GPS RTK fix](/docs_outdoornav_user_manual/quick_start#checking-gpt-rtk-fix) +1. Complete system configuration: + 1. [Load map tiles](/docs_outdoornav_user_manual/quick_start#loading_map_tiles) + 1. [Set dock location](/docs_outdoornav_user_manual/quick_start#set-dock-location), if a dock is included with your system +1. [Create your first map](/docs_outdoornav_user_manual/quick_start#create-your-first-map) +1. [Create your first mission](/docs_outdoornav_user_manual/quick_start#create-your-first-mission) +1. [Execute your first mission](/docs_outdoornav_user_manual/quick_start#execute-your-first-mission) + diff --git a/components/husky_a300/husky_a300_base_link.mdx b/components/husky_a300/husky_a300_base_link.mdx index 80abc1ae1..2548c9fc0 100644 --- a/components/husky_a300/husky_a300_base_link.mdx +++ b/components/husky_a300/husky_a300_base_link.mdx @@ -1,21 +1,21 @@ -### base_link - -`base_link` is the primary coordinate system for the robot. -All sensors, manipulators, and brackets are positioned with reference to `base link`. -[This ROS 2 Documentation page](https://docs.ros.org/en/jazzy/Tutorials/Intermediate/URDF/Building-a-Visual-Robot-Model-with-URDF-from-Scratch.html) explains how a robot's model is constructed. - -Husky's model is included on the robot, and is available on our public GitHub. -Husky's `base_link` is located on the bottom of the chassis, with +X pointed toward the front panel, and +Y toward the robot's left side. - -
- -
- -:::info - -The [STEP Model](#step-model)'s origin is aligned with `base_link`. - -::: +### base_link + +`base_link` is the primary coordinate system for the robot. +All sensors, manipulators, and brackets are positioned with reference to `base link`. +[This ROS 2 Documentation page](https://docs.ros.org/en/jazzy/Tutorials/Intermediate/URDF/Building-a-Visual-Robot-Model-with-URDF-from-Scratch.html) explains how a robot's model is constructed. + +Husky's model is included on the robot, and is available on our public GitHub. +Husky's `base_link` is located on the bottom of the chassis, with +X pointed toward the front panel, and +Y toward the robot's left side. + +
+ +
+ +:::info + +The [STEP Model](#step-model)'s origin is aligned with `base_link`. + +::: diff --git a/components/husky_a300/husky_a300_cable_passthrough.mdx b/components/husky_a300/husky_a300_cable_passthrough.mdx index 4aa919a04..94b2dea6d 100644 --- a/components/husky_a300/husky_a300_cable_passthrough.mdx +++ b/components/husky_a300/husky_a300_cable_passthrough.mdx @@ -1,80 +1,80 @@ -### Cable Passthrough {#cable-passthrough} - -To maintain Husky's IP54 rating while allowing cables to pass between the external kits and internal electronics, - Husky's top plate is provisioned with expansion plates for cable IP rated cable systems. -There are three expansion plates at the front, and three at the rear of the top plate. - -
-
- -
Top plate electrical expansion
-
-
- -Technicians have two main options. - -1. Drill holes in the expansion plates and add appropriate IP-rated sealing solutions on a cable-by-cable basis. -2. Remove an expansion plate and replace it with a cable entry system, such as Icotek. - -
-
- -
Options, from left to right: hole with a connector, Icotek straight housing, Icotek 90° housing
-
-
- - -#### Using the Icotek Cable Entry System - -The [Icotek Cable Entry System](https://www.icotek.com/en/products/cable-entry-systems) allows pre-terminated cables up to 65 mm in diameter to be routed into Husky A300, - and be sealed with up to IP66 rated ingress protection. -In addition, the cable entry frames serve as strain relief on the cable. - -This cable system is based on a set of cable entry frames and grommets. -Refer to the [demonstration video](https://www.youtube.com/watch?v=BQpOG0ptltE) for an overview of using the system. - -
- Supported cable entry frames: - - | Clearpath Item | Description | Manufacturer Item | - | :------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | 031161 | Blank Plate | | - | 032256 | Gasket | | - | 031682 | Straight Icotek Housing | | - | 032777 | 90° Icotek Housing Kit | | - | 028997 | 360° Icotek Housing Kit | | -
- -
- Supported grommets: - - Grommets are selected based on the size of the cable being passed through. - A list of the most common grommets are listed in the table below. - Also review [Icotek's full grommets catalog](https://www.icotek.com/en/products/cable-grommets/kt-bk). - - | Part Number | Part Description | CPR Item Number | Retailer Link | - | :----------------------------- | :------------------------------------- | :---------------- | :------------------------------------------------------------------- | - | Blank BK
(41351) | Blank grommet | 031393 | [RS-Online](https://ca.rs-online.com/product/icotek/41351/72428519/) | - | KT 1 BK
(39943) | 1X Split grommet for 1 - 2 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/39943/72428434/) | - | KT 2 BK
(41302) | 1X Split grommet for 2 - 3 mm cable | 032027 | [RS-Online](https://ca.rs-online.com/product/icotek/41302/72428490/) | - | KT 3 BK
(41303) | 1X Split grommet for 3 - 4 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41303/72428491/) | - | KT 4 BK
(41304) | 1X Split grommet for 4 - 5 mm cable | 032536 | [RS-Online](https://ca.rs-online.com/product/icotek/41304/72428492/) | - | KT 5 BK
(41305) | 1X Split grommet for 5 - 6 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41305/72428493/) | - | KT 6 BK
(41306) | 1X Split grommet for 6 - 7 mm cable | 031394 | [RS-Online](https://ca.rs-online.com/product/icotek/41306/72428494/) | - | KT 7 BK
(41307) | 1X Split grommet for 7 - 8 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41307/72428495/) | - | KT 8 BK
(41308) | 1X Split grommet for 8 - 9 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41308/72428496/) | - | KT 9 BK
(41309) | 1X Split grommet for 9 - 10 mm cable | 031395 | [RS-Online](https://ca.rs-online.com/product/icotek/41309/72428497/) | - | KT 10 BK
(41310) | 1X Split grommet for 10 - 11 mm cable | 032535 | [RS-Online](https://ca.rs-online.com/product/icotek/41310/72428498/) | - | KT 11 BK
(41311) | 1X Split grommet for 11 - 12 mm cable | 031396 | [RS-Online](https://ca.rs-online.com/product/icotek/41311/72428499/) | - | KT 2/6 BK
(39905) | 2X Split grommet for 6 - 7 mm cable | 028994 | [RS-Online](https://ca.rs-online.com/product/icotek/39905/72428402/) | - | KT 2/7 BK
(39916) | 2X Split grommet for 7 - 8 mm cable | 031398 | [RS-Online](https://ca.rs-online.com/product/icotek/39916/72428413/) | - | KT 2/8 BK
(39918) | 2X Split grommet for 8 - 9 mm cable | 032028 | [RS-Online](https://ca.rs-online.com/product/icotek/39918/72428415/) | - | KT 4/5 BK
(39910) | 4X Split grommet for 5 - 6 mm cable | 031399 | [RS-Online](https://ca.rs-online.com/product/icotek/39910/72428407/) | - | KT 4/6 BK
(39933) | 4X Split grommet for 6 - 7 mm cable | 031400 | [RS-Online](https://ca.rs-online.com/product/icotek/39933/72428424/) | -
+### Cable Passthrough {#cable-passthrough} + +To maintain Husky's IP54 rating while allowing cables to pass between the external kits and internal electronics, + Husky's top plate is provisioned with expansion plates for cable IP rated cable systems. +There are three expansion plates at the front, and three at the rear of the top plate. + +
+
+ +
Top plate electrical expansion
+
+
+ +Technicians have two main options. + +1. Drill holes in the expansion plates and add appropriate IP-rated sealing solutions on a cable-by-cable basis. +2. Remove an expansion plate and replace it with a cable entry system, such as Icotek. + +
+
+ +
Options, from left to right: hole with a connector, Icotek straight housing, Icotek 90° housing
+
+
+ + +#### Using the Icotek Cable Entry System + +The [Icotek Cable Entry System](https://www.icotek.com/en/products/cable-entry-systems) allows pre-terminated cables up to 65 mm in diameter to be routed into Husky A300, + and be sealed with up to IP66 rated ingress protection. +In addition, the cable entry frames serve as strain relief on the cable. + +This cable system is based on a set of cable entry frames and grommets. +Refer to the [demonstration video](https://www.youtube.com/watch?v=BQpOG0ptltE) for an overview of using the system. + +
+ Supported cable entry frames: + + | Clearpath Item | Description | Manufacturer Item | + | :------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | 031161 | Blank Plate | | + | 032256 | Gasket | | + | 031682 | Straight Icotek Housing | | + | 032777 | 90° Icotek Housing Kit | | + | 028997 | 360° Icotek Housing Kit | | +
+ +
+ Supported grommets: + + Grommets are selected based on the size of the cable being passed through. + A list of the most common grommets are listed in the table below. + Also review [Icotek's full grommets catalog](https://www.icotek.com/en/products/cable-grommets/kt-bk). + + | Part Number | Part Description | CPR Item Number | Retailer Link | + | :----------------------------- | :------------------------------------- | :---------------- | :------------------------------------------------------------------- | + | Blank BK
(41351) | Blank grommet | 031393 | [RS-Online](https://ca.rs-online.com/product/icotek/41351/72428519/) | + | KT 1 BK
(39943) | 1X Split grommet for 1 - 2 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/39943/72428434/) | + | KT 2 BK
(41302) | 1X Split grommet for 2 - 3 mm cable | 032027 | [RS-Online](https://ca.rs-online.com/product/icotek/41302/72428490/) | + | KT 3 BK
(41303) | 1X Split grommet for 3 - 4 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41303/72428491/) | + | KT 4 BK
(41304) | 1X Split grommet for 4 - 5 mm cable | 032536 | [RS-Online](https://ca.rs-online.com/product/icotek/41304/72428492/) | + | KT 5 BK
(41305) | 1X Split grommet for 5 - 6 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41305/72428493/) | + | KT 6 BK
(41306) | 1X Split grommet for 6 - 7 mm cable | 031394 | [RS-Online](https://ca.rs-online.com/product/icotek/41306/72428494/) | + | KT 7 BK
(41307) | 1X Split grommet for 7 - 8 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41307/72428495/) | + | KT 8 BK
(41308) | 1X Split grommet for 8 - 9 mm cable | N/A | [RS-Online](https://ca.rs-online.com/product/icotek/41308/72428496/) | + | KT 9 BK
(41309) | 1X Split grommet for 9 - 10 mm cable | 031395 | [RS-Online](https://ca.rs-online.com/product/icotek/41309/72428497/) | + | KT 10 BK
(41310) | 1X Split grommet for 10 - 11 mm cable | 032535 | [RS-Online](https://ca.rs-online.com/product/icotek/41310/72428498/) | + | KT 11 BK
(41311) | 1X Split grommet for 11 - 12 mm cable | 031396 | [RS-Online](https://ca.rs-online.com/product/icotek/41311/72428499/) | + | KT 2/6 BK
(39905) | 2X Split grommet for 6 - 7 mm cable | 028994 | [RS-Online](https://ca.rs-online.com/product/icotek/39905/72428402/) | + | KT 2/7 BK
(39916) | 2X Split grommet for 7 - 8 mm cable | 031398 | [RS-Online](https://ca.rs-online.com/product/icotek/39916/72428413/) | + | KT 2/8 BK
(39918) | 2X Split grommet for 8 - 9 mm cable | 032028 | [RS-Online](https://ca.rs-online.com/product/icotek/39918/72428415/) | + | KT 4/5 BK
(39910) | 4X Split grommet for 5 - 6 mm cable | 031399 | [RS-Online](https://ca.rs-online.com/product/icotek/39910/72428407/) | + | KT 4/6 BK
(39933) | 4X Split grommet for 6 - 7 mm cable | 031400 | [RS-Online](https://ca.rs-online.com/product/icotek/39933/72428424/) | +
diff --git a/components/husky_a300/husky_a300_canbus.mdx b/components/husky_a300/husky_a300_canbus.mdx index c83bf572a..1aa1a006e 100644 --- a/components/husky_a300/husky_a300_canbus.mdx +++ b/components/husky_a300/husky_a300_canbus.mdx @@ -1,19 +1,19 @@ -### CANbus Connection - -Husky has up to 3 standard CAN networks: - -| Network name | Data Rate | Purpose | Devices | -| :-------------- | :---------- | :------------------------ | :------------------------------------------------------------------------------ | -| `vcan0` | 1000 kBit/s | Motor Control | Primary Computer, MCU, 4 Motor Controllers | -| `vcan1` | 250 kBit/s | Batteries | Primary Computer, MCU, Batteries _(up to 6 batteries)_, Wireless Emergency Stop | -| `usbcan0` | 250 kBit/s | Optional Wireless Charger | Primary Computer, Wireless Charger | - -:::info - -We suggest you add custom CAN devices to a new network, using a USB-CAN adapter such as a PEAK System PCAN-USB. -You would need to name the new network something different than the 3 networks listed above. -We configure these networks using SocketCAN. - -It is possible to add new devices to the Husky's existing networks, but this requires significant testing time. - -::: +### CANbus Connection + +Husky has up to 3 standard CAN networks: + +| Network name | Data Rate | Purpose | Devices | +| :-------------- | :---------- | :------------------------ | :------------------------------------------------------------------------------ | +| `vcan0` | 1000 kBit/s | Motor Control | Primary Computer, MCU, 4 Motor Controllers | +| `vcan1` | 250 kBit/s | Batteries | Primary Computer, MCU, Batteries _(up to 6 batteries)_, Wireless Emergency Stop | +| `usbcan0` | 250 kBit/s | Optional Wireless Charger | Primary Computer, Wireless Charger | + +:::info + +We suggest you add custom CAN devices to a new network, using a USB-CAN adapter such as a PEAK System PCAN-USB. +You would need to name the new network something different than the 3 networks listed above. +We configure these networks using SocketCAN. + +It is possible to add new devices to the Husky's existing networks, but this requires significant testing time. + +::: diff --git a/components/husky_a300/husky_a300_data_connections.mdx b/components/husky_a300/husky_a300_data_connections.mdx index 43da26abb..fee3b6168 100644 --- a/components/husky_a300/husky_a300_data_connections.mdx +++ b/components/husky_a300/husky_a300_data_connections.mdx @@ -1,14 +1,14 @@ -### Data Connections - -:::note - -These are our suggested methods for connecting sensors and actuators to Husky. - -::: - -| Data Bus | Clearpath's suggestion for connecting devices to the Husky's computer: | -| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | -| USB | Direct connection to the robot's computer, or add a USB hub. | -| Ethernet | Connect to the robot's 2.5 Gbit/s Ethernet Switch, which is inside the chassis. | -| Serial RS-232, RS-422, RS-485 | Add a USB converter, such as a FTDI cable. Most computers have Serial ports, but these take more time to configure than a FTDI cable. | -| CAN | Add a USB converter, such as a PEAK System PCAN-USB. +### Data Connections + +:::note + +These are our suggested methods for connecting sensors and actuators to Husky. + +::: + +| Data Bus | Clearpath's suggestion for connecting devices to the Husky's computer: | +| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | +| USB | Direct connection to the robot's computer, or add a USB hub. | +| Ethernet | Connect to the robot's 2.5 Gbit/s Ethernet Switch, which is inside the chassis. | +| Serial RS-232, RS-422, RS-485 | Add a USB converter, such as a FTDI cable. Most computers have Serial ports, but these take more time to configure than a FTDI cable. | +| CAN | Add a USB converter, such as a PEAK System PCAN-USB. diff --git a/components/husky_a300/husky_a300_emergency_stop_clearing.mdx b/components/husky_a300/husky_a300_emergency_stop_clearing.mdx index ba65da926..04af70154 100644 --- a/components/husky_a300/husky_a300_emergency_stop_clearing.mdx +++ b/components/husky_a300/husky_a300_emergency_stop_clearing.mdx @@ -29,4 +29,5 @@ This state is common for machinery safety; as it waits for the machine operator #### To Clear The Needs Reset State: {#clear-needs-reset} 1. Press the _Emergency Stop Restart Button_ on at the back of the Husky. -2. Or, if included, connect your Wireless Emergency Stop remote. +2. Alternatively, it can be clearing by running `ros2 service call /a300_00000/platform/mcu/clear_estop_needs_reset std_srvs/srv/Empty "{}"` on the Husky's computer. +3. Or, if included, connect your Wireless Emergency Stop remote. diff --git a/components/husky_a300/husky_a300_fan_expansion.mdx b/components/husky_a300/husky_a300_fan_expansion.mdx index a9f3b2400..fddbe47c7 100644 --- a/components/husky_a300/husky_a300_fan_expansion.mdx +++ b/components/husky_a300/husky_a300_fan_expansion.mdx @@ -1,35 +1,35 @@ -### Fan Expansion {#fan-expansion} - -The System Interface circuit board has support for 4 additional 12 V brushless 4-wire PWM fans. -Ports FAN 1, FAN 2, FAN 3, and FAN 4 are already used by the base Husky A300. -Ports FAN 5, FAN 6, FAN 7, and FAN 8 are available for your fan expansions. - -:::info Examples Of Supported fans - -* [CFM-8025BG-170-517-22](https://www.digikey.ca/en/products/detail/cui-devices/CFM-8025BG-170-517-22/16581761) -* [9GA0812P4J001](https://www.digikey.ca/en/products/detail/sanyo-denki-america-inc/9GA0812P4J001/6192305). - -::: - -The pinout for each fan is: - -| Pin | Function | -| :-- | :----------------------------- | -| 1 | 12 V | -| 2 | GND | -| 3 | Tachometer _(output from fan)_ | -| 4 | PWM _(input to fan, 3.3 V)_ | - -The speed of each fan can be controlled by publishing to the `/a300_#####/platform/mcu/cmd_fans` ROS topic. - -The speed of each fan can be monitored by reading the `/a300_#####/platform/mcu/status/fans` ROS topic. - -In both cases, the fan value is in the range from 0 _(not spinning)_, to 255 _(max speed)_. - -:::info - -Fans require spool up time on startup. -Setting a fan to a very low value may result in the fan not rotating. -You should experiment to find minimum PWM value that causes your fan to spin. - -::: +### Fan Expansion {#fan-expansion} + +The System Interface circuit board has support for 4 additional 12 V brushless 4-wire PWM fans. +Ports FAN 1, FAN 2, FAN 3, and FAN 4 are already used by the base Husky A300. +Ports FAN 5, FAN 6, FAN 7, and FAN 8 are available for your fan expansions. + +:::info Examples Of Supported fans + +* [CFM-8025BG-170-517-22](https://www.digikey.ca/en/products/detail/cui-devices/CFM-8025BG-170-517-22/16581761) +* [9GA0812P4J001](https://www.digikey.ca/en/products/detail/sanyo-denki-america-inc/9GA0812P4J001/6192305). + +::: + +The pinout for each fan is: + +| Pin | Function | +| :-- | :----------------------------- | +| 1 | 12 V | +| 2 | GND | +| 3 | Tachometer _(output from fan)_ | +| 4 | PWM _(input to fan, 3.3 V)_ | + +The speed of each fan can be controlled by publishing to the `/a300_#####/platform/mcu/cmd_fans` ROS topic. + +The speed of each fan can be monitored by reading the `/a300_#####/platform/mcu/status/fans` ROS topic. + +In both cases, the fan value is in the range from 0 _(not spinning)_, to 255 _(max speed)_. + +:::info + +Fans require spool up time on startup. +Setting a fan to a very low value may result in the fan not rotating. +You should experiment to find minimum PWM value that causes your fan to spin. + +::: diff --git a/components/husky_a300/husky_a300_internal_integrations.mdx b/components/husky_a300/husky_a300_internal_integrations.mdx index f26202e03..005557778 100644 --- a/components/husky_a300/husky_a300_internal_integrations.mdx +++ b/components/husky_a300/husky_a300_internal_integrations.mdx @@ -1,22 +1,22 @@ -### Internal Integrations - -[//]: <> (TODO, add image of an internal integration) - -There are interfaces inside the Husky for your custom compnents. -This [Interface Control Drawing](/assets/pdf/clearpath_robotics_034163.pdf) shows the available volume near the robot's batteries, - noting that the size of this volume changes depending on what battery configuration your Husky has—_(40 Ah, 80 Ah, or 120 Ah)_. -The drawing also shows mounting provisions on the robot's Electronics Tray, for including these components: - -* Husky's System Interface Assembly _(circuit board with Husky's microcontroller, power supplies, and motor controllers)_ -* Primary computer -* IMU -* Add-on secondary computer or graphics card -* Add-on USB hub - -Refer to the [STEP model](#step-model) for more measurements of the Husky's interface areas. - -:::note - -This integration volume is available inside the base Husky A300, as well as Husky AMP and Husky Observer. - -::: +### Internal Integrations + +[//]: <> (TODO, add image of an internal integration) + +There are interfaces inside the Husky for your custom compnents. +This [Interface Control Drawing](/assets/pdf/clearpath_robotics_034163.pdf) shows the available volume near the robot's batteries, + noting that the size of this volume changes depending on what battery configuration your Husky has—_(40 Ah, 80 Ah, or 120 Ah)_. +The drawing also shows mounting provisions on the robot's Electronics Tray, for including these components: + +* Husky's System Interface Assembly _(circuit board with Husky's microcontroller, power supplies, and motor controllers)_ +* Primary computer +* IMU +* Add-on secondary computer or graphics card +* Add-on USB hub + +Refer to the [STEP model](#step-model) for more measurements of the Husky's interface areas. + +:::note + +This integration volume is available inside the base Husky A300, as well as Husky AMP and Husky Observer. + +::: diff --git a/components/husky_a300/husky_a300_ip_addresses.mdx b/components/husky_a300/husky_a300_ip_addresses.mdx index a0298283a..79a1047a9 100644 --- a/components/husky_a300/husky_a300_ip_addresses.mdx +++ b/components/husky_a300/husky_a300_ip_addresses.mdx @@ -1,58 +1,58 @@ -### IP Addresses - -
- - - - - - - - - - - - - - - - - - {(props.robotModel == "Observer") && - - - } - {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - - - } - {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - - - } - - - {(props.robotModel == "AMP") && } - {(props.robotModel == "Observer") && } - - {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - - - } - {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - - - } - {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - - - } -
IP AddressDevice
192.168.131.1Computer, Primary
192.168.131.2Common Core MCU
192.168.131.5Computer, Secondary, (Optional)
192.168.131.10Axis Q62 Pan-Tilt-Zoom Camera
192.168.131.15Front OAK-D Camera
192.168.131.16Rear OAK-D Camera
192.168.131.20Side Hokuyo Lidar (Optional, Autonomous Wireless Charging)Side Hokuyo Lidar
192.168.131.25Seyond Robin W Lidar
192.168.131.35Fixposition Vision RTK 2 Positioning
192.168.131.51Peplink Access Point
-
- -:::info Custom Additions - -Our [Network IP Addresses page](/docs/ros/networking/network_ip_addresses) lists the common ranges we use per sensor type. -Clearpath will provide a supplementary manual that includes the IP addressess of custom configuration sensors. - -::: +### IP Addresses + +
+ + + + + + + + + + + + + + + + + + {(props.robotModel == "Observer") && + + + } + {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + + + } + {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + + + } + + + {(props.robotModel == "AMP") && } + {(props.robotModel == "Observer") && } + + {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + + + } + {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + + + } + {((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + + + } +
IP AddressDevice
192.168.131.1Computer, Primary
192.168.131.2Common Core MCU
192.168.131.5Computer, Secondary, (Optional)
192.168.131.10Axis Q62 Pan-Tilt-Zoom Camera
192.168.131.15Front OAK-D Camera
192.168.131.16Rear OAK-D Camera
192.168.131.20Side Hokuyo Lidar (Optional, Autonomous Wireless Charging)Side Hokuyo Lidar
192.168.131.25Seyond Robin W Lidar
192.168.131.35Fixposition Vision RTK 2 Positioning
192.168.131.51Peplink Access Point
+
+ +:::info Custom Additions + +Our [Network IP Addresses page](/docs/ros/networking/network_ip_addresses) lists the common ranges we use per sensor type. +Clearpath will provide a supplementary manual that includes the IP addressess of custom configuration sensors. + +::: diff --git a/components/husky_a300/husky_a300_motors.mdx b/components/husky_a300/husky_a300_motors.mdx index 01cf1ab48..e82195ec5 100644 --- a/components/husky_a300/husky_a300_motors.mdx +++ b/components/husky_a300/husky_a300_motors.mdx @@ -52,6 +52,20 @@ When reinstalling the motor and suspension: * Torque the motor's 4 screws to 20 N·m. + * Gently pull both motor cables away from the motor so that the cables are held tightly along the suspension beam. + * Ensure that both cables are routed along the top face of the suspension beam, and are laid out so that the thinner cable sits on top of the thicker cable. + * Insert an 11" black cable tie into the first hole in the suspension beam (the hole closest to the motor) and tie it around the cables as they are being held. + * Ensure that the cable tie is tightened as much as possible by hand, that both cables remain above the suspension beam, and the thinner cable remains on top of the thicker cable. + * Insert another 11" black cable tie into the second hole in the suspension beam (the hole closest to the center) and tie it around the cables. + * Ensure that the cable tie is tightened as much as possible by hand, that both cables remain above the suspension beam, and the thinner cable remains on top of the thicker cable. + * Cut off the extra length of both cable ties. + * Repeat above steps for each of the remaining three motors. +
+ +
* Torque the wheel's 6 screws to 20 N·m. * Torque the suspension beam's nuts to 30 N·m. Torque these slowly, in a star pattern. diff --git a/components/husky_a300/husky_a300_network_connection.mdx b/components/husky_a300/husky_a300_network_connection.mdx index fa33c95d5..e66187fb7 100644 --- a/components/husky_a300/husky_a300_network_connection.mdx +++ b/components/husky_a300/husky_a300_network_connection.mdx @@ -1,15 +1,15 @@ -import ComponentEthernetConnection from "/components/husky_a300/networking/husky_a300_ethernet_connection.mdx"; -import ComponentPeplinkWifiApCconnection from "/components/husky_a300/networking/husky_a300_peplink_wifi_ap_connection.mdx"; -import ComponentNetplanWifiClient from "/components/husky_a300/networking/husky_a300_netplan_wifi_client.mdx"; -import ComponentPeplinkWifiClient from "/components/husky_a300/networking/husky_a300_peplink_wifi_client.mdx"; -import ComponentPeplinkCellular from "/components/husky_a300/networking/husky_a300_peplink_cellular.mdx"; - -### Robot Network Connection {#network-connection} - -Husky provides several network connection options, the details of which are outlined below. - - -{(props.robotModel == "A300") && } -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && } -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && } -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && } +import ComponentEthernetConnection from "/components/husky_a300/networking/husky_a300_ethernet_connection.mdx"; +import ComponentPeplinkWifiApCconnection from "/components/husky_a300/networking/husky_a300_peplink_wifi_ap_connection.mdx"; +import ComponentNetplanWifiClient from "/components/husky_a300/networking/husky_a300_netplan_wifi_client.mdx"; +import ComponentPeplinkWifiClient from "/components/husky_a300/networking/husky_a300_peplink_wifi_client.mdx"; +import ComponentPeplinkCellular from "/components/husky_a300/networking/husky_a300_peplink_cellular.mdx"; + +### Robot Network Connection {#network-connection} + +Husky provides several network connection options, the details of which are outlined below. + + +{(props.robotModel == "A300") && } +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && } +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && } +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && } diff --git a/components/husky_a300/husky_a300_orientation_references.mdx b/components/husky_a300/husky_a300_orientation_references.mdx index f29a3079f..c75a843d7 100644 --- a/components/husky_a300/husky_a300_orientation_references.mdx +++ b/components/husky_a300/husky_a300_orientation_references.mdx @@ -1,16 +1,16 @@ -### Orientation References - -Husky's coordinate system is based on ISO 8855. - -* Gravity is aligned with -Z. -* +X translational velocity will drive the Husky forward. -* The Husky can turn with ± Yaw. - -
-
- -
-
+### Orientation References + +Husky's coordinate system is based on ISO 8855. + +* Gravity is aligned with -Z. +* +X translational velocity will drive the Husky forward. +* The Husky can turn with ± Yaw. + +
+
+ +
+
diff --git a/components/husky_a300/husky_a300_pacs.mdx b/components/husky_a300/husky_a300_pacs.mdx index 62e89bb50..974ff9044 100644 --- a/components/husky_a300/husky_a300_pacs.mdx +++ b/components/husky_a300/husky_a300_pacs.mdx @@ -1,13 +1,13 @@ -### PACS™ Mounting and Kits - -Husky A300 is equipped with a [PACS™](/docs_robots/accessories/pacs) Top Plate for mounting sensors and equipment. -[PACS™](/docs_robots/accessories/pacs) is a Clearpath Robotics standard, providing a grid of M5×0.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 bracket. - -:::note - -Our [Sensors](/docs_robots/accessories/sensors/) and [Add-ons](/docs_robots/accessories/add-ons/) pages -indicate the required bracket for the particular attachment. - -::: +### PACS™ Mounting and Kits + +Husky A300 is equipped with a [PACS™](/docs_robots/accessories/pacs) Top Plate for mounting sensors and equipment. +[PACS™](/docs_robots/accessories/pacs) is a Clearpath Robotics standard, providing a grid of M5×0.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 bracket. + +:::note + +Our [Sensors](/docs_robots/accessories/sensors/) and [Add-ons](/docs_robots/accessories/add-ons/) pages +indicate the required bracket for the particular attachment. + +::: diff --git a/components/husky_a300/husky_a300_power_connections.mdx b/components/husky_a300/husky_a300_power_connections.mdx index 264caf20b..0d6f62d8b 100644 --- a/components/husky_a300/husky_a300_power_connections.mdx +++ b/components/husky_a300/husky_a300_power_connections.mdx @@ -1,377 +1,377 @@ -import Admonition from "@theme/Admonition"; - -### Power Connections - -#### User Power Connections {#user-power-connections} - -The System Interface circuit board has 8 User Power connectors, labelled USER 1 through USER 8. - -User power is divided into 4 power rails and the power for each rail is shared across each of the 8 connectors. -The maximum—_(aggregate)_—current available on each power rail is outlined in the table below. -These circuits are protected with self resetting fuses. -These circuits can also be toggled on and off through ROS. - -| User Power Rail | Maximum (Aggregate) Current | -| :------------------------------------- | :-------------------------- | -| 12 V Rail A | 5 A | -| 12 V Rail B | 5 A | -| 24 V | 5 A | -| VBAT (24 - 29 V, unregulated) | 5 A | - - - Do not exceed the specified maximum current limit of each power rail. - Exceeding the maximum current may damage to your payload. - - - -##### User Power Pinout - -The pinout for each of the 8 connectors—_(USER 1 through USER 8)_—is illustrated below. - -| USER connector pin | Function | -| :----------------- | :------------------------------------- | -| 1 | 12 V (Rail B) | -| 2 | 12 V (Rail A) | -| 3 | 24 V | -| 4 | VBAT (24 - 29 V, unregulated) | -| 5 | GND | -| 6 | GND | -| 7 | GND | -| 8 | GND | - - -
- Making User Power Cables - - Connecting to user power requires the use of a Molex connector and compatible crimp terminals. - To create these cables, follow the steps below. - - 1. Expose about 5 mm of bare wire from the payload power leads and twist the exposed wire on both leads. - 2. Take 2 Molex terminals from the spare parts kit provided and insert the exposed wire and crimp the terminals, - ensuring the wires are well secured inside the terminal, as shown below. - 3. Take 1 connector housing from the spare parts kit provided and insert the positive payload power lead—_(red)_—into position - 1, 2, 3 or 4 of the connector until it locks into place. - The positions numbers are visible on the back of the plastic housing. - 4. Insert the negative payload power lead (black) into position 5, 6, 7, or 8 of the connector until it locks into place. - - [//]: <> (TODO, update images to show a higher quality crimp) - [//]: <> (TODO, update images to remove the background colour) - -
-
- -
Crimping A Wire
-
-
-
-
- -
Inserting The Crimped Wires Into The Molex Connector
-
-
- - For more technical information on the Molex power connectors, as well as their corresponding mating connectors, - please visit the [Digi-Key WM3703-ND Product Page](https://www.digikey.ca/en/products/detail/molex/0039012080/61382). -
-
- -##### Software Control of User Power Rails {#user_power_control} - -User power can be enabled or disabled through ROS by publishing to `/a300_#####/platform/mcu/cmd_user_power` ROS topic. - -- To disable user power, run: - - ``` - ros2 topic pub --once /a300_#####/platform/mcu/cmd_user_power std_msgs/msg/Bool '{data: false}' - ``` - -- To enable user power, run: - - ``` - ros2 topic pub --once /a300_#####/platform/mcu/cmd_user_power std_msgs/msg/Bool '{data: true}' - ``` - -:::note - -User Power is enabled by default shortly after the robot first powers up, regardless of its state when the robot was powered off. - -::: - -
- -#### Expansion Power _(EXP 1 and EXP 2)_ {#expansion-power} - -There are 2 Expansion Power connectors on the System Interface circuit board. -The Expanison Power connectors can power small manipulators, DC-AC inverters, and DC-DC supplies. - -These connectors supply VBAT voltage, with a combined current of up to 20 A. -The connectors also include soft-start circuitry which limits inrush current to 25 A. -This soft-start circuit reduces the chance of a high capacitance load causing the 20 A fuse to pop. - -:::info Replacement Fuse - -Use a [Littelfuse 0297020.U](https://www.digikey.ca/en/products/detail/littelfuse-inc/0297020-U/3427482?s=N4IgTCBcDaIAxgJwHYFwHQFUQF0C%2BQA) as the replacement. - -::: - -##### Expansion Power Pinout - -The pinout for each of the 2 connectors—_(EXP 1 and EXP 2)_—is illustrated below. - -| Expansion Power connector pin | Function | -| :---------------------------- | :------------------------------------- | -| 1 | VBAT (24 - 29 V, unregulated) | -| 2 | GND | - -
- -##### Software Control of Expansion Power Rails - -The Expansion Power connectors are connected to the same control system as the User Power. -Refer to the [Software Control of User Power Rails](#user_power_control) section for details. - -
- -#### High Power Expansion Kit _(Large VBAT)_ {#high-power-expansion-kit} - -:::note - -The optional High Power Expansion Kit can purchased at the time of your original Husky order—_(Clearpath item 032001)_. -We do not allow field installation of the kit. - -::: - -:::tip - -We suggest you purchase a 80 Ah or 120 Ah Husky if you plan to operate on hills steeper than 5°, and have a payload of more than 50kg. -40 Ah battery configuration may not provide enough power in the worst case. -Contact [Support](#support) for more details. - -::: - -Some high power payloads, such as manipulators, require more power than can be provided through the User Power connectors. -The optional High Power Expansion Kit provides VBAT voltage at 40 A. -It also includes 2 contactors for enabling and disabling power to the payload. - -
- Making A Large VBAT Cable - - We suggest using #10 AWG wire for this cable routing if it is completely inside the robot's chassis. - We suggest using #8 AWG wire for this cable routing if it is outside the chassis, where someone could touch the cable. - #8 AWG surface temperature is acceptable in an exposed cable for 40 A, per UL 1740. - - The mating cable will connect to the yellow Anderson Power Products SB50 connector in left-rear of the robot's chassis, under the Top Plate. - - - Always observe local laws and electrical standards when building cables. - - - - Consult the manufacturer's documentation for full details on proper crimping. - - - | Description | Vendor Part | CPR Part Number | - | :-------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------- | - | Mating connector | [Anderson 992G5-BK](https://www.digikey.ca/en/products/detail/anderson-power-products-inc/992G5-BK/10650433) | 022554 | - | Crimps, #8 AWG | [Anderson 5952-BK](https://www.digikey.ca/en/products/detail/anderson-power-products-inc/5952-BK/10650106) | 017281 | - | Crimps, #10 - #12 AWG | [Anderson 5953-BK](https://www.digikey.ca/en/products/detail/anderson-power-products-inc/5953-bk/10650410) | 022562 | - | Crimping tool | [Anderson 1309G4](https://www.digikey.ca/en/products/detail/anderson-power-products,-inc./1309G4/10650073) | N/A | - -
- -:::info Replacement Fuse - -Use a [Littelfuse 142.5631.5402](https://www.digikey.ca/en/products/detail/littelfuse-inc/142-5631-5402/2515916) as the replacement. - -::: - -
- -##### On/Off Control via Software - -The High Power Expansion Kit output is controlled through software by publishing to the ROS topic `/a300_#####/platform/mcu/cmd_high_power`, - similar to [Software Control of User Power Rails](#user_power_control). - -:::note - -The High Power Expansion Kit output is always disabled when the system powers up. -You must enable the output, via the ROS topic above, each time after the system powers up. - -::: - -
- -### AUX Inputs {#aux-inputs} - -The System Interface circuit board has 3 auxilliary inputs—_(AUX1 IN, AUX2 IN, AUX3 IN)_—that allow external payloads to provide inputs to the robot. -Each of these auxilliary inputs can be driven by one of the following: - -- a 12 V input -- a 24 V input -- a push button or switch - -The state of the input can be read from the ROS topic `/a300_#####/platform/mcu/status/aux_inputs`. -The AUX inputs are active low and are mapped to the ROS message bits as follows: - -- AUX1 IN: bit 0 -- AUX2 IN: bit 1 -- AUX3 IN: bit 2 - -| AUX Input | Payload State | `/a300_#####/platform/mcu/status/aux_inputs` Value | -| :------------------- | :------------------------------------------------------------------------------------ | :---------------------------------------- | -| AUX1 IN | 24 V on OR 12 V on OR button pressed
24 V off AND 12 V off AND button not pressed | bit 0 reads as '0'
bit 0 reads as '1' | -| AUX2 IN | 24 V on OR 12 V on OR button pressed
24 V off AND 12 V off AND button not pressed | bit 1 reads as '0'
bit 1 reads as '1' | -| AUX3 IN | 24 V on OR 12 V on OR button pressed
24 V off AND 12 V off AND button not pressed | bit 2 reads as '0'
bit 2 reads as '1' | - -#### AUX Input Pinout - -The pinout for each of the connectors—_(AUX1 IN, AUX2 IN, AUX3 IN)_—is illustrated below. - -| AUX IN Connector's Pin | Function | -| :--------------------- | :-------------------------- | -| 1 | 24 V In | -| 2 | 12 V In | -| 3 | Button/Switch In, _(3.3 V)_ | -| 4 | 24 V Return | -| 5 | 12 V Return | -| 6 | GND | - -
- AUX Input Example #1 - - Consider the example where AUX2 IN has a 12 V supply connected to pins 2 and 5, with the remaining pins unconnected. - - Monitor the input reading in ROS. - - ``` - ros2 topic echo /a300_#####/platform/mcu/status/aux_inputs - ``` - - | Action | `/a300_#####/platform/mcu/status/aux_inputs` value | Bit 2 Explanation | Bit 1 Explanation | Bit 0 Explanation | - | :------------------------------------ | :------------------------------------------------- | :--------------------------------- | :--------------------------- | :--------------------------------- | - | Begin with the 12 V supply turned off | 7 (8b00000111) | '1' since AUX3 IN is not connected | '1' since 12 V supply is off | '1' since AUX1 IN is not connected | - | Turn the 12 V power supply on | 5 (8b00000101) | '1' since AUX3 IN is not connected | '0' since 12 V supply is on | '1' since AUX1 IN is not connected | - | Turn the 12 V supply off | 7 (8b00000111) | '1' since AUX3 IN is not connected | '1' since 12 V supply is off | '1' since AUX1 IN is not connected | -
- -
- AUX Input Example #2 - - Consider the example where AUX1 IN has a 24 V supply connected to pins 1 and 4, - AUX2 IN has a 12 V supply connected to pins 2 and 5, and AUX3 IN has a push button connected to pin 3. - - | Action | `/a300_#####/platform/mcu/status/aux_inputs` value | Bit 2 Explanation | Bit 1 Explanation | Bit 0 Explanation | - | :--------------------------------------------------------------------------------- | :------------------------------------------------- | :------------------------------ | :--------------------------- | :--------------------------- | - | Begin with 12 V supply turned off, the 24 V supply off, and the button not pressed | 7 (8b00000111) | '1' since button is not pressed | '1' since 12 V supply is off | '1' since 24 V supply is off | - | Turn the 24 V power supply on | 6 (8b00000110) | '1' since button is not pressed | '1' since 12 V supply is off | '0' since 24 V supply is on | - | Turn the 12 V supply on | 4 (8b00000100) | '1' since button is not pressed | '0' since 12 V supply is on | '0' 24 V supply is on | - | Press and hold the button | 0 (8b00000000) | '0' since button is pressed | '0' since 12 V supply is on | '0' 24 V supply is on | - -
- -
- -### AUX Outputs {#aux-outputs} - -The System Interface circuit board includes 3 outputs—_(AUX1 OUT, AUX2 OUT, AUX3 OUT)_—that can be controlled by publishing to the `/a300_#####/platform/mcu/cmd_aux_outputs` ROS topic. -To enable the AUX outputs, publish a single message with the appropriate bits set to 1 to turn the output on, and 0 to turn it off. -The state does not persist so new commands will need to keep the bit enabled as well. -The AUX outputs are mapped to the ROS message bits as follows: - -- AUX1 OUT: bit 0 -- AUX2 OUT: bit 1 -- AUX3 OUT: bit 2 - -#### AUX Output Pinout - -Each of the AUX outputs is an 8 position connector with pinout as outlined below. -The output value is available in several modes: - -- MOSFET outputs, _(2X)_ -- Normally open relay -- Normally closed relay - -| AUX OUT Connector Pin | Name | Function | Output when corresponding `cmd_aux_outputs` bit is '0' | Output when corresponding `cmd_aux_outputs` bit is '1' | -| :-------------------- | :--------------- | :-------------------------------------------------------- | :----------------------------------------------------- | :----------------------------------------------------- | -| 1 | AUX_24V | 24 V output, fused at 3 A | 24 V | 24 V | -| 2 | GND | GND | GND | GND | -| 3 | AUX_RELAY_NC | Normally closed relay pin | Connected to AUX_RELAY_COMMON | Floating | -| 4 | AUX_MOSFET2 | MOSFET #2 DRAIN | GND | Floating | -| 5 | GND | GND | GND | GND | -| 6 | AUX_RELAY_COMMON | Input that gets connected to AUX_RELAY_NC or AUX_RELAY_NO | Connected to AUX_RELAY_NC | Connected to AUX_RELAY_NO | -| 7 | AUX_RELAY_NO | Normally open relay pin | Floating | Connected to AUX_RELAY_COMMON | -| 8 | AUX_MOSFET1 | MOSFET #1 DRAIN | GND | Floating | - -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - Husky AMP's lights and sounder are controlled by the 3 AUX Output connectors. - The AUX Outputs cannot be used for a user payload on Husky AMP or Husky Observer. -} - -
- AUX Output Examples - - - To disable all AUX outputs: - - ``` - rostopic pub /a300_#####/platform/mcu/cmd_aux_outputs std_msgs/UInt8 "data: 0" - ``` - - - To enable all AUX outputs: - - ``` - rostopic pub /a300_#####/platform/mcu/cmd_aux_outputs std_msgs/UInt8 "data: 7" - ``` - - - To enable just the AUX3 output: - - ``` - rostopic pub /a300_#####/platform/mcu/cmd_aux_outputs std_msgs/UInt8 "data: 4" - ``` - -
- - -### General Purpose Inputs and Outputs _(GPIO)_ {#gpio} - -The System Interface circuit board includes 4 general purpose inputs, and 4 general purpose outputs. -All GPIOs are at the 3.3 V logic level. -General purpose inputs are readable from the `/a300_#####/platform/mcu/status/gp_inputs` ROS topic. -Publishing to the `/a300_#####/platform/mcu/cmd_gp_outputs` ROS topic controls the general purpose outputs. - -:::info - -All the inputs and outputs are exposed through a single connector. - -::: - -#### General Purpose Input Pinout - -| GPIO connector pin | Function | `gp_inputs` value when driven at 0 V | `gp_inputs` value when driven at 3.3 V | -| :----------------- | :------- | :----------------------------------- | :------------------------------------- | -| 5 | GP In 1 | Bit 0 is '0' | Bit 0 is '1' | -| 6 | GP In 2 | Bit 1 is '0' | Bit 1 is '1' | -| 7 | GP In 3 | Bit 2 is '0' | Bit 2 is '1' | -| 8 | GP In 4 | Bit 3 is '0' | Bit 3 is '1' | -| 13 | GND | N/A | N/A | -| 14 | GND | N/A | N/A | -| 15 | GND | N/A | N/A | -| 16 | GND | N/A | N/A | - -#### General Purpose Output Pinout - -| GPIO connector pin | Function | Corresponding bit in `cmd_gp_outputs` | Output value when set to '0' | Output value when set to '1' | -| :----------------- | :------- | :------------------------------------ | :--------------------------- | :--------------------------- | -| 1 | GP Out 1 | 0 | 0 V | 3.3 V | -| 2 | GP Out 2 | 1 | 0 V | 3.3 V | -| 3 | GP Out 3 | 2 | 0 V | 3.3 V | -| 4 | GP Out 4 | 3 | 0 V | 3.3 V | -| 9 | GND | N/A | GND | GND | -| 10 | GND | N/A | GND | GND | -| 11 | GND | N/A | GND | GND | -| 12 | GND | N/A | GND | GND | +import Admonition from "@theme/Admonition"; + +### Power Connections + +#### User Power Connections {#user-power-connections} + +The System Interface circuit board has 8 User Power connectors, labelled USER 1 through USER 8. + +User power is divided into 4 power rails and the power for each rail is shared across each of the 8 connectors. +The maximum—_(aggregate)_—current available on each power rail is outlined in the table below. +These circuits are protected with self resetting fuses. +These circuits can also be toggled on and off through ROS. + +| User Power Rail | Maximum (Aggregate) Current | +| :------------------------------------- | :-------------------------- | +| 12 V Rail A | 5 A | +| 12 V Rail B | 5 A | +| 24 V | 5 A | +| VBAT (24 - 29 V, unregulated) | 5 A | + + + Do not exceed the specified maximum current limit of each power rail. + Exceeding the maximum current may damage to your payload. + + + +##### User Power Pinout + +The pinout for each of the 8 connectors—_(USER 1 through USER 8)_—is illustrated below. + +| USER connector pin | Function | +| :----------------- | :------------------------------------- | +| 1 | 12 V (Rail B) | +| 2 | 12 V (Rail A) | +| 3 | 24 V | +| 4 | VBAT (24 - 29 V, unregulated) | +| 5 | GND | +| 6 | GND | +| 7 | GND | +| 8 | GND | + + +
+ Making User Power Cables + + Connecting to user power requires the use of a Molex connector and compatible crimp terminals. + To create these cables, follow the steps below. + + 1. Expose about 5 mm of bare wire from the payload power leads and twist the exposed wire on both leads. + 2. Take 2 Molex terminals from the spare parts kit provided and insert the exposed wire and crimp the terminals, + ensuring the wires are well secured inside the terminal, as shown below. + 3. Take 1 connector housing from the spare parts kit provided and insert the positive payload power lead—_(red)_—into position + 1, 2, 3 or 4 of the connector until it locks into place. + The positions numbers are visible on the back of the plastic housing. + 4. Insert the negative payload power lead (black) into position 5, 6, 7, or 8 of the connector until it locks into place. + + [//]: <> (TODO, update images to show a higher quality crimp) + [//]: <> (TODO, update images to remove the background colour) + +
+
+ +
Crimping A Wire
+
+
+
+
+ +
Inserting The Crimped Wires Into The Molex Connector
+
+
+ + For more technical information on the Molex power connectors, as well as their corresponding mating connectors, + please visit the [Digi-Key WM3703-ND Product Page](https://www.digikey.ca/en/products/detail/molex/0039012080/61382). +
+
+ +##### Software Control of User Power Rails {#user_power_control} + +User power can be enabled or disabled through ROS by publishing to `/a300_#####/platform/mcu/cmd_user_power` ROS topic. + +- To disable user power, run: + + ``` + ros2 topic pub --once /a300_#####/platform/mcu/cmd_user_power std_msgs/msg/Bool '{data: false}' + ``` + +- To enable user power, run: + + ``` + ros2 topic pub --once /a300_#####/platform/mcu/cmd_user_power std_msgs/msg/Bool '{data: true}' + ``` + +:::note + +User Power is enabled by default shortly after the robot first powers up, regardless of its state when the robot was powered off. + +::: + +
+ +#### Expansion Power _(EXP 1 and EXP 2)_ {#expansion-power} + +There are 2 Expansion Power connectors on the System Interface circuit board. +The Expanison Power connectors can power small manipulators, DC-AC inverters, and DC-DC supplies. + +These connectors supply VBAT voltage, with a combined current of up to 20 A. +The connectors also include soft-start circuitry which limits inrush current to 25 A. +This soft-start circuit reduces the chance of a high capacitance load causing the 20 A fuse to pop. + +:::info Replacement Fuse + +Use a [Littelfuse 0297020.U](https://www.digikey.ca/en/products/detail/littelfuse-inc/0297020-U/3427482?s=N4IgTCBcDaIAxgJwHYFwHQFUQF0C%2BQA) as the replacement. + +::: + +##### Expansion Power Pinout + +The pinout for each of the 2 connectors—_(EXP 1 and EXP 2)_—is illustrated below. + +| Expansion Power connector pin | Function | +| :---------------------------- | :------------------------------------- | +| 1 | VBAT (24 - 29 V, unregulated) | +| 2 | GND | + +
+ +##### Software Control of Expansion Power Rails + +The Expansion Power connectors are connected to the same control system as the User Power. +Refer to the [Software Control of User Power Rails](#user_power_control) section for details. + +
+ +#### High Power Expansion Kit _(Large VBAT)_ {#high-power-expansion-kit} + +:::note + +The optional High Power Expansion Kit can purchased at the time of your original Husky order—_(Clearpath item 032001)_. +We do not allow field installation of the kit. + +::: + +:::tip + +We suggest you purchase a 80 Ah or 120 Ah Husky if you plan to operate on hills steeper than 5°, and have a payload of more than 50kg. +40 Ah battery configuration may not provide enough power in the worst case. +Contact [Support](#support) for more details. + +::: + +Some high power payloads, such as manipulators, require more power than can be provided through the User Power connectors. +The optional High Power Expansion Kit provides VBAT voltage at 40 A. +It also includes 2 contactors for enabling and disabling power to the payload. + +
+ Making A Large VBAT Cable + + We suggest using #10 AWG wire for this cable routing if it is completely inside the robot's chassis. + We suggest using #8 AWG wire for this cable routing if it is outside the chassis, where someone could touch the cable. + #8 AWG surface temperature is acceptable in an exposed cable for 40 A, per UL 1740. + + The mating cable will connect to the yellow Anderson Power Products SB50 connector in left-rear of the robot's chassis, under the Top Plate. + + + Always observe local laws and electrical standards when building cables. + + + + Consult the manufacturer's documentation for full details on proper crimping. + + + | Description | Vendor Part | CPR Part Number | + | :-------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------- | + | Mating connector | [Anderson 992G5-BK](https://www.digikey.ca/en/products/detail/anderson-power-products-inc/992G5-BK/10650433) | 022554 | + | Crimps, #8 AWG | [Anderson 5952-BK](https://www.digikey.ca/en/products/detail/anderson-power-products-inc/5952-BK/10650106) | 017281 | + | Crimps, #10 - #12 AWG | [Anderson 5953-BK](https://www.digikey.ca/en/products/detail/anderson-power-products-inc/5953-bk/10650410) | 022562 | + | Crimping tool | [Anderson 1309G4](https://www.digikey.ca/en/products/detail/anderson-power-products,-inc./1309G4/10650073) | N/A | + +
+ +:::info Replacement Fuse + +Use a [Littelfuse 142.5631.5402](https://www.digikey.ca/en/products/detail/littelfuse-inc/142-5631-5402/2515916) as the replacement. + +::: + +
+ +##### On/Off Control via Software + +The High Power Expansion Kit output is controlled through software by publishing to the ROS topic `/a300_#####/platform/mcu/cmd_high_power`, + similar to [Software Control of User Power Rails](#user_power_control). + +:::note + +The High Power Expansion Kit output is always disabled when the system powers up. +You must enable the output, via the ROS topic above, each time after the system powers up. + +::: + +
+ +### AUX Inputs {#aux-inputs} + +The System Interface circuit board has 3 auxilliary inputs—_(AUX1 IN, AUX2 IN, AUX3 IN)_—that allow external payloads to provide inputs to the robot. +Each of these auxilliary inputs can be driven by one of the following: + +- a 12 V input +- a 24 V input +- a push button or switch + +The state of the input can be read from the ROS topic `/a300_#####/platform/mcu/status/aux_inputs`. +The AUX inputs are active low and are mapped to the ROS message bits as follows: + +- AUX1 IN: bit 0 +- AUX2 IN: bit 1 +- AUX3 IN: bit 2 + +| AUX Input | Payload State | `/a300_#####/platform/mcu/status/aux_inputs` Value | +| :------------------- | :------------------------------------------------------------------------------------ | :---------------------------------------- | +| AUX1 IN | 24 V on OR 12 V on OR button pressed
24 V off AND 12 V off AND button not pressed | bit 0 reads as '0'
bit 0 reads as '1' | +| AUX2 IN | 24 V on OR 12 V on OR button pressed
24 V off AND 12 V off AND button not pressed | bit 1 reads as '0'
bit 1 reads as '1' | +| AUX3 IN | 24 V on OR 12 V on OR button pressed
24 V off AND 12 V off AND button not pressed | bit 2 reads as '0'
bit 2 reads as '1' | + +#### AUX Input Pinout + +The pinout for each of the connectors—_(AUX1 IN, AUX2 IN, AUX3 IN)_—is illustrated below. + +| AUX IN Connector's Pin | Function | +| :--------------------- | :-------------------------- | +| 1 | 24 V In | +| 2 | 12 V In | +| 3 | Button/Switch In, _(3.3 V)_ | +| 4 | 24 V Return | +| 5 | 12 V Return | +| 6 | GND | + +
+ AUX Input Example #1 + + Consider the example where AUX2 IN has a 12 V supply connected to pins 2 and 5, with the remaining pins unconnected. + + Monitor the input reading in ROS. + + ``` + ros2 topic echo /a300_#####/platform/mcu/status/aux_inputs + ``` + + | Action | `/a300_#####/platform/mcu/status/aux_inputs` value | Bit 2 Explanation | Bit 1 Explanation | Bit 0 Explanation | + | :------------------------------------ | :------------------------------------------------- | :--------------------------------- | :--------------------------- | :--------------------------------- | + | Begin with the 12 V supply turned off | 7 (8b00000111) | '1' since AUX3 IN is not connected | '1' since 12 V supply is off | '1' since AUX1 IN is not connected | + | Turn the 12 V power supply on | 5 (8b00000101) | '1' since AUX3 IN is not connected | '0' since 12 V supply is on | '1' since AUX1 IN is not connected | + | Turn the 12 V supply off | 7 (8b00000111) | '1' since AUX3 IN is not connected | '1' since 12 V supply is off | '1' since AUX1 IN is not connected | +
+ +
+ AUX Input Example #2 + + Consider the example where AUX1 IN has a 24 V supply connected to pins 1 and 4, + AUX2 IN has a 12 V supply connected to pins 2 and 5, and AUX3 IN has a push button connected to pin 3. + + | Action | `/a300_#####/platform/mcu/status/aux_inputs` value | Bit 2 Explanation | Bit 1 Explanation | Bit 0 Explanation | + | :--------------------------------------------------------------------------------- | :------------------------------------------------- | :------------------------------ | :--------------------------- | :--------------------------- | + | Begin with 12 V supply turned off, the 24 V supply off, and the button not pressed | 7 (8b00000111) | '1' since button is not pressed | '1' since 12 V supply is off | '1' since 24 V supply is off | + | Turn the 24 V power supply on | 6 (8b00000110) | '1' since button is not pressed | '1' since 12 V supply is off | '0' since 24 V supply is on | + | Turn the 12 V supply on | 4 (8b00000100) | '1' since button is not pressed | '0' since 12 V supply is on | '0' 24 V supply is on | + | Press and hold the button | 0 (8b00000000) | '0' since button is pressed | '0' since 12 V supply is on | '0' 24 V supply is on | + +
+ +
+ +### AUX Outputs {#aux-outputs} + +The System Interface circuit board includes 3 outputs—_(AUX1 OUT, AUX2 OUT, AUX3 OUT)_—that can be controlled by publishing to the `/a300_#####/platform/mcu/cmd_aux_outputs` ROS topic. +To enable the AUX outputs, publish a single message with the appropriate bits set to 1 to turn the output on, and 0 to turn it off. +The state does not persist so new commands will need to keep the bit enabled as well. +The AUX outputs are mapped to the ROS message bits as follows: + +- AUX1 OUT: bit 0 +- AUX2 OUT: bit 1 +- AUX3 OUT: bit 2 + +#### AUX Output Pinout + +Each of the AUX outputs is an 8 position connector with pinout as outlined below. +The output value is available in several modes: + +- MOSFET outputs, _(2X)_ +- Normally open relay +- Normally closed relay + +| AUX OUT Connector Pin | Name | Function | Output when corresponding `cmd_aux_outputs` bit is '0' | Output when corresponding `cmd_aux_outputs` bit is '1' | +| :-------------------- | :--------------- | :-------------------------------------------------------- | :----------------------------------------------------- | :----------------------------------------------------- | +| 1 | AUX_24V | 24 V output, fused at 3 A | 24 V | 24 V | +| 2 | GND | GND | GND | GND | +| 3 | AUX_RELAY_NC | Normally closed relay pin | Connected to AUX_RELAY_COMMON | Floating | +| 4 | AUX_MOSFET2 | MOSFET #2 DRAIN | GND | Floating | +| 5 | GND | GND | GND | GND | +| 6 | AUX_RELAY_COMMON | Input that gets connected to AUX_RELAY_NC or AUX_RELAY_NO | Connected to AUX_RELAY_NC | Connected to AUX_RELAY_NO | +| 7 | AUX_RELAY_NO | Normally open relay pin | Floating | Connected to AUX_RELAY_COMMON | +| 8 | AUX_MOSFET1 | MOSFET #1 DRAIN | GND | Floating | + +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + Husky AMP's lights and sounder are controlled by the 3 AUX Output connectors. + The AUX Outputs cannot be used for a user payload on Husky AMP or Husky Observer. +} + +
+ AUX Output Examples + + - To disable all AUX outputs: + + ``` + rostopic pub /a300_#####/platform/mcu/cmd_aux_outputs std_msgs/UInt8 "data: 0" + ``` + + - To enable all AUX outputs: + + ``` + rostopic pub /a300_#####/platform/mcu/cmd_aux_outputs std_msgs/UInt8 "data: 7" + ``` + + - To enable just the AUX3 output: + + ``` + rostopic pub /a300_#####/platform/mcu/cmd_aux_outputs std_msgs/UInt8 "data: 4" + ``` + +
+ + +### General Purpose Inputs and Outputs _(GPIO)_ {#gpio} + +The System Interface circuit board includes 4 general purpose inputs, and 4 general purpose outputs. +All GPIOs are at the 3.3 V logic level. +General purpose inputs are readable from the `/a300_#####/platform/mcu/status/gp_inputs` ROS topic. +Publishing to the `/a300_#####/platform/mcu/cmd_gp_outputs` ROS topic controls the general purpose outputs. + +:::info + +All the inputs and outputs are exposed through a single connector. + +::: + +#### General Purpose Input Pinout + +| GPIO connector pin | Function | `gp_inputs` value when driven at 0 V | `gp_inputs` value when driven at 3.3 V | +| :----------------- | :------- | :----------------------------------- | :------------------------------------- | +| 5 | GP In 1 | Bit 0 is '0' | Bit 0 is '1' | +| 6 | GP In 2 | Bit 1 is '0' | Bit 1 is '1' | +| 7 | GP In 3 | Bit 2 is '0' | Bit 2 is '1' | +| 8 | GP In 4 | Bit 3 is '0' | Bit 3 is '1' | +| 13 | GND | N/A | N/A | +| 14 | GND | N/A | N/A | +| 15 | GND | N/A | N/A | +| 16 | GND | N/A | N/A | + +#### General Purpose Output Pinout + +| GPIO connector pin | Function | Corresponding bit in `cmd_gp_outputs` | Output value when set to '0' | Output value when set to '1' | +| :----------------- | :------- | :------------------------------------ | :--------------------------- | :--------------------------- | +| 1 | GP Out 1 | 0 | 0 V | 3.3 V | +| 2 | GP Out 2 | 1 | 0 V | 3.3 V | +| 3 | GP Out 3 | 2 | 0 V | 3.3 V | +| 4 | GP Out 4 | 3 | 0 V | 3.3 V | +| 9 | GND | N/A | GND | GND | +| 10 | GND | N/A | GND | GND | +| 11 | GND | N/A | GND | GND | +| 12 | GND | N/A | GND | GND | diff --git a/components/husky_a300/husky_a300_pre_operation_inspection.mdx b/components/husky_a300/husky_a300_pre_operation_inspection.mdx index 5c3d08e88..5c6f720b8 100644 --- a/components/husky_a300/husky_a300_pre_operation_inspection.mdx +++ b/components/husky_a300/husky_a300_pre_operation_inspection.mdx @@ -9,10 +9,11 @@ These are our suggested daily checks before sending the Husky on missions: 4. Inspect the tire treads for excessive wear of punctures. 5. Inspect the drivetrain for loose screws. 6. Inspect the drivetrain for any branches or debris lodged in robot's motors or suspension. -7. Inspect the air filter. -8. Clean any optical sensors. -9. Turn the robot on, and check the battery's State-of-charge. -10. Disconnect the battery charger from the robot. -11. Check that all of the Emergency Stop devices are functioning, including the _Rear Charge Port Door_, and the optional _Wireless Emergency Stop Transmitter_. -12. Check that the robot has connected to your worksite's wireless network. -13. Confirm that the robot computer has enough storage for any ROS bags that you plan to acquire during the robot's mission. +7. Inspect the drivetrain for damage to any of the motor cables or to the cable ties that are used to secure the motor cables to the suspension beam. Check that there is clearance between the motor cables and the tires. +8. Inspect the air filter. +9. Clean any optical sensors. +10. Turn the robot on, and check the battery's State-of-charge. +11. Disconnect the battery charger from the robot. +12. Check that all of the Emergency Stop devices are functioning, including the _Rear Charge Port Door_, and the optional _Wireless Emergency Stop Transmitter_. +13. Check that the robot has connected to your worksite's wireless network. +14. Confirm that the robot computer has enough storage for any ROS bags that you plan to acquire during the robot's mission. diff --git a/components/husky_a300/husky_a300_replacing_fuses_bf1.mdx b/components/husky_a300/husky_a300_replacing_fuses_bf1.mdx index ccc4cfe53..244f9d072 100644 --- a/components/husky_a300/husky_a300_replacing_fuses_bf1.mdx +++ b/components/husky_a300/husky_a300_replacing_fuses_bf1.mdx @@ -1,22 +1,22 @@ -### Replacing BF1 Fuses {#replacing-fuses-bf1} - -1. Perform the [Lockout-Tagout Procedure](#lockout-tagout). -1. Locate the fuse to be replaced. Follow the maintenance procedures for the corresponding - subassembly to access the fuse. - :::safety-caution - **Treat all circuits, cables, and fuses inside the robot as potentially live.**

- Some connections inside the robot are live even after Lockout Tagout. - Refer to the details of the subassembly maintenance procedures to - determine if the fuse is connected to a live connection. - ::: -1. Remove the fuse cover. -1. Remove the nuts holding the fuse in place. -1. Remove the fuse from the fuse holder. -1. Install the replacement fuse into the fuse holder. - :::note - Ensure that you are replacing the fuse with the same part number and rating. Refer to - [Common Replacement Items](#common-replacement-items) for a list of fuses. - ::: -1. Reinstall both nuts onto the fuse holder and tighten to 3 N·m unless otherwise specified - in the subassembly maintenance procedures. -1. Reinstall the fuse cover. +### Replacing BF1 Fuses {#replacing-fuses-bf1} + +1. Perform the [Lockout-Tagout Procedure](#lockout-tagout). +1. Locate the fuse to be replaced. Follow the maintenance procedures for the corresponding + subassembly to access the fuse. + :::safety-caution + **Treat all circuits, cables, and fuses inside the robot as potentially live.**

+ Some connections inside the robot are live even after Lockout Tagout. + Refer to the details of the subassembly maintenance procedures to + determine if the fuse is connected to a live connection. + ::: +1. Remove the fuse cover. +1. Remove the nuts holding the fuse in place. +1. Remove the fuse from the fuse holder. +1. Install the replacement fuse into the fuse holder. + :::note + Ensure that you are replacing the fuse with the same part number and rating. Refer to + [Common Replacement Items](#common-replacement-items) for a list of fuses. + ::: +1. Reinstall both nuts onto the fuse holder and tighten to 3 N·m unless otherwise specified + in the subassembly maintenance procedures. +1. Reinstall the fuse cover. diff --git a/components/husky_a300/husky_a300_replacing_fuses_board_mount.mdx b/components/husky_a300/husky_a300_replacing_fuses_board_mount.mdx index a7ba311a2..ee5723ee0 100644 --- a/components/husky_a300/husky_a300_replacing_fuses_board_mount.mdx +++ b/components/husky_a300/husky_a300_replacing_fuses_board_mount.mdx @@ -1,18 +1,18 @@ -### Replacing Board Mount Fuses {#replacing-fuses-board-mount} - -1. Perform the [Lockout-Tagout Procedure](#lockout-tagout). -1. Locate the fuse to be replaced. Follow the maintenance procedures for the corresponding - subassembly to access the fuse. - :::safety-caution - **Treat all circuits, cables, and fuses inside the robot as potentially live.**

- Some connections inside the robot are live even after Lockout Tagout. - Refer to the details of the subassembly maintenance procedures to - determine if the fuse is connected to a live connection. - ::: -1. Use tweezers to pull up on the old fuse to remove it from the fuse holder. -1. Slide the replacement fuse into the fuse holder and push firmly until the fuse is installed fully. - :::note - Ensure that you are replacing the fuse with the same part number and rating. Refer to - [Common Replacement Items](#common-replacement-items) for a list of fuses. - ::: +### Replacing Board Mount Fuses {#replacing-fuses-board-mount} + +1. Perform the [Lockout-Tagout Procedure](#lockout-tagout). +1. Locate the fuse to be replaced. Follow the maintenance procedures for the corresponding + subassembly to access the fuse. + :::safety-caution + **Treat all circuits, cables, and fuses inside the robot as potentially live.**

+ Some connections inside the robot are live even after Lockout Tagout. + Refer to the details of the subassembly maintenance procedures to + determine if the fuse is connected to a live connection. + ::: +1. Use tweezers to pull up on the old fuse to remove it from the fuse holder. +1. Slide the replacement fuse into the fuse holder and push firmly until the fuse is installed fully. + :::note + Ensure that you are replacing the fuse with the same part number and rating. Refer to + [Common Replacement Items](#common-replacement-items) for a list of fuses. + ::: \ No newline at end of file diff --git a/components/husky_a300/husky_a300_replacing_fuses_mini_blade.mdx b/components/husky_a300/husky_a300_replacing_fuses_mini_blade.mdx index a153c7d96..48d8ef2db 100644 --- a/components/husky_a300/husky_a300_replacing_fuses_mini_blade.mdx +++ b/components/husky_a300/husky_a300_replacing_fuses_mini_blade.mdx @@ -1,18 +1,18 @@ -### Replacing Mini Blade Fuses {#replacing-fuses-blade-mini} - -1. Perform the [Lockout-Tagout Procedure](#lockout-tagout). -1. Locate the fuse to be replaced. Follow the maintenance procedures for the corresponding - subassembly to access the fuse. - :::safety-caution - **Treat all circuits, cables, and fuses inside the robot as potentially live.**

- Some connections inside the robot are live even after Lockout Tagout. - Refer to the details of the subassembly maintenance procedures to - determine if the fuse is connected to a live connection. - ::: -1. Pull up on the old fuse to remove it from the fuse holder. -1. Slide the replacement fuse into the fuse holder and push firmly until the fuse is installed fully. - :::note - Ensure that you are replacing the fuse with the same part number and rating. Refer to - [Common Replacement Items](#common-replacement-items) for a list of fuses. - ::: +### Replacing Mini Blade Fuses {#replacing-fuses-blade-mini} + +1. Perform the [Lockout-Tagout Procedure](#lockout-tagout). +1. Locate the fuse to be replaced. Follow the maintenance procedures for the corresponding + subassembly to access the fuse. + :::safety-caution + **Treat all circuits, cables, and fuses inside the robot as potentially live.**

+ Some connections inside the robot are live even after Lockout Tagout. + Refer to the details of the subassembly maintenance procedures to + determine if the fuse is connected to a live connection. + ::: +1. Pull up on the old fuse to remove it from the fuse holder. +1. Slide the replacement fuse into the fuse holder and push firmly until the fuse is installed fully. + :::note + Ensure that you are replacing the fuse with the same part number and rating. Refer to + [Common Replacement Items](#common-replacement-items) for a list of fuses. + ::: \ No newline at end of file diff --git a/components/husky_a300/husky_a300_step_model.mdx b/components/husky_a300/husky_a300_step_model.mdx index 68e861c02..8d72c0862 100644 --- a/components/husky_a300/husky_a300_step_model.mdx +++ b/components/husky_a300/husky_a300_step_model.mdx @@ -1,69 +1,69 @@ -import ComponentButtonStepDownload from "/components/button_download_step.tsx" - -### STEP Model {#step-model} - -{(props.robotModel == "A300") &&
- - - This simplified 3D model of the Husky A300 includes details like the Top Plate mounting surface, internal Battery Integration Volume, - and the System Interface circuit board where you can connect to the robot's electrical provisions. - -
-
- - -
- 40 Ah battery configuration is shown. - Other configurations are available. -
-
-
-
} - - -{(props.robotModel == "AMP") &&
- - - This simplified 3D model of the Husky A300 AMP includes details like the enclosure's mounting extrusions, electronic modules and 3U Eurorack, and arch superstructure. - This model also includes the features from the base Husky A300, such as the System Interface Assembly circuit board where you can connect to the robot's electrical provisions. - -
-
- - -
-
-
} - - -{(props.robotModel == "Observer") &&
- - - This simplified 3D model of the Husky A300 Observer includes the PTZ camera, and the wireless charger. - This model also includes all the features that exist in the Husky A300 and Husky AMP models. - -
-
- - -
-
+import ComponentButtonStepDownload from "/components/button_download_step.tsx" + +### STEP Model {#step-model} + +{(props.robotModel == "A300") &&
+ + + This simplified 3D model of the Husky A300 includes details like the Top Plate mounting surface, internal Battery Integration Volume, + and the System Interface circuit board where you can connect to the robot's electrical provisions. + +
+
+ + +
+ 40 Ah battery configuration is shown. + Other configurations are available. +
+
+
+
} + + +{(props.robotModel == "AMP") &&
+ + + This simplified 3D model of the Husky A300 AMP includes details like the enclosure's mounting extrusions, electronic modules and 3U Eurorack, and arch superstructure. + This model also includes the features from the base Husky A300, such as the System Interface Assembly circuit board where you can connect to the robot's electrical provisions. + +
+
+ + +
+
+
} + + +{(props.robotModel == "Observer") &&
+ + + This simplified 3D model of the Husky A300 Observer includes the PTZ camera, and the wireless charger. + This model also includes all the features that exist in the Husky A300 and Husky AMP models. + +
+
+ + +
+
} \ No newline at end of file diff --git a/components/husky_a300/husky_a300_system_interface_connector_summary.mdx b/components/husky_a300/husky_a300_system_interface_connector_summary.mdx index 4564daa19..a79bfe68e 100644 --- a/components/husky_a300/husky_a300_system_interface_connector_summary.mdx +++ b/components/husky_a300/husky_a300_system_interface_connector_summary.mdx @@ -1,27 +1,27 @@ -### System Interface Connector Summary {#system-interface-circuit-board-connector-summary} - -
-
- -
-
- -The System Interface Assembly is a circuit board that includes power supplies, lighting controllers, motor controllers, and the Husky's microcontroller. -This circuit board has connectors for: power, fans, relays, GPIOs, auxiliary inputs, auxiliary outputs, and Emergency Stop devices. - -| Purpose | Label on the circuit board | Connector on the circuit board | Mating connector | Mating connector's crimp | Crimping tool | -| :----------------------------------------------------------- | :--------------------------- | :----------------------------- | :--------------- | :------------------------------------------------------------------------------------- | :--------------- | -| User Power Connections | USER 1 - USER 8 | Molex 0039296088 | Molex 0039012080 | Molex 0039000140 (AWG 22-28)
Or
Molex 0039000073 (AWG 18-24) | Molex 0638191000 | -| Expansion Power | EXP 1 - EXP 2 | Molex 1720650202 | Molex 1700010102 | Molex 1720630311 (AWG 14-16)
Or
Molex 1720630312 (AWG 12) | Molex 2238631200 | -| AUX Inputs | AUX1 IN, AUX2 IN, AUX3 IN | TE 3-794682-6 | TE 794617-6 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | -| AUX Outputs | AUX1 OUT, AUX2 OUT, AUX3 OUT | TE 3-794682-8 | TE 794617-8 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | -| GPIO | GPIO | TE 4-794680-6 | TE 1-794617-6 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | -| Fans | FAN 5 - FAN 8 | Molex 0705430003 | Molex 0050579404 | Molex 0016020103 (AWG 22-24) | Molex 0638118700 | -| Wireless Emergency Stop | W ES (Wireless E-Stop) | TE 4-794682-0 | TE 1-794617-0 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | -| Emergency Stop Buttons | ES 3 - ES 8 (E-Stop) | TE 3-794682-4 | TE 794617-4 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | -| Computer Power | SYS1 - SYS 2 | Molex 1720650204 | Molex 1700010104 | Molex 1720630311 (AWG 14-16)
Or
Molex 1720630312 (AWG 12) | Molex 2238631200 | -| Graphics Card Power | SYS3 | Molex 1720650206 | Molex 1700010106 | Molex 1720630311 (AWG 14-16)
Or
Molex 1720630312 (AWG 12) | Molex 2238631200 | -| Network Switch Power | SYS4 | Molex 0039281023 | Molex 0039012020 | Molex 0039000140 (AWG 22-28)
Or
Molex 0039000073 (AWG 18-24) | Molex 0638191000 | +### System Interface Connector Summary {#system-interface-circuit-board-connector-summary} + +
+
+ +
+
+ +The System Interface Assembly is a circuit board that includes power supplies, lighting controllers, motor controllers, and the Husky's microcontroller. +This circuit board has connectors for: power, fans, relays, GPIOs, auxiliary inputs, auxiliary outputs, and Emergency Stop devices. + +| Purpose | Label on the circuit board | Connector on the circuit board | Mating connector | Mating connector's crimp | Crimping tool | +| :----------------------------------------------------------- | :--------------------------- | :----------------------------- | :--------------- | :------------------------------------------------------------------------------------- | :--------------- | +| User Power Connections | USER 1 - USER 8 | Molex 0039296088 | Molex 0039012080 | Molex 0039000140 (AWG 22-28)
Or
Molex 0039000073 (AWG 18-24) | Molex 0638191000 | +| Expansion Power | EXP 1 - EXP 2 | Molex 1720650202 | Molex 1700010102 | Molex 1720630311 (AWG 14-16)
Or
Molex 1720630312 (AWG 12) | Molex 2238631200 | +| AUX Inputs | AUX1 IN, AUX2 IN, AUX3 IN | TE 3-794682-6 | TE 794617-6 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | +| AUX Outputs | AUX1 OUT, AUX2 OUT, AUX3 OUT | TE 3-794682-8 | TE 794617-8 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | +| GPIO | GPIO | TE 4-794680-6 | TE 1-794617-6 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | +| Fans | FAN 5 - FAN 8 | Molex 0705430003 | Molex 0050579404 | Molex 0016020103 (AWG 22-24) | Molex 0638118700 | +| Wireless Emergency Stop | W ES (Wireless E-Stop) | TE 4-794682-0 | TE 1-794617-0 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | +| Emergency Stop Buttons | ES 3 - ES 8 (E-Stop) | TE 3-794682-4 | TE 794617-4 | TE 1-794606-1 (AWG 20-24)
Or
TE 1-794607-1 (AWG 26-30) | TE 91391-1 | +| Computer Power | SYS1 - SYS 2 | Molex 1720650204 | Molex 1700010104 | Molex 1720630311 (AWG 14-16)
Or
Molex 1720630312 (AWG 12) | Molex 2238631200 | +| Graphics Card Power | SYS3 | Molex 1720650206 | Molex 1700010106 | Molex 1720630311 (AWG 14-16)
Or
Molex 1720630312 (AWG 12) | Molex 2238631200 | +| Network Switch Power | SYS4 | Molex 0039281023 | Molex 0039012020 | Molex 0039000140 (AWG 22-28)
Or
Molex 0039000073 (AWG 18-24) | Molex 0638191000 | diff --git a/components/husky_a300/husky_a300_system_interface_debug_led.mdx b/components/husky_a300/husky_a300_system_interface_debug_led.mdx index 6eb059657..1c7ca7ef3 100644 --- a/components/husky_a300/husky_a300_system_interface_debug_led.mdx +++ b/components/husky_a300/husky_a300_system_interface_debug_led.mdx @@ -1,64 +1,64 @@ -### Debugging The System Interface Assembly, _(Debug LEDs)_ - -
-
- -
-
- -The System Interface Assembly includes many LEDs to help debug system issues. - -:::safety-warning - -The Husky must be powered on, with the Top Plate removed to see these Debug LEDs. -This exposes significant battery energy to the technician, and risk of starting a fire. - -Review your worksite's safe operating procedures before performing this task. - -::: - -
- -
- Click to see all the LED functions - - #### Common Core Debug LEDs - - - `D6: USB 5V`: Solid green if a USB cable is plugged in and used to power the board - - `D7: 3.3V`: Solid green when the 3.3 V power rail is operational; else off - - `D9: DBG/CON`: For future use - - `D11: HB/ERR`: Heartbeat that toggles (red/off) every 500 ms when the main firmware loop is running; solid on or off indicates an error - - #### DC/DC Debug LEDs - - - `D3: V OUT`: Solid green when the output is operational; else off - - #### Motor Controller LEDs - - - `5V0`: Solid green when the 5 V power rail is operational; else off - - `3V3`: Solid green when the 3.3 V power rail is operational; else off - - `MTR_FAULT`: Solid red when a motor fault is detected; else off - - `ERROR`: Toggles (red/off) every 500 ms when a motor control error is detected; else off - - `DBG2`: For future use - - `DBG1`: Heartbeat that toggles (green/off) every 500 ms when the firmware loop is running; solid on or off indicates an error - - #### Main Circuit Board Debug LEDs - - - `D2`: UVB FLT: User power VBAT fault: red if the user battery rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off - - `D3`: U24 FLT: User power 24V fault: red if the user 24V rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off - - `D4`: U12A FLT: User power 12VA fault: red if the user 12VA rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off - - `D5`: U12B FLT: User power 12VB fault: red if the user 12VB rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off - - `D6`: PWR GD: Main power good indicator: red if any power supply is not enabled or has a fault; else off - - `D7`: 3.3V: Solid green if 3.3V rail is operational; else off - - `D9`: UPWR GD: User power good indicator: red if any of the 4 user power rails are not enabled or have a fault (including and overcurrent on any channel); else off - - `D10`: 5V: Solid green if 5V rail is operational; else off - - `D12`: APWR GD: Auxiliary power good indicator: red if either of the auxiliary power supplies are not enabled or has a fault (Auxiliary power supplies the USER power as well as other PCBA subsystem power rails at 12V and 24V); else off - - `D13`: SPWR GD: System power good indicator: red if either of the system power supplies are not enabled or has a fault (System power supplies the power for PCs, any optional GPU, and the primary network switch); else off - - `D30`: WES BP: Wireless E-Stop Bypass indicator: green if the Wireless E-Stop Bypass is enabled; else off - - `D31`: WES PFLT: Wireless E-Stop Power fault: red if the power supply is not enabled or has a fault; else off - - `D46`: XPWR GD: Expansion power good indicator: red if expansion power is not enabled or has a fault; else off - +### Debugging The System Interface Assembly, _(Debug LEDs)_ + +
+
+ +
+
+ +The System Interface Assembly includes many LEDs to help debug system issues. + +:::safety-warning + +The Husky must be powered on, with the Top Plate removed to see these Debug LEDs. +This exposes significant battery energy to the technician, and risk of starting a fire. + +Review your worksite's safe operating procedures before performing this task. + +::: + +
+ +
+ Click to see all the LED functions + + #### Common Core Debug LEDs + + - `D6: USB 5V`: Solid green if a USB cable is plugged in and used to power the board + - `D7: 3.3V`: Solid green when the 3.3 V power rail is operational; else off + - `D9: DBG/CON`: For future use + - `D11: HB/ERR`: Heartbeat that toggles (red/off) every 500 ms when the main firmware loop is running; solid on or off indicates an error + + #### DC/DC Debug LEDs + + - `D3: V OUT`: Solid green when the output is operational; else off + + #### Motor Controller LEDs + + - `5V0`: Solid green when the 5 V power rail is operational; else off + - `3V3`: Solid green when the 3.3 V power rail is operational; else off + - `MTR_FAULT`: Solid red when a motor fault is detected; else off + - `ERROR`: Toggles (red/off) every 500 ms when a motor control error is detected; else off + - `DBG2`: For future use + - `DBG1`: Heartbeat that toggles (green/off) every 500 ms when the firmware loop is running; solid on or off indicates an error + + #### Main Circuit Board Debug LEDs + + - `D2`: UVB FLT: User power VBAT fault: red if the user battery rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off + - `D3`: U24 FLT: User power 24V fault: red if the user 24V rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off + - `D4`: U12A FLT: User power 12VA fault: red if the user 12VA rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off + - `D5`: U12B FLT: User power 12VB fault: red if the user 12VB rail is not enabled or if there has been a fault such as an overcurrent or over temperature event; else off + - `D6`: PWR GD: Main power good indicator: red if any power supply is not enabled or has a fault; else off + - `D7`: 3.3V: Solid green if 3.3V rail is operational; else off + - `D9`: UPWR GD: User power good indicator: red if any of the 4 user power rails are not enabled or have a fault (including and overcurrent on any channel); else off + - `D10`: 5V: Solid green if 5V rail is operational; else off + - `D12`: APWR GD: Auxiliary power good indicator: red if either of the auxiliary power supplies are not enabled or has a fault (Auxiliary power supplies the USER power as well as other PCBA subsystem power rails at 12V and 24V); else off + - `D13`: SPWR GD: System power good indicator: red if either of the system power supplies are not enabled or has a fault (System power supplies the power for PCs, any optional GPU, and the primary network switch); else off + - `D30`: WES BP: Wireless E-Stop Bypass indicator: green if the Wireless E-Stop Bypass is enabled; else off + - `D31`: WES PFLT: Wireless E-Stop Power fault: red if the power supply is not enabled or has a fault; else off + - `D46`: XPWR GD: Expansion power good indicator: red if expansion power is not enabled or has a fault; else off +
\ No newline at end of file diff --git a/components/husky_a300/husky_a300_system_power.mdx b/components/husky_a300/husky_a300_system_power.mdx index 33982c8cb..30b78798e 100644 --- a/components/husky_a300/husky_a300_system_power.mdx +++ b/components/husky_a300/husky_a300_system_power.mdx @@ -1,49 +1,49 @@ -import Admonition from "@theme/Admonition"; - -### System Power - -These 4 connectors collectively provide up to 400 W of power at 12 V for powering computers and network equipment. - -#### SYS1 And SYS2 Pinouts For Computers {#computer-power} - -| Pin | Function / Value | -| :-- | :--------------- | -| 1 | 12 V | -| 2 | 12 V | -| 3 | GND | -| 4 | GND | - -:::info - -SYS1 is always being used by the robot's Primary Computer. - -::: - -#### SYS3 Pinout For A Graphics Card {#graphics-card-power} - -| Pin | Function / Value | -| :-- | :--------------- | -| 1 | 12 V | -| 2 | 12 V | -| 3 | 12 V | -| 4 | GND | -| 5 | GND | -| 6 | GND | - -#### SYS4 System Power For A Network Switch {#network-switch-power} - -This provides 60 W of power at 12 V. - -| Pin | Function / Value | -| :-- | :--------------- | -| 1 | 12 V | -| 2 | GND | - -{(props.robotModel == "A300") && - SYS4 is always being used power the Husky's network switch. -} - -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - Husky AMP and Husky Observer add a wye cable to SYS4. - This wye cable powers the base Husky A300's network switch, as well as a switch in the upper enclosure. -} +import Admonition from "@theme/Admonition"; + +### System Power + +These 4 connectors collectively provide up to 400 W of power at 12 V for powering computers and network equipment. + +#### SYS1 And SYS2 Pinouts For Computers {#computer-power} + +| Pin | Function / Value | +| :-- | :--------------- | +| 1 | 12 V | +| 2 | 12 V | +| 3 | GND | +| 4 | GND | + +:::info + +SYS1 is always being used by the robot's Primary Computer. + +::: + +#### SYS3 Pinout For A Graphics Card {#graphics-card-power} + +| Pin | Function / Value | +| :-- | :--------------- | +| 1 | 12 V | +| 2 | 12 V | +| 3 | 12 V | +| 4 | GND | +| 5 | GND | +| 6 | GND | + +#### SYS4 System Power For A Network Switch {#network-switch-power} + +This provides 60 W of power at 12 V. + +| Pin | Function / Value | +| :-- | :--------------- | +| 1 | 12 V | +| 2 | GND | + +{(props.robotModel == "A300") && + SYS4 is always being used power the Husky's network switch. +} + +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + Husky AMP and Husky Observer add a wye cable to SYS4. + This wye cable powers the base Husky A300's network switch, as well as a switch in the upper enclosure. +} diff --git a/components/husky_a300/husky_a300_whats_included.mdx b/components/husky_a300/husky_a300_whats_included.mdx index c417d779e..5ac81bece 100644 --- a/components/husky_a300/husky_a300_whats_included.mdx +++ b/components/husky_a300/husky_a300_whats_included.mdx @@ -1,20 +1,20 @@ -### What's Included? - -
    -
  • Husky A300 base robot
    • - {((props.robotModel == "AMP") || (props.robotModel == "Observer")) &&
  • Husky AMP's enclosure and sensors installed on top of the Husky A300 base robot.
    • } - {(props.robotModel == "Observer") &&
  • Husky Observer's autonomous wireless charger and stationary dock.
    • } - {(props.robotModel == "Observer") &&
  • Husky Observer's pan-tilt-zoom camera.
    • } -
  • Wireless joystick
    • -
  • Battery charger
    • -
  • Spare parts
    • -
  • Crate, with straps to retain the robot
    • -
- -:::info - -Clearpath Robotics also provides integration services. -Your order may include addional sensors, auxiliary hardware, or software packages. -This additional work will come preinstalled on your robot. - -::: +### What's Included? + +
    +
  • Husky A300 base robot
    • + {((props.robotModel == "AMP") || (props.robotModel == "Observer")) &&
  • Husky AMP's enclosure and sensors installed on top of the Husky A300 base robot.
    • } + {(props.robotModel == "Observer") &&
  • Husky Observer's autonomous wireless charger and stationary dock.
    • } + {(props.robotModel == "Observer") &&
  • Husky Observer's pan-tilt-zoom camera.
    • } +
  • Wireless joystick
    • +
  • Battery charger
    • +
  • Spare parts
    • +
  • Crate, with straps to retain the robot
    • +
+ +:::info + +Clearpath Robotics also provides integration services. +Your order may include addional sensors, auxiliary hardware, or software packages. +This additional work will come preinstalled on your robot. + +::: diff --git a/components/husky_a300/husky_a300_wireless_emergency_stop.mdx b/components/husky_a300/husky_a300_wireless_emergency_stop.mdx index 088bc6c46..3de2e7853 100644 --- a/components/husky_a300/husky_a300_wireless_emergency_stop.mdx +++ b/components/husky_a300/husky_a300_wireless_emergency_stop.mdx @@ -1,26 +1,26 @@ -### Wireless Emergency Stop {#wireless-stop} - -A wireless dual-channel emergency stop can be added to Husky. -This allows you to invoke an emergency stop remotely—_(either through a button press or when the remote unit is out of range)_. -This is in addition to the Husky's built-in Emergency Stop Buttons. -Refer to the User Manual for details on how the Wireless Emergency Stop can be bypassed in certain debugging scenarios. - -The Wireless Emergency Stop can be connected to Husky on the System Interface circuit board at the `W ES` connector, based on the pinout below. - -| W ES Pin | Function / Value | -| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | 24 V, _(fused at 3 A)_ | -| 2 | CAN High: combined with CAN Low, connected to the CAN2 pins on the MCU; see additional notes below | -| 3 | Reset In: Pull to GND for at least 100 ms to restart the robot after all emergency stops have been cleared; equivalent to pressing the Restart Button on Husky | -| 4 | Channel 1 Out, _(24 V)_: normally connected to Channel 1 In; disconnect to trigger an emergency stop | -| 5 | Channel 1 In | -| 6 | GND | -| 7 | CAN Low | -| 8 | GND | -| 9 | Channel 2 Out, _(24 V)_: normally connected to Channel 2 In; disconnect to trigger an emergency stop | -| 10 | Channel 2 In | - -#### Receiver Installation - -In addition to the electrical integration noted above, the wireless receiver will normally require mechanical mounting inside the Husky, along with external mounting of an antenna. -Refer to Wireless Stop receivers and Cable Passthrough for additional details. +### Wireless Emergency Stop {#wireless-stop} + +A wireless dual-channel emergency stop can be added to Husky. +This allows you to invoke an emergency stop remotely—_(either through a button press or when the remote unit is out of range)_. +This is in addition to the Husky's built-in Emergency Stop Buttons. +Refer to the User Manual for details on how the Wireless Emergency Stop can be bypassed in certain debugging scenarios. + +The Wireless Emergency Stop can be connected to Husky on the System Interface circuit board at the `W ES` connector, based on the pinout below. + +| W ES Pin | Function / Value | +| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | 24 V, _(fused at 3 A)_ | +| 2 | CAN High: combined with CAN Low, connected to the CAN2 pins on the MCU; see additional notes below | +| 3 | Reset In: Pull to GND for at least 100 ms to restart the robot after all emergency stops have been cleared; equivalent to pressing the Restart Button on Husky | +| 4 | Channel 1 Out, _(24 V)_: normally connected to Channel 1 In; disconnect to trigger an emergency stop | +| 5 | Channel 1 In | +| 6 | GND | +| 7 | CAN Low | +| 8 | GND | +| 9 | Channel 2 Out, _(24 V)_: normally connected to Channel 2 In; disconnect to trigger an emergency stop | +| 10 | Channel 2 In | + +#### Receiver Installation + +In addition to the electrical integration noted above, the wireless receiver will normally require mechanical mounting inside the Husky, along with external mounting of an antenna. +Refer to Wireless Stop receivers and Cable Passthrough for additional details. diff --git a/components/husky_a300/husky_a300_wiring_diagram.mdx b/components/husky_a300/husky_a300_wiring_diagram.mdx index 3fbe6497c..116b95284 100644 --- a/components/husky_a300/husky_a300_wiring_diagram.mdx +++ b/components/husky_a300/husky_a300_wiring_diagram.mdx @@ -1,28 +1,28 @@ -import Admonition from "@theme/Admonition"; -import ButtonDownloadWiringDiagram from "/components/button_download_wiring_diagram.tsx"; - -### Wiring Diagram {#wiring-diagram} - -
-
- -
Snippet Of The Husky's Wiring Diagram, Showing The Optional 120 Ah Battery
-
-
- - - -Wiring diagrams help diagnose the cause of issues, such as damaged cables or loose connections. -This wiring diagram lists Clearpath's 6 digit item numbers for circuit boards and cables. -The diagram does not include pinouts for individual cables. - - - Please contact our [Support Team](#support) if you need more debugging information, or want a replacement cable. - - -{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && - Refer to the Husky AMP's wiring diagram for details about the additional wiring added for AMP and Observer. -} +import Admonition from "@theme/Admonition"; +import ButtonDownloadWiringDiagram from "/components/button_download_wiring_diagram.tsx"; + +### Wiring Diagram {#wiring-diagram} + +
+
+ +
Snippet Of The Husky's Wiring Diagram, Showing The Optional 120 Ah Battery
+
+
+ + + +Wiring diagrams help diagnose the cause of issues, such as damaged cables or loose connections. +This wiring diagram lists Clearpath's 6 digit item numbers for circuit boards and cables. +The diagram does not include pinouts for individual cables. + + + Please contact our [Support Team](#support) if you need more debugging information, or want a replacement cable. + + +{((props.robotModel == "AMP") || (props.robotModel == "Observer")) && + Refer to the Husky AMP's wiring diagram for details about the additional wiring added for AMP and Observer. +} diff --git a/components/husky_a300/husky_a300_wiring_diagram_amp.mdx b/components/husky_a300/husky_a300_wiring_diagram_amp.mdx index 129c33608..bc2df8401 100644 --- a/components/husky_a300/husky_a300_wiring_diagram_amp.mdx +++ b/components/husky_a300/husky_a300_wiring_diagram_amp.mdx @@ -1,30 +1,30 @@ -import Admonition from "@theme/Admonition"; -import ButtonDownloadWiringDiagram from "/components/button_download_wiring_diagram.tsx"; - -### Wiring Diagram {#wiring-diagram-amp} - -
-
- -
Snippet Of The Wiring Diagram, Showing The Husky Observer's Wireless Charger And Docking Lidar
-
-
- - - -Wiring diagrams help diagnose the cause of issues, such as damaged cables or loose connections. -This wiring diagram lists Clearpath's 6 digit item numbers for circuit boards, electronics, sensors, and cables. -The diagram does not include pinouts for individual cables. - - - Please contact our [Support Team](#support) if you need more debugging information, or want a replacement cable. - - - - The Husky AMP uses a Husky A300 as its base. - This wiring diagram only includes the hardware which converts a Husky A300 base into and AMP or Observer. - Refer to the [Husky A300's Wiring Diagram](#wiring-diagram) for details of how the base robot is wired. - +import Admonition from "@theme/Admonition"; +import ButtonDownloadWiringDiagram from "/components/button_download_wiring_diagram.tsx"; + +### Wiring Diagram {#wiring-diagram-amp} + +
+
+ +
Snippet Of The Wiring Diagram, Showing The Husky Observer's Wireless Charger And Docking Lidar
+
+
+ + + +Wiring diagrams help diagnose the cause of issues, such as damaged cables or loose connections. +This wiring diagram lists Clearpath's 6 digit item numbers for circuit boards, electronics, sensors, and cables. +The diagram does not include pinouts for individual cables. + + + Please contact our [Support Team](#support) if you need more debugging information, or want a replacement cable. + + + + The Husky AMP uses a Husky A300 as its base. + This wiring diagram only includes the hardware which converts a Husky A300 base into and AMP or Observer. + Refer to the [Husky A300's Wiring Diagram](#wiring-diagram) for details of how the base robot is wired. + diff --git a/components/husky_a300/networking/husky_a300_ethernet_connection.mdx b/components/husky_a300/networking/husky_a300_ethernet_connection.mdx index 5aa4e1c62..61a022cf6 100644 --- a/components/husky_a300/networking/husky_a300_ethernet_connection.mdx +++ b/components/husky_a300/networking/husky_a300_ethernet_connection.mdx @@ -1,42 +1,42 @@ -#### Connecting to Husky over an Ethernet Connection {#ethernet-connection} - -Husky can always be accessed over an Ethernet connection, following the steps below. - -1. Open the Rear Charge Port Door on Husky to expose the debug Ethernet port. -1. Connect an Ethernet cable from Husky's debug Ethernet port to your laptop. -1. Set your laptop's IP address and netmask as shown below. - - **IP Address**: 192.168.131.100 - - **Netmask**: 255.255.255.0 -1. Confirm that you can ping Husky from your laptop's terminal window in Linux or the - command prompt in Windows by entering the following command: - ```ping 192.168.131.1``` - The output should be similar to the following. - ``` - Pinging 192.168.131.1 with 32 bytes of data: - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - - Ping statistics for 192.168.131.1: - Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), - Approximate round trip times in milli-seconds: - Minimum = 0ms, Maximum = 0ms, Average = 0ms - ``` -1. Connect to your laptop to the robot using SSH. To do so, execute the following in a terminal window: - ``` - ssh robot@192.168.131.1 - ``` - You will be prompted to enter a password. The default password is `clearpath`. - :::note - All Clearpath robots ship from the factory with their login password set to `clearpath`. - Upon receipt of your robot we recommend changing the password. To change the password, - run the following command on the robot: - ``` - passwd - ``` - This will prompt you to enter the current password, followed by the new password twice. - While typing the passwords in the `passwd` prompt there will be no visual feedback - (e.g. `*` characters). - ::: - +#### Connecting to Husky over an Ethernet Connection {#ethernet-connection} + +Husky can always be accessed over an Ethernet connection, following the steps below. + +1. Open the Rear Charge Port Door on Husky to expose the debug Ethernet port. +1. Connect an Ethernet cable from Husky's debug Ethernet port to your laptop. +1. Set your laptop's IP address and netmask as shown below. + - **IP Address**: 192.168.131.100 + - **Netmask**: 255.255.255.0 +1. Confirm that you can ping Husky from your laptop's terminal window in Linux or the + command prompt in Windows by entering the following command: + ```ping 192.168.131.1``` + The output should be similar to the following. + ``` + Pinging 192.168.131.1 with 32 bytes of data: + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + + Ping statistics for 192.168.131.1: + Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), + Approximate round trip times in milli-seconds: + Minimum = 0ms, Maximum = 0ms, Average = 0ms + ``` +1. Connect to your laptop to the robot using SSH. To do so, execute the following in a terminal window: + ``` + ssh robot@192.168.131.1 + ``` + You will be prompted to enter a password. The default password is `clearpath`. + :::note + All Clearpath robots ship from the factory with their login password set to `clearpath`. + Upon receipt of your robot we recommend changing the password. To change the password, + run the following command on the robot: + ``` + passwd + ``` + This will prompt you to enter the current password, followed by the new password twice. + While typing the passwords in the `passwd` prompt there will be no visual feedback + (e.g. `*` characters). + ::: + diff --git a/components/husky_a300/networking/husky_a300_netplan_wifi_client.mdx b/components/husky_a300/networking/husky_a300_netplan_wifi_client.mdx index 91a837b4a..e89d63793 100644 --- a/components/husky_a300/networking/husky_a300_netplan_wifi_client.mdx +++ b/components/husky_a300/networking/husky_a300_netplan_wifi_client.mdx @@ -1,8 +1,8 @@ -#### Connecting Husky to a Wi-Fi Network {#wifi-client-setup} - -To get Husky connected to your local Wi-Fi network, follow the setup below. - -1. Follow the steps for [Connecting to Husky over an Ethernet Connection](#ethernet-connection). -1. Follow the [Wi-Fi connection](/docs/ros/networking/computer_setup#netplan-wifi) - instructions for setting up the Wi-Fi network. - +#### Connecting Husky to a Wi-Fi Network {#wifi-client-setup} + +To get Husky connected to your local Wi-Fi network, follow the setup below. + +1. Follow the steps for [Connecting to Husky over an Ethernet Connection](#ethernet-connection). +1. Follow the [Wi-Fi connection](/docs/ros/networking/computer_setup#netplan-wifi) + instructions for setting up the Wi-Fi network. + diff --git a/components/husky_a300/networking/husky_a300_peplink_cellular.mdx b/components/husky_a300/networking/husky_a300_peplink_cellular.mdx index e55e957cb..967850423 100644 --- a/components/husky_a300/networking/husky_a300_peplink_cellular.mdx +++ b/components/husky_a300/networking/husky_a300_peplink_cellular.mdx @@ -1,51 +1,51 @@ -#### Connecting Husky to a Cellular Network {#cellular-setup} - -To get Husky AMP or Husky Observer connected to a cellular network, follow the steps below. - -1. Install your SIM card into Husky's router by removing the Husky's - right side panel, removing the cover on the `Cellular SIM` port on the router - inserting the SIM card into slot `A`, and reinstalling the covers. -1. [Connect your laptop to Husky's AMP network](#basic-network-connection). -1. In a web browser, open the configuration page for Husky's router: https://192.168.131.51 - - Username: `admin` - - Default password: `Clearpath1` -1. Click on the `Cellular` link. -
-
- -
Select Cellular
-
-
-1. On the new configuration page, complete the configuration as specified by your - cellular network provider. Ensure that the `Enabled` checkbox is clicked. -
-
- -
Cellular settings
-
-
-1. Click `Save and Apply` and wait for a message confirming that the configuration has been applied. -1. Click on the `Dashboard` tab and confirm that the `Cellular` connection reports as `Connected`. -
-
- -
Cellular Connection Status
-
-
- -:::info - -For more advanced configurations, refer to the `Cellular WAN` section of the -[router's user manual](https://manual.peplink.com/peplink-max-user-manual/). - -::: - +#### Connecting Husky to a Cellular Network {#cellular-setup} + +To get Husky AMP or Husky Observer connected to a cellular network, follow the steps below. + +1. Install your SIM card into Husky's router by removing the Husky's + right side panel, removing the cover on the `Cellular SIM` port on the router + inserting the SIM card into slot `A`, and reinstalling the covers. +1. [Connect your laptop to Husky's AMP network](#basic-network-connection). +1. In a web browser, open the configuration page for Husky's router: https://192.168.131.51 + - Username: `admin` + - Default password: `Clearpath1` +1. Click on the `Cellular` link. +
+
+ +
Select Cellular
+
+
+1. On the new configuration page, complete the configuration as specified by your + cellular network provider. Ensure that the `Enabled` checkbox is clicked. +
+
+ +
Cellular settings
+
+
+1. Click `Save and Apply` and wait for a message confirming that the configuration has been applied. +1. Click on the `Dashboard` tab and confirm that the `Cellular` connection reports as `Connected`. +
+
+ +
Cellular Connection Status
+
+
+ +:::info + +For more advanced configurations, refer to the `Cellular WAN` section of the +[router's user manual](https://manual.peplink.com/peplink-max-user-manual/). + +::: + diff --git a/components/husky_a300/networking/husky_a300_peplink_wifi_ap_connection.mdx b/components/husky_a300/networking/husky_a300_peplink_wifi_ap_connection.mdx index c6552c1b0..337a3640d 100644 --- a/components/husky_a300/networking/husky_a300_peplink_wifi_ap_connection.mdx +++ b/components/husky_a300/networking/husky_a300_peplink_wifi_ap_connection.mdx @@ -1,31 +1,31 @@ -#### Connecting to Husky AMP's Wi-Fi Access Point {#wifi-ap-connection} - -As an alternative to connecting over Ethernet, it is always possible to connect to Husky AMP's -Wi-Fi access point, following the steps below. - -1. Use your laptop to connect to Husky AMP's Wi-Fi network. The Wi-Fi network name (SSID) will be - `cpr_a300_amp_XXXXX`, where `XXXXX` matches the serial number of the Husky AMP. When - prompted, use the password `clearpath`. -1. Confirm that your laptop's Wi-Fi network interface is configured to use DHCP and that it - has been assigned an IP address in the `192.168.131.XXX` range. -1. Confirm that you can ping Husky AMP from your laptop's terminal window in Linux or the - command prompt in Windows by entering the following command: - ```ping 192.168.131.1``` - The output should be similar to the following. - ``` - Pinging 192.168.131.1 with 32 bytes of data: - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 - - Ping statistics for 192.168.131.1: - Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), - Approximate round trip times in milli-seconds: - Minimum = 0ms, Maximum = 0ms, Average = 0ms - ``` -1. Connect to your robot via SSH. To do so, execute the following in a terminal window: - ``` - ssh robot@192.168.131.1 - ``` - +#### Connecting to Husky AMP's Wi-Fi Access Point {#wifi-ap-connection} + +As an alternative to connecting over Ethernet, it is always possible to connect to Husky AMP's +Wi-Fi access point, following the steps below. + +1. Use your laptop to connect to Husky AMP's Wi-Fi network. The Wi-Fi network name (SSID) will be + `cpr_a300_amp_XXXXX`, where `XXXXX` matches the serial number of the Husky AMP. When + prompted, use the password `clearpath`. +1. Confirm that your laptop's Wi-Fi network interface is configured to use DHCP and that it + has been assigned an IP address in the `192.168.131.XXX` range. +1. Confirm that you can ping Husky AMP from your laptop's terminal window in Linux or the + command prompt in Windows by entering the following command: + ```ping 192.168.131.1``` + The output should be similar to the following. + ``` + Pinging 192.168.131.1 with 32 bytes of data: + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + Reply from 192.168.131.1: bytes=32 time<1ms TTL=128 + + Ping statistics for 192.168.131.1: + Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), + Approximate round trip times in milli-seconds: + Minimum = 0ms, Maximum = 0ms, Average = 0ms + ``` +1. Connect to your robot via SSH. To do so, execute the following in a terminal window: + ``` + ssh robot@192.168.131.1 + ``` + diff --git a/components/husky_a300/networking/husky_a300_peplink_wifi_client.mdx b/components/husky_a300/networking/husky_a300_peplink_wifi_client.mdx index fa465396c..6e46a9eba 100644 --- a/components/husky_a300/networking/husky_a300_peplink_wifi_client.mdx +++ b/components/husky_a300/networking/husky_a300_peplink_wifi_client.mdx @@ -1,59 +1,59 @@ -#### Connecting Husky to a Wi-Fi Network {#wifi-client-setup} - -To get Husky AMP or Husky Observer connected to your local Wi-Fi network, follow the steps below. - -1. [Connect your laptop to Husky's AMP network](#basic-network-connection). -1. In a web browser, open the configuration page for Husky's router: https://192.168.131.51 - - Username: `admin` - - Default password: `Clearpath1` -1. Click on either the `Wi-Fi WAN on 2.4 GHz` or `Wi-Fi WAN on 5GHz` link, depending on - whether you are setting up a 2.4 GHz or 5 GHz connection. -
-
- -
Select 2.4 GHz for configuration
-
-
-1. On the new configuration page, scroll to the bottom; under `Wi-Fi Connection Profiles` - click `Create Profile`. -
-
- -
Create network profile
-
-
-1. Enter the SSID and password for the network, then click OK. -
-
- -
Configure network profile
-
-
-1. Click `Save and Apply` and wait for a message confirming that the configuration has been applied. -1. Click on the `Dashboard` tab and confirm that the configured WAN connection reports as `Connected`. -
-
- -
WAN Connection Status
-
-
- -:::info - -For more advanced configurations, refer to the `Wi-Fi WAN` section of the -[router's user manual](https://manual.peplink.com/peplink-max-user-manual/). - -::: - +#### Connecting Husky to a Wi-Fi Network {#wifi-client-setup} + +To get Husky AMP or Husky Observer connected to your local Wi-Fi network, follow the steps below. + +1. [Connect your laptop to Husky's AMP network](#basic-network-connection). +1. In a web browser, open the configuration page for Husky's router: https://192.168.131.51 + - Username: `admin` + - Default password: `Clearpath1` +1. Click on either the `Wi-Fi WAN on 2.4 GHz` or `Wi-Fi WAN on 5GHz` link, depending on + whether you are setting up a 2.4 GHz or 5 GHz connection. +
+
+ +
Select 2.4 GHz for configuration
+
+
+1. On the new configuration page, scroll to the bottom; under `Wi-Fi Connection Profiles` + click `Create Profile`. +
+
+ +
Create network profile
+
+
+1. Enter the SSID and password for the network, then click OK. +
+
+ +
Configure network profile
+
+
+1. Click `Save and Apply` and wait for a message confirming that the configuration has been applied. +1. Click on the `Dashboard` tab and confirm that the configured WAN connection reports as `Connected`. +
+
+ +
WAN Connection Status
+
+
+ +:::info + +For more advanced configurations, refer to the `Wi-Fi WAN` section of the +[router's user manual](https://manual.peplink.com/peplink-max-user-manual/). + +::: + diff --git a/components/maintenance/_wd_ssd_critical_update.mdx b/components/maintenance/_wd_ssd_critical_update.mdx index af280c77f..4085b0810 100644 --- a/components/maintenance/_wd_ssd_critical_update.mdx +++ b/components/maintenance/_wd_ssd_critical_update.mdx @@ -1,12 +1,12 @@ -:::warning - -Some computers shipped with a WD Blue SA510 SATA SSD, for which -the manufacturer has posted a -[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). - -Failure to perform the firmware update could result in permanent failure of the SSD. - -::: - -[See these instructions](../../accessories/computers/mini_itx#wd-firmware-update) to check if your SSD is +:::warning + +Some computers shipped with a WD Blue SA510 SATA SSD, for which +the manufacturer has posted a +[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). + +Failure to perform the firmware update could result in permanent failure of the SSD. + +::: + +[See these instructions](../../accessories/computers/mini_itx#wd-firmware-update) to check if your SSD is affected and to perform the update. \ No newline at end of file diff --git a/components/maintenance/wd_ssd_critical_update.mdx b/components/maintenance/wd_ssd_critical_update.mdx index 138740e76..9e28b40b9 100644 --- a/components/maintenance/wd_ssd_critical_update.mdx +++ b/components/maintenance/wd_ssd_critical_update.mdx @@ -1,34 +1,34 @@ -### WD Blue SA510 SATA SSD Critical Firmware Update {#wd-firmware-update} - -:::warning - -Some computers shipped with a WD Blue SA510 SATA SSD, for which -the manufacturer has posted a -[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). - -Failure to perform the firmware update could result in permanent failure of the SSD. - -::: - -#### How to check if your SSD is affected - -1. From the command line, run `sudo fdisk -l` to check your SSD model and check the - "Disk model" and mount location. If the disk model is in the - [list of affected models](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2), - then proceed with the following steps. Otherwise, no further action is required. -1. Check the firmware version, which may require the installation of `smartmontools`: - ``` - sudo apt install smartmontools - sudo smartctl --xall /dev/sda2 | grep -i firmware - ``` - If the firmware version is **v52046100**, no further action is required. Otherwise, - proceed with the remaining steps to update the firmware. - -#### How to update the firmware on affected SSDs - -1. Create an OS image backup of the SSD ([ROS 1 backup details here](/docs_robots/legacy/ros1_robots/outdoor_robots/husky/tutorials_husky#performing-a-backup), - [ROS 2 backup details here](/docs/ros/installation/upgrading#saving-a-hard-drive-image)). -1. Remove the SSD from the robot. Ensure that you use an ESD grounded wrist strap when handling SSD or PCB components. -1. Use a USB SSD dock and a Windows computer to perform the update by [following the vendor's instructions](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). -1. Re-install the SSD into the robot. +### WD Blue SA510 SATA SSD Critical Firmware Update {#wd-firmware-update} + +:::warning + +Some computers shipped with a WD Blue SA510 SATA SSD, for which +the manufacturer has posted a +[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). + +Failure to perform the firmware update could result in permanent failure of the SSD. + +::: + +#### How to check if your SSD is affected + +1. From the command line, run `sudo fdisk -l` to check your SSD model and check the + "Disk model" and mount location. If the disk model is in the + [list of affected models](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2), + then proceed with the following steps. Otherwise, no further action is required. +1. Check the firmware version, which may require the installation of `smartmontools`: + ``` + sudo apt install smartmontools + sudo smartctl --xall /dev/sda2 | grep -i firmware + ``` + If the firmware version is **v52046100**, no further action is required. Otherwise, + proceed with the remaining steps to update the firmware. + +#### How to update the firmware on affected SSDs + +1. Create an OS image backup of the SSD ([ROS 1 backup details here](/docs_robots/legacy/ros1_robots/outdoor_robots/husky/tutorials_husky#performing-a-backup), + [ROS 2 backup details here](/docs/ros/installation/upgrading#saving-a-hard-drive-image)). +1. Remove the SSD from the robot. Ensure that you use an ESD grounded wrist strap when handling SSD or PCB components. +1. Use a USB SSD dock and a Windows computer to perform the update by [following the vendor's instructions](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). +1. Re-install the SSD into the robot. 1. Verify all data is still present and that the SSD works as expected. \ No newline at end of file diff --git a/components/supported_platforms.mdx b/components/supported_platforms.mdx index c812a3318..06d647aac 100644 --- a/components/supported_platforms.mdx +++ b/components/supported_platforms.mdx @@ -1,39 +1,39 @@ -## Supported Platforms {#supported-platforms} - -| Platform | Platform code | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | -|:--------- |:------------- |:---------------- |:---------------- |:--------------- |:--------------- | -| Husky | A200 | Yes (as of 0.1) | No | Yes (as of 2.0) | Coming Soon | -| | A300 | No | No | Yes (as of 2.0) | Coming Soon | -| Jackal | J100 | Yes (as of 0.1) | No | Yes (as of 2.3) | Coming Soon | -| Warthog | W200 | Yes (as of 0.2) | No | Yes (as of 2.6) | Coming Soon | -| Dingo | DD100 | Yes (as of 0.3) | No | Yes (as of 2.3) | Coming Soon | -| | DO100 | Yes (as of 1.0) | No | Yes (as of 2.3) | Coming Soon | -| | DD150 | Yes (as of 0.3) | No | Yes (as of 2.3) | Coming Soon | -| | DO150 | Yes (as of 1.0) | No | Yes (as of 2.3) | Coming Soon | -| Ridgeback | R100 | Yes (as of 0.3) | No | Yes (as of 2.3) | Coming Soon | -| Boxer | B250 | No | No | No | No | - -## Supported ROS 2 Middleware {#supported-middleware} - -:::note - -Most Clearpath platforms use Micro ROS in their MCU firmware, which limits the ability to use -middleware implementations other than `Fast DDS`. - -If you need your Clearpath robot to interact with systems that rely on unsupported middleware, please -refer to [ROS' middleware documentation](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Different-Middleware-Vendors.html) -for information on cross-vendor commuication. - -::: - -| Platform | Platform code | Fast DDS | CycloneDDS | Connext DDS | GurumDDS | Zenoh | -|:--------- |:------------- |:----------- |:---------- |:----------- |:-------- | :-------- | -| Husky | A200 | Yes | Yes | No | No | Yes | -| | A300 | Yes | No | No | No | No | -| Jackal | J100 | Yes | No | No | No | No | -| Warthog | W200 | Coming Soon | No | No | No | No | -| Dingo | DD100 | Yes | No | No | No | No | -| | DO100 | Yes | No | No | No | No | -| | DD150 | Yes | No | No | No | No | -| | DO150 | Yes | No | No | No | No | -| Ridgeback | R100 | Yes | No | No | No | No | +## Supported Platforms {#supported-platforms} + +| Platform | Platform code | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | +|:--------- |:------------- |:---------------- |:---------------- |:--------------- |:--------------- | +| Husky | A200 | Yes (as of 0.1) | No | Yes (as of 2.0) | Coming Soon | +| | A300 | No | No | Yes (as of 2.0) | Coming Soon | +| Jackal | J100 | Yes (as of 0.1) | Source | Yes (as of 2.3) | Coming Soon | +| Warthog | W200 | Yes (as of 0.2) | No | Yes (as of 2.6) | Coming Soon | +| Dingo | DD100 | Yes (as of 0.3) | Source | Yes (as of 2.3) | Coming Soon | +| | DO100 | Yes (as of 1.0) | Source | Yes (as of 2.3) | Coming Soon | +| | DD150 | Yes (as of 0.3) | Source | Yes (as of 2.3) | Coming Soon | +| | DO150 | Yes (as of 1.0) | Source | Yes (as of 2.3) | Coming Soon | +| Ridgeback | R100 | Yes (as of 0.3) | Source | Yes (as of 2.3) | Coming Soon | +| Boxer | B250 | No | No | No | No | + +## Supported ROS 2 Middleware {#supported-middleware} + +:::note + +Most Clearpath platforms use Micro ROS in their MCU firmware, which limits the ability to use +middleware implementations other than `Fast DDS`. + +If you need your Clearpath robot to interact with systems that rely on unsupported middleware, please +refer to [ROS' middleware documentation](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Different-Middleware-Vendors.html) +for information on cross-vendor commuication. + +::: + +| Platform | Platform code | Fast DDS | CycloneDDS | Connext DDS | GurumDDS | Zenoh | +|:--------- |:------------- |:----------- |:---------- |:----------- |:-------- | :-------- | +| Husky | A200 | Yes | Yes | No | No | Yes | +| | A300 | Yes | No | No | No | No | +| Jackal | J100 | Yes | No | No | No | No | +| Warthog | W200 | Yes | No | No | No | No | +| Dingo | DD100 | Yes | No | No | No | No | +| | DO100 | Yes | No | No | No | No | +| | DD150 | Yes | No | No | No | No | +| | DO150 | Yes | No | No | No | No | +| Ridgeback | R100 | Yes | No | No | No | No | diff --git a/components/supported_sensors.mdx b/components/supported_sensors.mdx index a1116339b..cdfa87571 100644 --- a/components/supported_sensors.mdx +++ b/components/supported_sensors.mdx @@ -1,80 +1,80 @@ -## Supported Sensors {#supported-sensors} - -:::note - -While some sensor drivers may support other sensor models, the table below represents the -sensors that have been validated by Clearpath. - -::: - -:::note - -Debian drivers are automatically installed on robots as part of the -[Clearpath Robot Metapackage](/docs/ros/installation/robot#clearpath-robot-metapackage). - -::: - -### 2D Lidars - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------- | -| [SICK LMS-111/LMS-151](/docs_robots/accessories/sensors/lidar_2d/sick_lms111) | Debian | Debian | Debian | Debian | [LMS1xx](https://github.com/clearpathrobotics/LMS1xx) | -| [Hokuyo UST10-LX](/docs_robots/accessories/sensors/lidar_2d/hokuyo_ust10_lx) | Debian | Debian | Debian | Debian | [urg_node](https://github.com/ros-drivers/urg_node) | -| [Hokuyo UST20-LX](/docs_robots/accessories/sensors/lidar_2d/hokuyo_ust20_lx) | Debian | Debian | Debian | Debian | [urg_node](https://github.com/ros-drivers/urg_node) | -| [Hokuyo UST30-LX](/docs_robots/accessories/sensors/lidar_2d/hokuyo_ust30_lx) | Debian | Debian | Debian | Debian | [urg_node](https://github.com/ros-drivers/urg_node) | - -### 3D Lidars - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:--------------------------------------------------------- | -| [Velodyne Puck](/docs_robots/accessories/sensors/lidar_3d/velodyne_puck) | Debian | Debian | Debian | Debian | [Velodyne](https://github.com/ros-drivers/velodyne) | -| [Ouster OS-1](/docs_robots/accessories/sensors/lidar_3d/ouster) | Debian | Debian | Debian | Debian | [Ouster](https://github.com/ouster-lidar/ouster-ros) | -| Seyond Robin | Source | Source | Source | Source | [Seyond](https://github.com/Seyond-Inc/seyond_ros_driver) | - -### IMUs - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:------------------------------------------------------------------------- | -| [MicroStrain 3DM-GX5](/docs_robots/accessories/sensors/imu/microstrain_3dm_gx5) | Debian | Debian | Debian | Debian | [LORD Inertial](https://github.com/LORD-MicroStrain/microstrain_inertial) | -| [MicroStrain 3DM-GQ7](/docs_robots/accessories/sensors/gps/microstrain_gq7) | Debian | Debian | Debian | Debian | [LORD Inertial](https://github.com/LORD-MicroStrain/microstrain_inertial) | -| [Redshift Labs UM7](/docs_robots/accessories/sensors/imu/redshift_labs_um7) | Debian | Debian | Debian | Debian | [UM7](https://github.com/ros-drivers/um7) | -| CH Robotics UM6 | Debian | Debian | Debian | Debian | [UM7](https://github.com/ros-drivers/um7) | -| Phidgets IMU | Unsupported | Unsupported | Debian | Debian | [Phidgets](https://github.com/ros-drivers/phidgets_drivers) | - - -### GPS - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:------------------------------------------------------------------------- | -| [MicroStrain 3DM-GQ7](/docs_robots/accessories/sensors/gps/microstrain_gq7) | Debian | Debian | Debian | Debian | [LORD Inertial](https://github.com/LORD-MicroStrain/microstrain_inertial) | -| [Garmin GPS 18x](/docs_robots/accessories/sensors/gps/garmin_gps_18x) | Debian | Debian | Debian | Debian | [NMEA Navsat Driver](https://github.com/ros-drivers/nmea_navsat_driver) | -| [Swift Navigation Duro](/docs_robots/accessories/sensors/gps/swift_navigation_duro) | Source | Source | Source | Source | [Duro GPS Driver](https://github.com/szenergy/duro_gps_driver) | -| NovAtel SMART6 and SMART7 | Debian | Debian | Debian | Debian | [NMEA Navsat Driver](https://github.com/ros-drivers/nmea_navsat_driver) | - -### Inertial Navigation Sensors - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------------------------- | -| [Fixposition Vision-RTK 2](/docs_robots/accessories/sensors/ins/fixposition) | Source | Source | Source | Source | [Fixposition Driver](https://github.com/fixposition/fixposition_driver) | - -### Optical Cameras - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------- | -| [Axis F1035-E](/docs_robots/accessories/sensors/cameras/axis_f1035_e) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | -| [Axis M5525-E](/docs_robots/accessories/sensors/cameras/axis_m5525_e) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | -| [Axis M5526-E](/docs_robots/accessories/sensors/cameras/axis_m5526_e) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | -| [Axis Q6225-LE-E](/docs_robots/accessories/sensors/cameras/axis_q6225_le) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | -| [Flir Blackfly S](/docs_robots/accessories/sensors/cameras/flir_blackfly_s) | Debian | Debian | Debian | Debian | [flir_camera_driver](https://github.com/ros-drivers/flir_camera_driver) | - -### Depth Cameras - -| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | -|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------- | -| [Intel Realsense D435](/docs_robots/accessories/sensors/cameras/realsense_d435) | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | -| [Intel Realsense D435i](/docs_robots/accessories/sensors/cameras/realsense_d435) | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | -| Intel Realsense D415 | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | -| Intel Realsense D455 | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | -| Intel Realsense D456 | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | -| [Luxonis OAK-D](/docs_robots/accessories/sensors/cameras/luxonis_oakd) | Debian | Debian | Debian | Debian | [depthai-ros](https://github.com/luxonis/depthai-ros.git) | -| [Stereolabs Zed 2](/docs_robots/accessories/sensors/cameras/stereolabs_zed_2) | Source | Source | Source | Source | [zed-ros2-wrapper](https://github.com/stereolabs/zed-ros2-wrapper.git) | +## Supported Sensors {#supported-sensors} + +:::note + +While some sensor drivers may support other sensor models, the table below represents the +sensors that have been validated by Clearpath. + +::: + +:::note + +Debian drivers are automatically installed on robots as part of the +[Clearpath Robot Metapackage](/docs/ros/installation/robot#clearpath-robot-metapackage). + +::: + +### 2D Lidars + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------- | +| [SICK LMS-111/LMS-151](/docs_robots/accessories/sensors/lidar_2d/sick_lms111) | Debian | Debian | Debian | Debian | [LMS1xx](https://github.com/clearpathrobotics/LMS1xx) | +| [Hokuyo UST10-LX](/docs_robots/accessories/sensors/lidar_2d/hokuyo_ust10_lx) | Debian | Debian | Debian | Debian | [urg_node](https://github.com/ros-drivers/urg_node) | +| [Hokuyo UST20-LX](/docs_robots/accessories/sensors/lidar_2d/hokuyo_ust20_lx) | Debian | Debian | Debian | Debian | [urg_node](https://github.com/ros-drivers/urg_node) | +| [Hokuyo UST30-LX](/docs_robots/accessories/sensors/lidar_2d/hokuyo_ust30_lx) | Debian | Debian | Debian | Debian | [urg_node](https://github.com/ros-drivers/urg_node) | + +### 3D Lidars + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:--------------------------------------------------------- | +| [Velodyne Puck](/docs_robots/accessories/sensors/lidar_3d/velodyne_puck) | Debian | Debian | Debian | Debian | [Velodyne](https://github.com/ros-drivers/velodyne) | +| [Ouster OS-1](/docs_robots/accessories/sensors/lidar_3d/ouster) | Debian | Debian | Debian | Debian | [Ouster](https://github.com/ouster-lidar/ouster-ros) | +| Seyond Robin | Source | Source | Source | Source | [Seyond](https://github.com/Seyond-Inc/seyond_ros_driver) | + +### IMUs + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:------------------------------------------------------------------------- | +| [MicroStrain 3DM-GX5](/docs_robots/accessories/sensors/imu/microstrain_3dm_gx5) | Debian | Debian | Debian | Debian | [LORD Inertial](https://github.com/LORD-MicroStrain/microstrain_inertial) | +| [MicroStrain 3DM-GQ7](/docs_robots/accessories/sensors/gps/microstrain_gq7) | Debian | Debian | Debian | Debian | [LORD Inertial](https://github.com/LORD-MicroStrain/microstrain_inertial) | +| [Redshift Labs UM7](/docs_robots/accessories/sensors/imu/redshift_labs_um7) | Debian | Debian | Debian | Debian | [UM7](https://github.com/ros-drivers/um7) | +| CH Robotics UM6 | Debian | Debian | Debian | Debian | [UM7](https://github.com/ros-drivers/um7) | +| Phidgets IMU | Unsupported | Unsupported | Debian | Debian | [Phidgets](https://github.com/ros-drivers/phidgets_drivers) | + + +### GPS + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:------------------------------------------------------------------------- | +| [MicroStrain 3DM-GQ7](/docs_robots/accessories/sensors/gps/microstrain_gq7) | Debian | Debian | Debian | Debian | [LORD Inertial](https://github.com/LORD-MicroStrain/microstrain_inertial) | +| [Garmin GPS 18x](/docs_robots/accessories/sensors/gps/garmin_gps_18x) | Debian | Debian | Debian | Debian | [NMEA Navsat Driver](https://github.com/ros-drivers/nmea_navsat_driver) | +| [Swift Navigation Duro](/docs_robots/accessories/sensors/gps/swift_navigation_duro) | Source | Source | Source | Source | [Duro GPS Driver](https://github.com/szenergy/duro_gps_driver) | +| NovAtel SMART6 and SMART7 | Debian | Debian | Debian | Debian | [NMEA Navsat Driver](https://github.com/ros-drivers/nmea_navsat_driver) | + +### Inertial Navigation Sensors + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------------------------- | +| [Fixposition Vision-RTK 2](/docs_robots/accessories/sensors/ins/fixposition) | Source | Source | Source | Source | [Fixposition Driver](https://github.com/fixposition/fixposition_driver) | + +### Optical Cameras + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------- | +| [Axis F1035-E](/docs_robots/accessories/sensors/cameras/axis_f1035_e) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | +| [Axis M5525-E](/docs_robots/accessories/sensors/cameras/axis_m5525_e) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | +| [Axis M5526-E](/docs_robots/accessories/sensors/cameras/axis_m5526_e) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | +| [Axis Q6225-LE-E](/docs_robots/accessories/sensors/cameras/axis_q6225_le) | Debian | Debian | Debian | Debian | [axis_camera](https://github.com/ros-drivers/axis_camera.git) | +| [Flir Blackfly S](/docs_robots/accessories/sensors/cameras/flir_blackfly_s) | Debian | Debian | Debian | Debian | [flir_camera_driver](https://github.com/ros-drivers/flir_camera_driver) | + +### Depth Cameras + +| Sensor | Humble (`amd64`) | Humble (`arm64`) | Jazzy (`amd64`) | Jazzy (`arm64`) | Source | +|:------------------------------------------------------------------------------------ |:---------------- |:---------------- |:--------------- |:--------------- |:----------------------------------------------------- | +| [Intel Realsense D435](/docs_robots/accessories/sensors/cameras/realsense_d435) | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | +| [Intel Realsense D435i](/docs_robots/accessories/sensors/cameras/realsense_d435) | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | +| Intel Realsense D415 | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | +| Intel Realsense D455 | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | +| Intel Realsense D456 | Debian | Debian | Debian | Debian | [Realsense](https://github.com/clearpathrobotics/realsense_ros) | +| [Luxonis OAK-D](/docs_robots/accessories/sensors/cameras/luxonis_oakd) | Debian | Debian | Debian | Debian | [depthai-ros](https://github.com/luxonis/depthai-ros.git) | +| [Stereolabs Zed 2](/docs_robots/accessories/sensors/cameras/stereolabs_zed_2) | Source | Source | Source | Source | [zed-ros2-wrapper](https://github.com/stereolabs/zed-ros2-wrapper.git) | diff --git a/docs_indoornav_user_manual/api.mdx b/docs_indoornav_user_manual/api.mdx index e0741f809..cb41c3643 100644 --- a/docs_indoornav_user_manual/api.mdx +++ b/docs_indoornav_user_manual/api.mdx @@ -1,139 +1,139 @@ ---- -title: "Appendix A: IndoorNav ROS 2 API" -sidebar_label: "Appendix A: IndoorNav ROS 2 API" -sidebar_position: 6 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -In addition to the Web GUI, IndoorNav provides a ROS 2 API for -programmatic interactions. Documentation for this API is included in the -`clearpath-api` package, installable with `apt`: - -```bash -sudo apt install clearpath-api -``` - -Once the package is installed, the documentation can be found at -`/opt/clearpath/ros2-api-1.3.3/share/public`. Alternatively, the -documentation can be downloaded directly from -[docs.ottomotors.com](https://file-share.ottomotors.com/remote.php/webdav/OTTO%20Motors/Software%20Releases/v2.22/Clearpath_API_html_PDF_2.22.zip) -(requires an OTTO Motors account to log in). - -## API Summary - -The ROS 2 API is separated into 3 main categories, each operating on a -separate ROS 2 Domain, as outlined in the table below: - -_ROS 2 API Domain IDs_ - -| Domain ID | Description | -|-------------|--------------| -| 100 | Fleet API | -| 110 | Autonomy API | -| 95 | Platform API | - -The Fleet API is intended to allow the robot to be controlled by an -external fleet manager. - -The Autonomy API enables control of a single robot's autonomy and -navigation. - -The Platform API is not available for use with IndoorNav. Instead of -using the Platform API, developers should use the base robot's ROS 1 -nodes to interact with the robot hardware. - -Additional details on the Fleet, Autonomy, and Platform APIs can be -found on -[docs.ottomotors.com](https://docs.ottomotors.com/Archive/2-22/out/en/51722-52217-robot-fleet-api.html). - -## API Examples - -OTTO Motors provides examples of working with their ROS 2 API. These -examples can be found in -`/opt/clearpath/ros2-api-1.3.3/share/clearpath_api/examples/` - -To build the examples, create a Colcon workspace, copy (or symlink) the -examples folder into the `src` folder, and build using the -`colcon build` command: - -```bash -mkdir -p $HOME/example_ws/src -cd $HOME/example_ws/src -ln -s /opt/clearpath/ros2-api-1.3.3/share/clearpath_api/examples/ $(pwd)/examples -cd .. -source /opt/ros/foxy/setup.bash -source /opt/clearpath/ros2-api-1.3.3/local_setup.bash -colcon build -``` - -The `examples` folder contains 3 programs: - -- `send_move_goal`: command the robot to drive to an (X, Y, Yaw) position on the map -- `monitor_odom_intent`: print the robot's odometry and planning data as it navigates -- `get_map_info`: get information about the map saved on the robot - -:::note - -At the time of writing there is a known bug in the `get_map_info` -example; it always returns an empty array. This will be corrected ASAP. - -::: - -Refer to the source code for the examples for more information about -their use. All examples should be run using the Fleet API domain ID. - -## Accessing Noetic Topics in ROS 2 - -The Clearpath Robotics base platform is configured to bridge sensor -data, velocity control, wireless connection status, power information, -and other basic topics into ROS 2 on domain ID 121. The bridged topics -are prefaced with the robot's hostname (with any hyphens replaced with -underscores). For example: - -```bash -export ROS_DOMAIN_ID=121 -ros2 topic list -/cpr_dora/battery_status -/cpr_dora/cmd_vel -/cpr_dora/front/scan -/cpr_dora/gx5/imu/data -/cpr_dora/imu/data -/cpr_dora/navsat/fix -/cpr_dora/rear/scan -/cpr_dora/wireless/connected -``` - -Publishing to the `{hostname}/cmd_vel` topic will drive the robot: - -```bash -ros2 topic pub /cpr_dora/cmd_vel geometry_msgs/msg/Twist '{linear: {x: 0.1}}' -r 10 -``` - -All other topics are read-only and will publish sensor/power/wireless -information at the same rate as their ROS 1 topics. - -## Using the ROS 2 API with ROS Noetic - -:::note - -At present the ROS 2 API is unstable when bridged into ROS 1 Noetic. You -are welcome to experiment with developing ROS 1 nodes that use the -bridged topics, but Clearpath Robotics can only offer minimal support. - -::: - -To enable bridging the ROS 2 Fleet and Platform APIs into the ROS 1 Noetic -master, set the `INDOORNAV_ENABLE_ROS2_TO_ROS1_BRIDGE` envar to `1` in -`/etc/ros/setup.bash`: - -```bash -export INDOORNAV_ENABLE_ROS2_TO_ROS1_BRIDGE=1 -``` - -This will start 2 `ros1_bridge` nodes (one for domain 110 and one for -domain 95). Bridged topics will be visible in the `fleet_api` and -`autonomy_api` namespaces when `rostopic list` is run. - -You will need to build or install the `clearpath_api` messages and +--- +title: "Appendix A: IndoorNav ROS 2 API" +sidebar_label: "Appendix A: IndoorNav ROS 2 API" +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +In addition to the Web GUI, IndoorNav provides a ROS 2 API for +programmatic interactions. Documentation for this API is included in the +`clearpath-api` package, installable with `apt`: + +```bash +sudo apt install clearpath-api +``` + +Once the package is installed, the documentation can be found at +`/opt/clearpath/ros2-api-1.3.3/share/public`. Alternatively, the +documentation can be downloaded directly from +[docs.ottomotors.com](https://file-share.ottomotors.com/remote.php/webdav/OTTO%20Motors/Software%20Releases/v2.22/Clearpath_API_html_PDF_2.22.zip) +(requires an OTTO Motors account to log in). + +## API Summary + +The ROS 2 API is separated into 3 main categories, each operating on a +separate ROS 2 Domain, as outlined in the table below: + +_ROS 2 API Domain IDs_ + +| Domain ID | Description | +|-------------|--------------| +| 100 | Fleet API | +| 110 | Autonomy API | +| 95 | Platform API | + +The Fleet API is intended to allow the robot to be controlled by an +external fleet manager. + +The Autonomy API enables control of a single robot's autonomy and +navigation. + +The Platform API is not available for use with IndoorNav. Instead of +using the Platform API, developers should use the base robot's ROS 1 +nodes to interact with the robot hardware. + +Additional details on the Fleet, Autonomy, and Platform APIs can be +found on +[docs.ottomotors.com](https://docs.ottomotors.com/Archive/2-22/out/en/51722-52217-robot-fleet-api.html). + +## API Examples + +OTTO Motors provides examples of working with their ROS 2 API. These +examples can be found in +`/opt/clearpath/ros2-api-1.3.3/share/clearpath_api/examples/` + +To build the examples, create a Colcon workspace, copy (or symlink) the +examples folder into the `src` folder, and build using the +`colcon build` command: + +```bash +mkdir -p $HOME/example_ws/src +cd $HOME/example_ws/src +ln -s /opt/clearpath/ros2-api-1.3.3/share/clearpath_api/examples/ $(pwd)/examples +cd .. +source /opt/ros/foxy/setup.bash +source /opt/clearpath/ros2-api-1.3.3/local_setup.bash +colcon build +``` + +The `examples` folder contains 3 programs: + +- `send_move_goal`: command the robot to drive to an (X, Y, Yaw) position on the map +- `monitor_odom_intent`: print the robot's odometry and planning data as it navigates +- `get_map_info`: get information about the map saved on the robot + +:::note + +At the time of writing there is a known bug in the `get_map_info` +example; it always returns an empty array. This will be corrected ASAP. + +::: + +Refer to the source code for the examples for more information about +their use. All examples should be run using the Fleet API domain ID. + +## Accessing Noetic Topics in ROS 2 + +The Clearpath Robotics base platform is configured to bridge sensor +data, velocity control, wireless connection status, power information, +and other basic topics into ROS 2 on domain ID 121. The bridged topics +are prefaced with the robot's hostname (with any hyphens replaced with +underscores). For example: + +```bash +export ROS_DOMAIN_ID=121 +ros2 topic list +/cpr_dora/battery_status +/cpr_dora/cmd_vel +/cpr_dora/front/scan +/cpr_dora/gx5/imu/data +/cpr_dora/imu/data +/cpr_dora/navsat/fix +/cpr_dora/rear/scan +/cpr_dora/wireless/connected +``` + +Publishing to the `{hostname}/cmd_vel` topic will drive the robot: + +```bash +ros2 topic pub /cpr_dora/cmd_vel geometry_msgs/msg/Twist '{linear: {x: 0.1}}' -r 10 +``` + +All other topics are read-only and will publish sensor/power/wireless +information at the same rate as their ROS 1 topics. + +## Using the ROS 2 API with ROS Noetic + +:::note + +At present the ROS 2 API is unstable when bridged into ROS 1 Noetic. You +are welcome to experiment with developing ROS 1 nodes that use the +bridged topics, but Clearpath Robotics can only offer minimal support. + +::: + +To enable bridging the ROS 2 Fleet and Platform APIs into the ROS 1 Noetic +master, set the `INDOORNAV_ENABLE_ROS2_TO_ROS1_BRIDGE` envar to `1` in +`/etc/ros/setup.bash`: + +```bash +export INDOORNAV_ENABLE_ROS2_TO_ROS1_BRIDGE=1 +``` + +This will start 2 `ros1_bridge` nodes (one for domain 110 and one for +domain 95). Bridged topics will be visible in the `fleet_api` and +`autonomy_api` namespaces when `rostopic list` is run. + +You will need to build or install the `clearpath_api` messages and service definitions for Noetic. \ No newline at end of file diff --git a/docs_indoornav_user_manual/base_robot_config/_category_.json b/docs_indoornav_user_manual/base_robot_config/_category_.json index df114c9b3..c79acf89a 100644 --- a/docs_indoornav_user_manual/base_robot_config/_category_.json +++ b/docs_indoornav_user_manual/base_robot_config/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Base Robot Config", - "position": 3 +{ + "label": "Base Robot Config", + "position": 3 } \ No newline at end of file diff --git a/docs_indoornav_user_manual/base_robot_config/config_apt_rosdep.mdx b/docs_indoornav_user_manual/base_robot_config/config_apt_rosdep.mdx index ce76ca5b1..e78916344 100644 --- a/docs_indoornav_user_manual/base_robot_config/config_apt_rosdep.mdx +++ b/docs_indoornav_user_manual/base_robot_config/config_apt_rosdep.mdx @@ -1,66 +1,66 @@ ---- -title: APT and Rosdep Configuration -sidebar_label: APT and Rosdep Configuration -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -To install the IndoorNav software on your robot you must add the ROS 1, -ROS 2, and Clearpath Robotics package servers to your apt configuration. -This is normally done automatically by Clearpath's OS installation -media, but if you are missing any of these sources, use the following -commands to add them - -**ROS 1 Noetic** - -```bash -sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' -curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - -sudo apt-get update -``` - -**ROS 2 Foxy** - -```bash -echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null -sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg -sudo apt-get update -``` - -**Clearpath Robotics** - -```bash -sudo sh -c 'echo "deb https://packages.clearpathrobotics.com/stable/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/clearpath-latest.list' -wget https://packages.clearpathrobotics.com/public.key -O - | sudo apt-key add - -sudo apt-get update -``` - -Once you have enabled the necessary package sources, make sure rosdep -can resolve all the necessary dependencies: - -```bash -sudo wget https://raw.githubusercontent.com/clearpathrobotics/public-rosdistro/master/rosdep/50-clearpath.list -O /etc/ros/rosdep/sources.list.d/50-clearpath.list -rosdep update -``` - -:::note - -Complete ROS Noetic installation instructions can be found at -http://wiki.ros.org/noetic/Installation/Ubuntu - -::: - -:::note - -Complete ROS 2 Foxy installation instructions can be found at -https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html - -::: - -:::note - -Complete instructions for Clearpath APT sources can be found at -http://packages.clearpathrobotics.com - -::: +--- +title: APT and Rosdep Configuration +sidebar_label: APT and Rosdep Configuration +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +To install the IndoorNav software on your robot you must add the ROS 1, +ROS 2, and Clearpath Robotics package servers to your apt configuration. +This is normally done automatically by Clearpath's OS installation +media, but if you are missing any of these sources, use the following +commands to add them + +**ROS 1 Noetic** + +```bash +sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' +curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - +sudo apt-get update +``` + +**ROS 2 Foxy** + +```bash +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null +sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg +sudo apt-get update +``` + +**Clearpath Robotics** + +```bash +sudo sh -c 'echo "deb https://packages.clearpathrobotics.com/stable/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/clearpath-latest.list' +wget https://packages.clearpathrobotics.com/public.key -O - | sudo apt-key add - +sudo apt-get update +``` + +Once you have enabled the necessary package sources, make sure rosdep +can resolve all the necessary dependencies: + +```bash +sudo wget https://raw.githubusercontent.com/clearpathrobotics/public-rosdistro/master/rosdep/50-clearpath.list -O /etc/ros/rosdep/sources.list.d/50-clearpath.list +rosdep update +``` + +:::note + +Complete ROS Noetic installation instructions can be found at +http://wiki.ros.org/noetic/Installation/Ubuntu + +::: + +:::note + +Complete ROS 2 Foxy installation instructions can be found at +https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html + +::: + +:::note + +Complete instructions for Clearpath APT sources can be found at +http://packages.clearpathrobotics.com + +::: diff --git a/docs_indoornav_user_manual/base_robot_config/config_install_required_sw.mdx b/docs_indoornav_user_manual/base_robot_config/config_install_required_sw.mdx index 729779793..5f84f0d07 100644 --- a/docs_indoornav_user_manual/base_robot_config/config_install_required_sw.mdx +++ b/docs_indoornav_user_manual/base_robot_config/config_install_required_sw.mdx @@ -1,47 +1,47 @@ ---- -title: Installing Required Software -sidebar_label: Installing Required Software -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -Once you have configured apt and rosdep, you can install the IndoorNav -libraries and their dependencies on your robot by running: - -``` bash -sudo apt-get install ros-$ROS_DISTRO-cpr-indoornav-ROBOT -``` - -where _ROBOT_ is replaced with the model of Clearpath robot -you are installing: -- `dingo` for Dingo-O or Dingo-D, -- `husky` for Husky A200, -- `jackal` for Jackal J100, or -- `ridgeback` for Ridgeback. - -This will automatically install the required launch files and -dependencies. - -Once the packages are installed, run the following to configure the -IndoorNav software: - -```bash -rosrun cpr_indoornav setup -``` - -This script will install additional necessary packages, configure -`apache2` to act as a proxy server to the IndoorNav backpack, configure -SSH credentials to allow ROS to launch nodes on the backpack PC -automatically, and configure the networking between the main PC and -backpack to ensure the hostnames and IP addresses are configured -correctly. The `setup` script is interactive; you will be prompted to -enter your password more than once and select options from multiple -menus. - -Once you have finished running the setup script, reboot the robot to -finish. - -For more details on the networking configuration the -`cpr_indoornav setup` script performs, please see -[Configuring the Network Bridge](/docs_indoornav_user_manual/network_config.mdx#config-network-bridge). +--- +title: Installing Required Software +sidebar_label: Installing Required Software +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Once you have configured apt and rosdep, you can install the IndoorNav +libraries and their dependencies on your robot by running: + +``` bash +sudo apt-get install ros-$ROS_DISTRO-cpr-indoornav-ROBOT +``` + +where _ROBOT_ is replaced with the model of Clearpath robot +you are installing: +- `dingo` for Dingo-O or Dingo-D, +- `husky` for Husky A200, +- `jackal` for Jackal J100, or +- `ridgeback` for Ridgeback. + +This will automatically install the required launch files and +dependencies. + +Once the packages are installed, run the following to configure the +IndoorNav software: + +```bash +rosrun cpr_indoornav setup +``` + +This script will install additional necessary packages, configure +`apache2` to act as a proxy server to the IndoorNav backpack, configure +SSH credentials to allow ROS to launch nodes on the backpack PC +automatically, and configure the networking between the main PC and +backpack to ensure the hostnames and IP addresses are configured +correctly. The `setup` script is interactive; you will be prompted to +enter your password more than once and select options from multiple +menus. + +Once you have finished running the setup script, reboot the robot to +finish. + +For more details on the networking configuration the +`cpr_indoornav setup` script performs, please see +[Configuring the Network Bridge](/docs_indoornav_user_manual/network_config.mdx#config-network-bridge). diff --git a/docs_indoornav_user_manual/base_robot_config/config_install_robot_os.mdx b/docs_indoornav_user_manual/base_robot_config/config_install_robot_os.mdx index 754689066..9865d7aae 100644 --- a/docs_indoornav_user_manual/base_robot_config/config_install_robot_os.mdx +++ b/docs_indoornav_user_manual/base_robot_config/config_install_robot_os.mdx @@ -1,40 +1,40 @@ ---- -title: Installing the Robot OS -sidebar_label: Installing the Robot OS -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -:::note - -Most users will not require this step as robots from Clearpath Robotics -will ship with the Robot OS installed and configured. Only users that -are upgrading an OS or restoring a robot to factory settings will need -to perform these steps so that their robot is compatible with IndoorNav. - -::: - -:::note - -IndoorNav is only supported on robots running ROS Noetic on Ubuntu -20.04. - -::: - -Follow the instructions in your robot's user manual to reinstall the -default OS. The links below contain the instructions for reinstalling -Ubuntu 20.04 and ROS Noetic on all robots that support IndoorNav: - -- Dingo: - [http://www.clearpathrobotics.com/assets/guides/noetic/dingo/](http://www.clearpathrobotics.com/assets/guides/noetic/dingo/Installing.html#installing-with-iso-image) -- Husky: - [http://www.clearpathrobotics.com/assets/guides/noetic/husky](http://www.clearpathrobotics.com/assets/guides/noetic/husky/InstallHuskySoftware.html) -- Jackal: - [http://www.clearpathrobotics.com/assets/guides/noetic/jackal/](http://www.clearpathrobotics.com/assets/guides/noetic/jackal/update.html#starting-from-scratch) -- Ridgeback: - [http://www.clearpathrobotics.com/assets/guides/noetic/ridgeback/](http://www.clearpathrobotics.com/assets/guides/noetic/ridgeback/Installing.html#installing-with-iso-image) - -You can download the latest version of Clearpath's ROS Noetic + Ubuntu -20.04 `Focal` installation media for 64-bit Intel or AMD CPUs here: -\. +--- +title: Installing the Robot OS +sidebar_label: Installing the Robot OS +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Most users will not require this step as robots from Clearpath Robotics +will ship with the Robot OS installed and configured. Only users that +are upgrading an OS or restoring a robot to factory settings will need +to perform these steps so that their robot is compatible with IndoorNav. + +::: + +:::note + +IndoorNav is only supported on robots running ROS Noetic on Ubuntu +20.04. + +::: + +Follow the instructions in your robot's user manual to reinstall the +default OS. The links below contain the instructions for reinstalling +Ubuntu 20.04 and ROS Noetic on all robots that support IndoorNav: + +- Dingo: + [http://www.clearpathrobotics.com/assets/guides/noetic/dingo/](http://www.clearpathrobotics.com/assets/guides/noetic/dingo/Installing.html#installing-with-iso-image) +- Husky: + [http://www.clearpathrobotics.com/assets/guides/noetic/husky](http://www.clearpathrobotics.com/assets/guides/noetic/husky/InstallHuskySoftware.html) +- Jackal: + [http://www.clearpathrobotics.com/assets/guides/noetic/jackal/](http://www.clearpathrobotics.com/assets/guides/noetic/jackal/update.html#starting-from-scratch) +- Ridgeback: + [http://www.clearpathrobotics.com/assets/guides/noetic/ridgeback/](http://www.clearpathrobotics.com/assets/guides/noetic/ridgeback/Installing.html#installing-with-iso-image) + +You can download the latest version of Clearpath's ROS Noetic + Ubuntu +20.04 `Focal` installation media for 64-bit Intel or AMD CPUs here: +\. diff --git a/docs_indoornav_user_manual/base_robot_config/config_starting_automatically.mdx b/docs_indoornav_user_manual/base_robot_config/config_starting_automatically.mdx index bf4afb9ca..f737ac2f0 100644 --- a/docs_indoornav_user_manual/base_robot_config/config_starting_automatically.mdx +++ b/docs_indoornav_user_manual/base_robot_config/config_starting_automatically.mdx @@ -1,32 +1,32 @@ ---- -title: Automatically Starting IndoorNav -sidebar_label: Automatically Starting IndoorNav -sidebar_position: 5 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -If you want IndoorNav to start automatically when the robot boots you -may create a systemd job to start it automatically: - -```bash -rosrun cpr_indoornav_ROBOT install -``` - -where `ROBOT` is your supported Clearpath platform: - -- `dingo` -- `husky` -- `jackal` -- `ridgeback` - -This command will create a new systemd job called `cpr-indoornav` which -will start automatically when the robot boots. This systemd job depends -on the robot's core `ros` systemd job. If you need to restart IndoorNav -it is recommended that you restart both services: - -```bash -sudo systemctl stop cpr-indoornav -sudo systemctl restart ros -sudo systemctl start cpr-indoornav -``` +--- +title: Automatically Starting IndoorNav +sidebar_label: Automatically Starting IndoorNav +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +If you want IndoorNav to start automatically when the robot boots you +may create a systemd job to start it automatically: + +```bash +rosrun cpr_indoornav_ROBOT install +``` + +where `ROBOT` is your supported Clearpath platform: + +- `dingo` +- `husky` +- `jackal` +- `ridgeback` + +This command will create a new systemd job called `cpr-indoornav` which +will start automatically when the robot boots. This systemd job depends +on the robot's core `ros` systemd job. If you need to restart IndoorNav +it is recommended that you restart both services: + +```bash +sudo systemctl stop cpr-indoornav +sudo systemctl restart ros +sudo systemctl start cpr-indoornav +``` diff --git a/docs_indoornav_user_manual/base_robot_config/config_starting_manually.mdx b/docs_indoornav_user_manual/base_robot_config/config_starting_manually.mdx index 26940cfea..730f284bb 100644 --- a/docs_indoornav_user_manual/base_robot_config/config_starting_manually.mdx +++ b/docs_indoornav_user_manual/base_robot_config/config_starting_manually.mdx @@ -1,22 +1,22 @@ ---- -title: Manually Starting IndoorNav -sidebar_label: Manually Starting IndoorNav -sidebar_position: 4 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -# Manually Starting IndoorNav {#config-starting-manually} - -To manually start the IndoorNav software, you can run - -```bash -roslaunch cpr_indoornav_ROBOT indoornav.launch -``` - -where `ROBOT` is your supported Clearpath platform: - -- `dingo` -- `husky` -- `jackal` -- `ridgeback` +--- +title: Manually Starting IndoorNav +sidebar_label: Manually Starting IndoorNav +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +# Manually Starting IndoorNav {#config-starting-manually} + +To manually start the IndoorNav software, you can run + +```bash +roslaunch cpr_indoornav_ROBOT indoornav.launch +``` + +where `ROBOT` is your supported Clearpath platform: + +- `dingo` +- `husky` +- `jackal` +- `ridgeback` diff --git a/docs_indoornav_user_manual/base_robot_config/config_updating_software.mdx b/docs_indoornav_user_manual/base_robot_config/config_updating_software.mdx index 7cdbe7cad..9084c5a53 100644 --- a/docs_indoornav_user_manual/base_robot_config/config_updating_software.mdx +++ b/docs_indoornav_user_manual/base_robot_config/config_updating_software.mdx @@ -1,22 +1,22 @@ ---- -title: Updating Robot Software -sidebar_label: Updating Robot Software -sidebar_position: 6 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -Updating IndoorNav is split into two separate operations: minor updates -and major updates. - -Minor updates affect only the robot's main PC and can be done by -connecting the robot to the internet and running - -``` bash -sudo apt-get update -sudo apt-get upgrade -``` - -If you have been instructed by Clearpath Robotics' support team that -you should update your IndoorNav backpack PC, you should follow the +--- +title: Updating Robot Software +sidebar_label: Updating Robot Software +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Updating IndoorNav is split into two separate operations: minor updates +and major updates. + +Minor updates affect only the robot's main PC and can be done by +connecting the robot to the internet and running + +``` bash +sudo apt-get update +sudo apt-get upgrade +``` + +If you have been instructed by Clearpath Robotics' support team that +you should update your IndoorNav backpack PC, you should follow the instructions at [Installing Backpack Software](/docs_indoornav_user_manual/installing_backpack_software.mdx). \ No newline at end of file diff --git a/docs_indoornav_user_manual/getting_started.mdx b/docs_indoornav_user_manual/getting_started.mdx index 28026ae85..ca2e76a6c 100644 --- a/docs_indoornav_user_manual/getting_started.mdx +++ b/docs_indoornav_user_manual/getting_started.mdx @@ -1,59 +1,59 @@ ---- -title: Getting Started -sidebar_label: Getting Started -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -
-
- -
-
- -Clearpath Robotics' IndoorNav all-in-one package contains everything -you need to allow your robot to navigate autonomously in indoor -environments. IndoorNav is based on indoor autonomy software developed -by OTTO Motors and has been adapted to run on Clearpath Robotics' -robots. - -This document will explain how to set up and use the IndoorNav software -on your supported Clearpath Robotics robot. Supported robots include: - -- [Dingo-D](https://clearpathrobotics.com/dingo-indoor-mobile-robot/) - and [Dingo-O](https://clearpathrobotics.com/dingo-indoor-mobile-robot/) - -
-
- -
-
- -- [Husky](https://clearpathrobotics.com/husky-unmanned-ground-vehicle-robot/) - -
-
- -
-
- -- [Jackal](https://clearpathrobotics.com/jackal-small-unmanned-ground-vehicle/) - -
-
- -
-
- -- [Ridgeback](https://clearpathrobotics.com/ridgeback-indoor-robot-platform/). - -
-
- -
-
- -In addition, [Boxer](https://clearpathrobotics.com/boxer/), which is -based on the OTTO-100 robot, also includes an unmodified version of the +--- +title: Getting Started +sidebar_label: Getting Started +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +
+
+ +
+
+ +Clearpath Robotics' IndoorNav all-in-one package contains everything +you need to allow your robot to navigate autonomously in indoor +environments. IndoorNav is based on indoor autonomy software developed +by OTTO Motors and has been adapted to run on Clearpath Robotics' +robots. + +This document will explain how to set up and use the IndoorNav software +on your supported Clearpath Robotics robot. Supported robots include: + +- [Dingo-D](https://clearpathrobotics.com/dingo-indoor-mobile-robot/) + and [Dingo-O](https://clearpathrobotics.com/dingo-indoor-mobile-robot/) + +
+
+ +
+
+ +- [Husky](https://clearpathrobotics.com/husky-unmanned-ground-vehicle-robot/) + +
+
+ +
+
+ +- [Jackal](https://clearpathrobotics.com/jackal-small-unmanned-ground-vehicle/) + +
+
+ +
+
+ +- [Ridgeback](https://clearpathrobotics.com/ridgeback-indoor-robot-platform/). + +
+
+ +
+
+ +In addition, [Boxer](https://clearpathrobotics.com/boxer/), which is +based on the OTTO-100 robot, also includes an unmodified version of the OTTO Motors indoor autonomy software. \ No newline at end of file diff --git a/docs_indoornav_user_manual/index.mdx b/docs_indoornav_user_manual/index.mdx index 0c6902782..bd51fb653 100644 --- a/docs_indoornav_user_manual/index.mdx +++ b/docs_indoornav_user_manual/index.mdx @@ -1,19 +1,19 @@ ---- -title: IndoorNav User Manual -sidebar_label: IndoorNav User Manual -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -
-
- -
-
- -IndoorNav is an all-in-one autonomy kit that enables robust point-to-point autonomous -navigation of mobile robots in indoor environments. It provides advanced software with -a powerful processor and sensor suite, and integrates seamlessly with Clearpath mobile -robotic development platforms. Designed for researchers in academia and corporate R&D, +--- +title: IndoorNav User Manual +sidebar_label: IndoorNav User Manual +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +
+
+ +
+
+ +IndoorNav is an all-in-one autonomy kit that enables robust point-to-point autonomous +navigation of mobile robots in indoor environments. It provides advanced software with +a powerful processor and sensor suite, and integrates seamlessly with Clearpath mobile +robotic development platforms. Designed for researchers in academia and corporate R&D, IndoorNav is ROS ready and fully extensible with a well documented developer API. \ No newline at end of file diff --git a/docs_indoornav_user_manual/installing_backpack_software.mdx b/docs_indoornav_user_manual/installing_backpack_software.mdx index e1c347981..7deefd287 100644 --- a/docs_indoornav_user_manual/installing_backpack_software.mdx +++ b/docs_indoornav_user_manual/installing_backpack_software.mdx @@ -1,61 +1,61 @@ ---- -title: "Appendix B: Installing Backpack Software" -sidebar_label: "Appendix B: Installing Backpack Software" -sidebar_position: 7 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -:::note - -Before you can configure the IndoorNav backpack, you must contact -Clearpath Robotics' customer support and ask to be sent an archive -containing additional files needed. You will need to copy this archive -onto the backpack PC as noted below. - -::: - -Your IndoorNav backpack PC comes with the latest supported version of -IndoorNav pre-installed. If you need to update or reinstall the software -on the backpack PC, first update the OS using the procedure outlined -here: \. - -Once the OS has been updated you will need to connect a monitor, -keyboard, and wired internet connection to backpack PC. Power-on the PC -and log in using the backpack's default username and password. - -After logging in you may now copy the `.tar.gz` file supplied by -Clearpath Robotics onto the backpack. Make a note of the path to this -file, as you will need it in the following steps. - -Run the following commands to establish a wired internet connection: - -```bash -sudo ip link delete sbr0 type bridge -sudo dhclient eno1 -``` - -You may need to replace `eno1` with a different interface ID, depending -on the physical ethernet port you have connected to your router. Other -common examples are `enp2s0`, `enp3s0`, and `eth0`. Running the `ip a` -command will show all available network interfaces. - -Run the following commands to download the setup script to complete the -rest of the backpack software installation: - -```bash -cd $HOME -git clone https://github.com/clearpathrobotics/cpr-indoornav-install.git -cd cpr-indoornav-install -bash install.sh -``` - -The `install.sh` script is interactive and will prompt you for the -following pieces of information (not necessarily in this order): - -- a new hostname for the backpack PC -- the hostname of your robot's primary PC -- the path to the `.tar.gz` file you copied onto the backpack earlier - -You must power-cycle the backpack PC after running +--- +title: "Appendix B: Installing Backpack Software" +sidebar_label: "Appendix B: Installing Backpack Software" +sidebar_position: 7 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Before you can configure the IndoorNav backpack, you must contact +Clearpath Robotics' customer support and ask to be sent an archive +containing additional files needed. You will need to copy this archive +onto the backpack PC as noted below. + +::: + +Your IndoorNav backpack PC comes with the latest supported version of +IndoorNav pre-installed. If you need to update or reinstall the software +on the backpack PC, first update the OS using the procedure outlined +here: \. + +Once the OS has been updated you will need to connect a monitor, +keyboard, and wired internet connection to backpack PC. Power-on the PC +and log in using the backpack's default username and password. + +After logging in you may now copy the `.tar.gz` file supplied by +Clearpath Robotics onto the backpack. Make a note of the path to this +file, as you will need it in the following steps. + +Run the following commands to establish a wired internet connection: + +```bash +sudo ip link delete sbr0 type bridge +sudo dhclient eno1 +``` + +You may need to replace `eno1` with a different interface ID, depending +on the physical ethernet port you have connected to your router. Other +common examples are `enp2s0`, `enp3s0`, and `eth0`. Running the `ip a` +command will show all available network interfaces. + +Run the following commands to download the setup script to complete the +rest of the backpack software installation: + +```bash +cd $HOME +git clone https://github.com/clearpathrobotics/cpr-indoornav-install.git +cd cpr-indoornav-install +bash install.sh +``` + +The `install.sh` script is interactive and will prompt you for the +following pieces of information (not necessarily in this order): + +- a new hostname for the backpack PC +- the hostname of your robot's primary PC +- the path to the `.tar.gz` file you copied onto the backpack earlier + +You must power-cycle the backpack PC after running `install.sh` to finalize the configuration. \ No newline at end of file diff --git a/docs_indoornav_user_manual/network_config.mdx b/docs_indoornav_user_manual/network_config.mdx index 5f79d4e83..c90b5455c 100644 --- a/docs_indoornav_user_manual/network_config.mdx +++ b/docs_indoornav_user_manual/network_config.mdx @@ -1,286 +1,286 @@ ---- -title: "Appendix C: Network Configuration" -sidebar_label: "Appendix C: Network Configuration" -sidebar_position: 8 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -Normally the network bridge and port forwarding are configured -automatically when using the `cpr_indoornav setup` script (see -[Installing Required Software](/docs_indoornav_user_manual/base_robot_config/config_install_required_sw.mdx). This -appendix explains the network configuration of the robot's PC in more -detail. - -## Configuring the Network Bridge {#config-network-bridge} - -The first step to configure your robot for use with IndoorNav is to make -sure that the ethernet communication between the robot's PC and the -IndoorNav backpack works. All Clearpath robots are configured to bridge -their physical ethernet ports together. This allows all the ports on the -motherboard to operate on multiple subnets simultaneously. By default -Clearpath robots use the `192.168.131.0/24` subnet for their internal -network, with all IP-based sensors and peripherals operating on this -subnet. - -IndoorNav requires modifying the default bridge to remove a single -ethernet port, `eno1` by default, from the bridge and assigning it to -the `10.252.252.0/24` subnet. This physical port will be dedicated to -communicating with the IndoorNav backpack PC. - -To configure `eno1` to be used to communicate with the backpack PC, -modify `/etc/netplan/50-clearpath-bridge.yaml` as follows. The example -below bridges interfaces with the identifiers `eth*`, `enp*`, `enx*` and -`usb*` together on the `192.168.131.0/24` subnet. - -```yaml -network: - version: 2 - renderer: networkd - ethernets: - # dedicated port for communicating with the IndoorNav backpack - eno1: - dhcp4: no - dhcp6: no - addresses: - - 10.252.252.100/24 - - # bridge all other ports together on the 192.168.131.0/24 subnet - bridge_eth: - dhcp4: no - dhcp6: no - match: - name: eth* - bridge_enp: - dhcp4: no - dhcp6: no - match: - name: enp* - bridge_enx: - dhcp4: no - dhcp6: no - match: - name: enx* - bridge_usb: - dhcp4: no - dhcp6: no - match: - name: usb* - bridges: - br0: - dhcp4: yes - dhcp6: no - interfaces: [bridge_eth, bridge_enp, bridge_enx, bridge_usb] - addresses: - - 192.168.131.1/24 -``` - -Instead of using `eno1` you can use a specific USB to ethernet dongle, -for example: - -```yaml -network: - version: 2 - renderer: networkd - ethernets: - # dedicated port for communicating with the IndoorNav backpack - enx70886b8f17a5: - dhcp4: no - dhcp6: no - addresses: - - 10.252.252.100/24 - - # bridge all other ports together on the 192.168.131.0/24 subnet - bridge_eth: - dhcp4: no - dhcp6: no - match: - name: eth* - bridge_eno: - dhcp4: no - dhcp6: no - match: - name: eno* - bridge_enp: - dhcp4: no - dhcp6: no - match: - name: enp* - bridges: - br0: - dhcp4: yes - dhcp6: no - interfaces: [bridge_eth, bridge_eno, bridge_enp] - addresses: - - 192.168.131.1/24 -``` - -If you made any changes to the bridge configuration reboot the robot -now. Once the robot and backpack PC are both powered-on, connect them -with an ethernet cable connected to `eno1` on the backpack and the -IndoorNav port you configured above. Run the following command to check -that you can communicate with the backpack PC: - -```bash -ping 10.252.252.1 -``` - -Once you have configured the network interfaces and confirmed that the -communication works, ensure that the dedicated IndoorNav port is set in -the `cpr_indoornav` package's `config/cyclone_dds.xml` file: - -``` xml - - - - - - eno1 - true - - - 5 min - - - -``` - -## Configuring Apache2 Proxy Server - -IndoorNav operates a web-based mapping GUI that you can use to plan -routes, mark areas for specific tasks, view/edit the map, and the like. -To access this interface you should install the `apache2` package and -configure it to act as a proxy server for the IndoorNav backpack: - -```bash -sudo apt-get install apache2 -sudo a2enmod proxy -sudo a2enmod proxy_http -sudo a2enmod proxy_wstunnel -sudo a2enmod rewrite -``` - -Create (or edit) `/etc/apache2/conf-enabled/clearpath.conf` to contain -the following: - -``` -Listen 2000 -Listen 2001 -Listen 5000 -Listen 9091 - - - ProxyRequests On - ProxyVia On - - ProxyPass / http://10.252.252.1:2000/ - ProxyPassReverse / http://10.252.252.1:2000/ - - - - ServerName HOSTNAME # replace HOSTNAME with your robot's hostname!! - - RewriteEngine On - - RewriteCond %{HTTP:Upgrade} =websocket [NC] - RewriteRule /(.*) ws://10.252.252.1:2001/$1 [P,L] - - RewriteCond %{HTTP:Upgrade} !=websocket [NC] - RewriteRule /(.*) ws://10.252.252.1:2001/$1 [P,L] - - ProxyPass / http://10.252.252.1:2001/ - ProxyPassReverse / http://10.252.252.1:2001/ - - - - ProxyRequests On - ProxyVia On - - ProxyPass / http://10.252.252.1:5000/ - ProxyPassReverse / http://10.252.252.1:5000/ - - - - ServerName HOSTNAME # replace HOSTNAME with your robot's hostname!! - - RewriteEngine On - - RewriteCond %{HTTP:Upgrade} =websocket [NC] - RewriteRule /(.*) ws://10.252.252.1:9091/$1 [P,L] - - RewriteCond %{HTTP:Upgrade} !=websocket [NC] - RewriteRule /(.*) ws://10.252.252.1:9091/$1 [P,L] - - ProxyPass / http://10.252.252.1:9091/ - ProxyPassReverse / http://10.252.252.1:9091/ - -``` - -Make sure to replace the two instances of `HOSTNAME` in the file above -with your robot's hostname, e.g. `cpr-j100-1234` - -Once `/etc/apache2/conf-enabled/clearpath.conf` has been modified, -restart the `apache2` service: - -```bash -sudo systemctl restart apache2 -``` - -## Configuring IP Tables - -:::warning - -It has been observed that using `iptables` to enable port-forwarding may -cause errors with the ROS 2 daemon. We recommend using the Apache Proxy -Server method described above. - -::: - -Instead of using Apache2 to act as a proxy server, you can instead use -the Linux Kernel's `iptables` to enable port-forwarding. If you enable -`iptables` you should also disable the `apache2` service to prevent the -proxy server from also listening on these ports: - -```bash -sudo systemctl stop apache2 -sudo systemctl disable apache2 -``` - -To configure `iptables` run the following commands: - -```bash -sudo sysctl net.ipv4.ip_forward=1 -sudo iptables --policy FORWARD ACCEPT -sudo iptables -t nat -A PREROUTING -p tcp --dport 2000 -j DNAT --to-destination 10.252.252.1:2000 -sudo iptables -t nat -A PREROUTING -p tcp --dport 2001 -j DNAT --to-destination 10.252.252.1:2001 -sudo iptables -t nat -A PREROUTING -p tcp --dport 5000 -j DNAT --to-destination 10.252.252.1:5000 -sudo iptables -t nat -A PREROUTING -p tcp --dport 9091 -j DNAT --to-destination 10.252.252.1:9091 -sudo iptables -t nat -A POSTROUTING -j MASQUERADE -``` - -To make these changes permanent you should edit `/etc/sysctl.conf` and -make sure that IPv4 forwarding is enabled: - -```bash -net.ipv4.ip_forward=1 -``` - -and install the `iptables-persistent` package: - -```bash -sudo apt-get install iptables-persistent -``` - -If this package is already installed you can update the rules by running - -```bash -sudo dpkg-reconfigure iptables-persistent -``` - -Select **Yes** when asked if you want to save the IPv4 rules and **No** -if you want to save the IPv6 rules. +--- +title: "Appendix C: Network Configuration" +sidebar_label: "Appendix C: Network Configuration" +sidebar_position: 8 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Normally the network bridge and port forwarding are configured +automatically when using the `cpr_indoornav setup` script (see +[Installing Required Software](/docs_indoornav_user_manual/base_robot_config/config_install_required_sw.mdx). This +appendix explains the network configuration of the robot's PC in more +detail. + +## Configuring the Network Bridge {#config-network-bridge} + +The first step to configure your robot for use with IndoorNav is to make +sure that the ethernet communication between the robot's PC and the +IndoorNav backpack works. All Clearpath robots are configured to bridge +their physical ethernet ports together. This allows all the ports on the +motherboard to operate on multiple subnets simultaneously. By default +Clearpath robots use the `192.168.131.0/24` subnet for their internal +network, with all IP-based sensors and peripherals operating on this +subnet. + +IndoorNav requires modifying the default bridge to remove a single +ethernet port, `eno1` by default, from the bridge and assigning it to +the `10.252.252.0/24` subnet. This physical port will be dedicated to +communicating with the IndoorNav backpack PC. + +To configure `eno1` to be used to communicate with the backpack PC, +modify `/etc/netplan/50-clearpath-bridge.yaml` as follows. The example +below bridges interfaces with the identifiers `eth*`, `enp*`, `enx*` and +`usb*` together on the `192.168.131.0/24` subnet. + +```yaml +network: + version: 2 + renderer: networkd + ethernets: + # dedicated port for communicating with the IndoorNav backpack + eno1: + dhcp4: no + dhcp6: no + addresses: + - 10.252.252.100/24 + + # bridge all other ports together on the 192.168.131.0/24 subnet + bridge_eth: + dhcp4: no + dhcp6: no + match: + name: eth* + bridge_enp: + dhcp4: no + dhcp6: no + match: + name: enp* + bridge_enx: + dhcp4: no + dhcp6: no + match: + name: enx* + bridge_usb: + dhcp4: no + dhcp6: no + match: + name: usb* + bridges: + br0: + dhcp4: yes + dhcp6: no + interfaces: [bridge_eth, bridge_enp, bridge_enx, bridge_usb] + addresses: + - 192.168.131.1/24 +``` + +Instead of using `eno1` you can use a specific USB to ethernet dongle, +for example: + +```yaml +network: + version: 2 + renderer: networkd + ethernets: + # dedicated port for communicating with the IndoorNav backpack + enx70886b8f17a5: + dhcp4: no + dhcp6: no + addresses: + - 10.252.252.100/24 + + # bridge all other ports together on the 192.168.131.0/24 subnet + bridge_eth: + dhcp4: no + dhcp6: no + match: + name: eth* + bridge_eno: + dhcp4: no + dhcp6: no + match: + name: eno* + bridge_enp: + dhcp4: no + dhcp6: no + match: + name: enp* + bridges: + br0: + dhcp4: yes + dhcp6: no + interfaces: [bridge_eth, bridge_eno, bridge_enp] + addresses: + - 192.168.131.1/24 +``` + +If you made any changes to the bridge configuration reboot the robot +now. Once the robot and backpack PC are both powered-on, connect them +with an ethernet cable connected to `eno1` on the backpack and the +IndoorNav port you configured above. Run the following command to check +that you can communicate with the backpack PC: + +```bash +ping 10.252.252.1 +``` + +Once you have configured the network interfaces and confirmed that the +communication works, ensure that the dedicated IndoorNav port is set in +the `cpr_indoornav` package's `config/cyclone_dds.xml` file: + +``` xml + + + + + + eno1 + true + + + 5 min + + + +``` + +## Configuring Apache2 Proxy Server + +IndoorNav operates a web-based mapping GUI that you can use to plan +routes, mark areas for specific tasks, view/edit the map, and the like. +To access this interface you should install the `apache2` package and +configure it to act as a proxy server for the IndoorNav backpack: + +```bash +sudo apt-get install apache2 +sudo a2enmod proxy +sudo a2enmod proxy_http +sudo a2enmod proxy_wstunnel +sudo a2enmod rewrite +``` + +Create (or edit) `/etc/apache2/conf-enabled/clearpath.conf` to contain +the following: + +``` +Listen 2000 +Listen 2001 +Listen 5000 +Listen 9091 + + + ProxyRequests On + ProxyVia On + + ProxyPass / http://10.252.252.1:2000/ + ProxyPassReverse / http://10.252.252.1:2000/ + + + + ServerName HOSTNAME # replace HOSTNAME with your robot's hostname!! + + RewriteEngine On + + RewriteCond %{HTTP:Upgrade} =websocket [NC] + RewriteRule /(.*) ws://10.252.252.1:2001/$1 [P,L] + + RewriteCond %{HTTP:Upgrade} !=websocket [NC] + RewriteRule /(.*) ws://10.252.252.1:2001/$1 [P,L] + + ProxyPass / http://10.252.252.1:2001/ + ProxyPassReverse / http://10.252.252.1:2001/ + + + + ProxyRequests On + ProxyVia On + + ProxyPass / http://10.252.252.1:5000/ + ProxyPassReverse / http://10.252.252.1:5000/ + + + + ServerName HOSTNAME # replace HOSTNAME with your robot's hostname!! + + RewriteEngine On + + RewriteCond %{HTTP:Upgrade} =websocket [NC] + RewriteRule /(.*) ws://10.252.252.1:9091/$1 [P,L] + + RewriteCond %{HTTP:Upgrade} !=websocket [NC] + RewriteRule /(.*) ws://10.252.252.1:9091/$1 [P,L] + + ProxyPass / http://10.252.252.1:9091/ + ProxyPassReverse / http://10.252.252.1:9091/ + +``` + +Make sure to replace the two instances of `HOSTNAME` in the file above +with your robot's hostname, e.g. `cpr-j100-1234` + +Once `/etc/apache2/conf-enabled/clearpath.conf` has been modified, +restart the `apache2` service: + +```bash +sudo systemctl restart apache2 +``` + +## Configuring IP Tables + +:::warning + +It has been observed that using `iptables` to enable port-forwarding may +cause errors with the ROS 2 daemon. We recommend using the Apache Proxy +Server method described above. + +::: + +Instead of using Apache2 to act as a proxy server, you can instead use +the Linux Kernel's `iptables` to enable port-forwarding. If you enable +`iptables` you should also disable the `apache2` service to prevent the +proxy server from also listening on these ports: + +```bash +sudo systemctl stop apache2 +sudo systemctl disable apache2 +``` + +To configure `iptables` run the following commands: + +```bash +sudo sysctl net.ipv4.ip_forward=1 +sudo iptables --policy FORWARD ACCEPT +sudo iptables -t nat -A PREROUTING -p tcp --dport 2000 -j DNAT --to-destination 10.252.252.1:2000 +sudo iptables -t nat -A PREROUTING -p tcp --dport 2001 -j DNAT --to-destination 10.252.252.1:2001 +sudo iptables -t nat -A PREROUTING -p tcp --dport 5000 -j DNAT --to-destination 10.252.252.1:5000 +sudo iptables -t nat -A PREROUTING -p tcp --dport 9091 -j DNAT --to-destination 10.252.252.1:9091 +sudo iptables -t nat -A POSTROUTING -j MASQUERADE +``` + +To make these changes permanent you should edit `/etc/sysctl.conf` and +make sure that IPv4 forwarding is enabled: + +```bash +net.ipv4.ip_forward=1 +``` + +and install the `iptables-persistent` package: + +```bash +sudo apt-get install iptables-persistent +``` + +If this package is already installed you can update the rules by running + +```bash +sudo dpkg-reconfigure iptables-persistent +``` + +Select **Yes** when asked if you want to save the IPv4 rules and **No** +if you want to save the IPv6 rules. diff --git a/docs_indoornav_user_manual/support.mdx b/docs_indoornav_user_manual/support.mdx index 23d3f71a2..5ae86ff27 100644 --- a/docs_indoornav_user_manual/support.mdx +++ b/docs_indoornav_user_manual/support.mdx @@ -1,11 +1,11 @@ ---- -title: Support -sidebar_label: Support -sidebar_position: 5 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -import Support from "/components/support.mdx"; - +--- +title: Support +sidebar_label: Support +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Support from "/components/support.mdx"; + \ No newline at end of file diff --git a/docs_indoornav_user_manual/using_indoornav/_category_.json b/docs_indoornav_user_manual/using_indoornav/_category_.json index a6be182f8..797147e5e 100644 --- a/docs_indoornav_user_manual/using_indoornav/_category_.json +++ b/docs_indoornav_user_manual/using_indoornav/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Using IndoorNav Software", - "position": 4 +{ + "label": "Using IndoorNav Software", + "position": 4 } \ No newline at end of file diff --git a/docs_indoornav_user_manual/using_indoornav/driving_the_robot.mdx b/docs_indoornav_user_manual/using_indoornav/driving_the_robot.mdx index 2b86c98f5..46077613f 100644 --- a/docs_indoornav_user_manual/using_indoornav/driving_the_robot.mdx +++ b/docs_indoornav_user_manual/using_indoornav/driving_the_robot.mdx @@ -1,118 +1,118 @@ ---- -title: Driving the Robot -sidebar_label: Driving the Robot -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -IndoorNav offers several different methods to drive the robot, in -addition to using the included game controller, interactive markers in -Rviz, or publishing directly to `/cmd_vel`. - -:::warning - -CAUTION! Failure to follow these instructions may result in MINOR or -MODERATE INJURY or DAMAGE to the system or property. - -::: - -:::warning - -IMPACT HAZARD! Always maintain a safe distance from a robot in -operation. A robot being operated in manual mode should only be operated -by personnel who have been trained and authorized according to the -standards of the facility in which the robot is in use. Be aware of the -Emergency Stop button locations. - -::: - -## Driving the Robot in Manual Mode - -:::note - -See [detailed documentation on manual driving](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51784-driving-a-robot-in-manual-mode.html) -for more information. - -::: - -The Web GUI allows teleoperation of the robot without using the included -game controller. To enable manual driving, select either the Drive or -Facility tab and use the on-screen controls in the lower-right corner, -as shown in the figure below. Moving the virtual joystick up/down will -drive the robot forward/backward, and moving it left/right will make the -robot turn. - -
-
- -
-
- -The first time you access the Web GUI after powering-on the robot, the -robot may be in neutral. Click the button to take the robot out of neutral. - -Clicking the will open the drive settings, allowing you to adjust the -robot's driving speed or disable manual driving, shown in the figure -below. - -
-
- -
-
- -## Driving the Robot in Autonomous Mode - -:::note - -See [detailed documentation on autonomous driving](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51785-driving-a-robot-in-autonomous-mode.html) -for more information. - -::: - -To drive the robot in autonomous mode the steps are: - -1. Create a map. See [Making a Map](/docs_indoornav_user_manual/using_indoornav/maps.mdx#making-a-map) for - details. - -2. Confirm that the **Manual** toggle is disabled and manual driving - mode is OFF. When disabled, the **Drive Mode** toggle is gray and a - **Move** button will be displayed. - -3. Select **Move**. - -4. Select the location on the map to which the robot should drive. The - joystick button will turn green and the orientation circle will be - displayed at the selected location on the map. - -5. Move the green line inside the orientation circle to define the - direction in which the front of the robot should be directed when it - stops at the selected location. - -
-
- -
-
- -6. Select **Go** to send the robot on its way. Select **Stop** to stop - the robot at any time. - -## Driving Using Endpoints - -:::note - -See [detailed documentation on driving using endpoints](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51786-driving-a-robot-using-endpoints.html) -for more information. - -::: - -To drive the robot using endpoints the steps are: - -1. Create a map. See [Making a Map](/docs_indoornav_user_manual/using_indoornav/maps.mdx#making-a-map) for - details. -2. Add Endpoints to the map. See [Adding Endpoints](/docs_indoornav_user_manual/using_indoornav/maps.mdx#adding-endpoints) for details. -3. Select an Endpoint. -4. Select **Go** to send the robot on its way. Select **Stop** to stop - the robot at any time. +--- +title: Driving the Robot +sidebar_label: Driving the Robot +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +IndoorNav offers several different methods to drive the robot, in +addition to using the included game controller, interactive markers in +Rviz, or publishing directly to `/cmd_vel`. + +:::warning + +CAUTION! Failure to follow these instructions may result in MINOR or +MODERATE INJURY or DAMAGE to the system or property. + +::: + +:::warning + +IMPACT HAZARD! Always maintain a safe distance from a robot in +operation. A robot being operated in manual mode should only be operated +by personnel who have been trained and authorized according to the +standards of the facility in which the robot is in use. Be aware of the +Emergency Stop button locations. + +::: + +## Driving the Robot in Manual Mode + +:::note + +See [detailed documentation on manual driving](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51784-driving-a-robot-in-manual-mode.html) +for more information. + +::: + +The Web GUI allows teleoperation of the robot without using the included +game controller. To enable manual driving, select either the Drive or +Facility tab and use the on-screen controls in the lower-right corner, +as shown in the figure below. Moving the virtual joystick up/down will +drive the robot forward/backward, and moving it left/right will make the +robot turn. + +
+
+ +
+
+ +The first time you access the Web GUI after powering-on the robot, the +robot may be in neutral. Click the button to take the robot out of neutral. + +Clicking the will open the drive settings, allowing you to adjust the +robot's driving speed or disable manual driving, shown in the figure +below. + +
+
+ +
+
+ +## Driving the Robot in Autonomous Mode + +:::note + +See [detailed documentation on autonomous driving](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51785-driving-a-robot-in-autonomous-mode.html) +for more information. + +::: + +To drive the robot in autonomous mode the steps are: + +1. Create a map. See [Making a Map](/docs_indoornav_user_manual/using_indoornav/maps.mdx#making-a-map) for + details. + +2. Confirm that the **Manual** toggle is disabled and manual driving + mode is OFF. When disabled, the **Drive Mode** toggle is gray and a + **Move** button will be displayed. + +3. Select **Move**. + +4. Select the location on the map to which the robot should drive. The + joystick button will turn green and the orientation circle will be + displayed at the selected location on the map. + +5. Move the green line inside the orientation circle to define the + direction in which the front of the robot should be directed when it + stops at the selected location. + +
+
+ +
+
+ +6. Select **Go** to send the robot on its way. Select **Stop** to stop + the robot at any time. + +## Driving Using Endpoints + +:::note + +See [detailed documentation on driving using endpoints](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51786-driving-a-robot-using-endpoints.html) +for more information. + +::: + +To drive the robot using endpoints the steps are: + +1. Create a map. See [Making a Map](/docs_indoornav_user_manual/using_indoornav/maps.mdx#making-a-map) for + details. +2. Add Endpoints to the map. See [Adding Endpoints](/docs_indoornav_user_manual/using_indoornav/maps.mdx#adding-endpoints) for details. +3. Select an Endpoint. +4. Select **Go** to send the robot on its way. Select **Stop** to stop + the robot at any time. diff --git a/docs_indoornav_user_manual/using_indoornav/maps.mdx b/docs_indoornav_user_manual/using_indoornav/maps.mdx index ea617741c..0ec7df864 100644 --- a/docs_indoornav_user_manual/using_indoornav/maps.mdx +++ b/docs_indoornav_user_manual/using_indoornav/maps.mdx @@ -1,331 +1,331 @@ ---- -title: Maps -sidebar_label: Maps -sidebar_position: 4 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -:::note - -See [detailed documentation on mapping a -facility](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51848-mapping-a-facility.html) -for more information. - -::: - -A map is a digital representation of the facility around which your -robot needs to navigate. Maps are on a grid and X and Y axes are used to -define locations on that grid. The point at which a map recording begins -is located on the grid at 0m, 0m. Maps are always measured in meters. - -Maps are how robots become aware of traffic rules and key waypoints -within a facility. A robot determines which traffic rules to apply based -on its position estimate---this is not a safety rated system. If a robot -is in close proximity to an area where a drift in position may cause a -hazard, place physical barriers that the safety system is capable of -seeing. - -Robots require an accurate map of a facility in order to plan the best -routes for executing workflows. Map creation is done using your robot to -record the its surroundings while it drives around the facility. - -## Making a Map - -:::note - -When you first receive your robot with IndoorNav it may have a map of -Clearpath's building and testing facility already saved on it. This map -may be discarded. - -::: - -To create a new map: - -1. [Refer to the mapping guidelines](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51849-mapping-guidelines.html). - -2. Open the Web GUI. - -3. Determine where map recording will begin and navigate the robot to - that position. Carefully select the starting position and alignment. - This point may be important in the future if updating a map or - remapping. A point that is central is recommended, but not required. - Note that the orientation of robot in relation to the facility when - beginning to record the map affects the orientation of the map as it - appears. When recording map data first beings, the direction in - which the front of the robot is facing will be the right side (east) - of the map. - -4. Select the **Facility** tab. - -5. From the upper toolbar, select **New Map**. The existing map (if - any) will disappear and be replaced with a new, blank map. To - download a copy of the current map click **Export Map.** To upload - an existing map, e.g. one saved from another robot, click **Import Map.** - -
-
- -
-
- -6. Select **REC** to begin recording the map. Select **Pause** at any - time to pause map data recording. - -
-
- -
-
- -7. Drive the robot through the facility manually, either using the web - GUI or the game controller. You will see light grey lines appear, - indicating where walls and other obstacles are. You should map all - locations where the robot is expected to navigate autonomously. - -8. To save the changes to the map, select **Save Map**. To cancel all - changes, select **Undo** or navigate to a new screen. - -# Using Map Features - -Once the map is made you can specify certain zones as off-limits to the -robot, designate certain areas as one-way traffic, restrict speed, or -simply add annotations to make the map easier to read. See -[Using Zones](#usage-zones) for more information about -creating zones on the map. - -To add zones and endpoints, use the menus found on the Facility -interface's main menu. - -
-
- -
-
- -:::note - -After adding, removing, or editing zones and endpoints, you must click -the -button on the main toolbar before navigating away from the page. Failing -to click this button may result in data being lost. - -::: - -## Adding Endpoints - -:::note - -See [detailed documentation on creating endpoints](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51866-creating-endpoints.html) -for more information. - -::: - -An endpoint is a physical location that sometimes includes a collection -of tasks that define how a robot performs a workflow. To add an endpoint -to the map: - -1. From the **Facility** menu select **Endpoints**. - -2. Select the appropriate type of endpoint from the list. - -3. Select the desired location on the map where the endpoint will be - created. An endpoint details pane will appear on the right side of - the window. If desired, orient the endpoint using the orientation - circle. Select and drag the middle of the orientation circle to move - the endpoint to a different location on the map. Select the drag the - edge of the orientation circle to rotate the endpoint. - -
-
- -
-
- -4. Enter a **Name** for the endpoint. - -5. If desired, enter a **Description**. - -6. The **X** and **Y** coordinates and **Rotation** (in degrees) of the - endpoint will be pre-populated based on the placement of the - endpoint. Use these fields to finely position the endpoint on the - map. - -7. Select **Done** to add the endpoint to the map. - -8. Select **Save** to save the changes to the map. To cancel all - changes, select **Undo** or navigate to a new screen. - -## Using Zones {#usage-zones} - -:::note - -See [detailed documentation on using zones](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51877-zones.html) -for more information. - -::: - -Zones define specific areas where robots can travel and their behavior -while within or near the zone such as maximum speed. - -Zones are polygons with three or more points making up a closed shape. -Zone placement isn't restricted by walls or other solid objects on the -map. - -To add a new zone to the map: - -1. Click the Map button on the main toolbar and select the desired type - of zone from the menu. -2. Click and drag on the map to add a new zone. Initially the zone will - be rectangular. -3. Update the zone shape as needed. You can add additional corners by - clicking on a segment and dragging it; a new corner will appear - under the mouse, allowing you to build more complex shapes. The - following figures show the process of creating a new zone and - editing its shape. - -
-
- -
Initial shape made by clicking and dragging
-
- -
- -
Zone in its default shape
-
- -
- -
Same zone after clicking and dragging on the zone edges to add additional corners
-
-
- -You can add further details about the zone using the configuration -tools, such as those shown for the Narrow Corridor Zone in the following -figure. - -
-
- -
-
- -Clicking on the -will allow you to change the type of zone, using the menu -shown in the figure below. When you have finished creating the zone -select **Done** on the upper toolbar. - -
-
- -
-
- -## Using Workflows - -:::note - -See [detailed documentation on creating workflows](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51871-creating-workflows.html) -for more information. - -::: - -Workflows use endpoints to have a robot perform work automatically. When -a workflow is created, robots can execute them automatically when -autonomy is active. - -To create a workflow: - -1. From the **Facility** menu select **Endpoints**. -2. Select **A-B-C**. The workflow details pane will appear on the right - side of the window. -3. Enter a **Name** for the workflow. -4. Select **Add Task** to add a task to the workflow using endpoints - that have been created already. The tasks available for selection - are dependent on the endpoints that have been added to the map and - their types. -5. Select the desired tasks type. -6. Select the desired endpoint at which the selected task will be - performed. -7. Add additional tasks to the workflow as desired. -8. Select **Done** to add the workflow to the map. -9. Select **Save** to save the changes to the map. - -To execute a workflow: - -1. From the **Drive** menu select **Workflows**. -2. Select the desired workflow. -3. Select **GO**. The robot will attempt to execute the workflow. - Select **Stop** at any time to pause execution of the workflow. - Select **Resume** to continue the workflow. - -## Using Docking - -:::warning - -Keep the area around the dock free of objects and people. There is no -obstacle detection between pre-docking point and the dock; similarly, -there is no obstacle detection during the undocking operation. - -::: - -Docking is a feature for IndoorNav that requires the purchase of a dock -target. Refer to [Support](/docs_indoornav_user_manual/support.mdx) for -information on how to contact the sales team to purchase a dock. - -To include a dock in the workflow: - -1. **Mapping**: Position the dock in its intended position, then - proceed to map the area as usual, including the dock area. If the - dock was not included fully in the original map, remap the dock - area. - -
-
- -
-
- -2. **Placing Dock on the Map**: Once the map is created, overlay the - dock target onto the map as shown below by selecting "Charger - Endpoint" from the "Endpoints" menu and adding the charger on the - map such that it overlays the position from the mapping step. - -
-
- -
-
- -3. **Docking**: Select the "Dock Endpoint" and add it to the map so - that it is 2 metres away from the dock, positioned in the centre of - the dock, and oriented to point to the centre of the dock as shown - below. Then, update the desired workflow to make the "Dock - Endpoint" the last endpoint of the mission. - -
-
- -
-
- -4. **Undocking**: Add an "Undock Endpoint" at the position of the - robot when docked as shown below. Then, update the desired workflow - to make the "Undock Endpoint" the first endpoint of the mission. - -
-
- -
-
- -For clarity, when creating a mission that begins and ends with the robot -at the dock, use the Undock Endpoint as the first endpoint and the Dock -Endpoint as the last one. - -
-
- -
-
+--- +title: Maps +sidebar_label: Maps +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +See [detailed documentation on mapping a +facility](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51848-mapping-a-facility.html) +for more information. + +::: + +A map is a digital representation of the facility around which your +robot needs to navigate. Maps are on a grid and X and Y axes are used to +define locations on that grid. The point at which a map recording begins +is located on the grid at 0m, 0m. Maps are always measured in meters. + +Maps are how robots become aware of traffic rules and key waypoints +within a facility. A robot determines which traffic rules to apply based +on its position estimate---this is not a safety rated system. If a robot +is in close proximity to an area where a drift in position may cause a +hazard, place physical barriers that the safety system is capable of +seeing. + +Robots require an accurate map of a facility in order to plan the best +routes for executing workflows. Map creation is done using your robot to +record the its surroundings while it drives around the facility. + +## Making a Map + +:::note + +When you first receive your robot with IndoorNav it may have a map of +Clearpath's building and testing facility already saved on it. This map +may be discarded. + +::: + +To create a new map: + +1. [Refer to the mapping guidelines](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51849-mapping-guidelines.html). + +2. Open the Web GUI. + +3. Determine where map recording will begin and navigate the robot to + that position. Carefully select the starting position and alignment. + This point may be important in the future if updating a map or + remapping. A point that is central is recommended, but not required. + Note that the orientation of robot in relation to the facility when + beginning to record the map affects the orientation of the map as it + appears. When recording map data first beings, the direction in + which the front of the robot is facing will be the right side (east) + of the map. + +4. Select the **Facility** tab. + +5. From the upper toolbar, select **New Map**. The existing map (if + any) will disappear and be replaced with a new, blank map. To + download a copy of the current map click **Export Map.** To upload + an existing map, e.g. one saved from another robot, click **Import Map.** + +
+
+ +
+
+ +6. Select **REC** to begin recording the map. Select **Pause** at any + time to pause map data recording. + +
+
+ +
+
+ +7. Drive the robot through the facility manually, either using the web + GUI or the game controller. You will see light grey lines appear, + indicating where walls and other obstacles are. You should map all + locations where the robot is expected to navigate autonomously. + +8. To save the changes to the map, select **Save Map**. To cancel all + changes, select **Undo** or navigate to a new screen. + +# Using Map Features + +Once the map is made you can specify certain zones as off-limits to the +robot, designate certain areas as one-way traffic, restrict speed, or +simply add annotations to make the map easier to read. See +[Using Zones](#usage-zones) for more information about +creating zones on the map. + +To add zones and endpoints, use the menus found on the Facility +interface's main menu. + +
+
+ +
+
+ +:::note + +After adding, removing, or editing zones and endpoints, you must click +the +button on the main toolbar before navigating away from the page. Failing +to click this button may result in data being lost. + +::: + +## Adding Endpoints + +:::note + +See [detailed documentation on creating endpoints](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51866-creating-endpoints.html) +for more information. + +::: + +An endpoint is a physical location that sometimes includes a collection +of tasks that define how a robot performs a workflow. To add an endpoint +to the map: + +1. From the **Facility** menu select **Endpoints**. + +2. Select the appropriate type of endpoint from the list. + +3. Select the desired location on the map where the endpoint will be + created. An endpoint details pane will appear on the right side of + the window. If desired, orient the endpoint using the orientation + circle. Select and drag the middle of the orientation circle to move + the endpoint to a different location on the map. Select the drag the + edge of the orientation circle to rotate the endpoint. + +
+
+ +
+
+ +4. Enter a **Name** for the endpoint. + +5. If desired, enter a **Description**. + +6. The **X** and **Y** coordinates and **Rotation** (in degrees) of the + endpoint will be pre-populated based on the placement of the + endpoint. Use these fields to finely position the endpoint on the + map. + +7. Select **Done** to add the endpoint to the map. + +8. Select **Save** to save the changes to the map. To cancel all + changes, select **Undo** or navigate to a new screen. + +## Using Zones {#usage-zones} + +:::note + +See [detailed documentation on using zones](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51877-zones.html) +for more information. + +::: + +Zones define specific areas where robots can travel and their behavior +while within or near the zone such as maximum speed. + +Zones are polygons with three or more points making up a closed shape. +Zone placement isn't restricted by walls or other solid objects on the +map. + +To add a new zone to the map: + +1. Click the Map button on the main toolbar and select the desired type + of zone from the menu. +2. Click and drag on the map to add a new zone. Initially the zone will + be rectangular. +3. Update the zone shape as needed. You can add additional corners by + clicking on a segment and dragging it; a new corner will appear + under the mouse, allowing you to build more complex shapes. The + following figures show the process of creating a new zone and + editing its shape. + +
+
+ +
Initial shape made by clicking and dragging
+
+ +
+ +
Zone in its default shape
+
+ +
+ +
Same zone after clicking and dragging on the zone edges to add additional corners
+
+
+ +You can add further details about the zone using the configuration +tools, such as those shown for the Narrow Corridor Zone in the following +figure. + +
+
+ +
+
+ +Clicking on the +will allow you to change the type of zone, using the menu +shown in the figure below. When you have finished creating the zone +select **Done** on the upper toolbar. + +
+
+ +
+
+ +## Using Workflows + +:::note + +See [detailed documentation on creating workflows](https://docs.ottomotors.com/Archive/2-22/out/en/51722-51871-creating-workflows.html) +for more information. + +::: + +Workflows use endpoints to have a robot perform work automatically. When +a workflow is created, robots can execute them automatically when +autonomy is active. + +To create a workflow: + +1. From the **Facility** menu select **Endpoints**. +2. Select **A-B-C**. The workflow details pane will appear on the right + side of the window. +3. Enter a **Name** for the workflow. +4. Select **Add Task** to add a task to the workflow using endpoints + that have been created already. The tasks available for selection + are dependent on the endpoints that have been added to the map and + their types. +5. Select the desired tasks type. +6. Select the desired endpoint at which the selected task will be + performed. +7. Add additional tasks to the workflow as desired. +8. Select **Done** to add the workflow to the map. +9. Select **Save** to save the changes to the map. + +To execute a workflow: + +1. From the **Drive** menu select **Workflows**. +2. Select the desired workflow. +3. Select **GO**. The robot will attempt to execute the workflow. + Select **Stop** at any time to pause execution of the workflow. + Select **Resume** to continue the workflow. + +## Using Docking + +:::warning + +Keep the area around the dock free of objects and people. There is no +obstacle detection between pre-docking point and the dock; similarly, +there is no obstacle detection during the undocking operation. + +::: + +Docking is a feature for IndoorNav that requires the purchase of a dock +target. Refer to [Support](/docs_indoornav_user_manual/support.mdx) for +information on how to contact the sales team to purchase a dock. + +To include a dock in the workflow: + +1. **Mapping**: Position the dock in its intended position, then + proceed to map the area as usual, including the dock area. If the + dock was not included fully in the original map, remap the dock + area. + +
+
+ +
+
+ +2. **Placing Dock on the Map**: Once the map is created, overlay the + dock target onto the map as shown below by selecting "Charger + Endpoint" from the "Endpoints" menu and adding the charger on the + map such that it overlays the position from the mapping step. + +
+
+ +
+
+ +3. **Docking**: Select the "Dock Endpoint" and add it to the map so + that it is 2 metres away from the dock, positioned in the centre of + the dock, and oriented to point to the centre of the dock as shown + below. Then, update the desired workflow to make the "Dock + Endpoint" the last endpoint of the mission. + +
+
+ +
+
+ +4. **Undocking**: Add an "Undock Endpoint" at the position of the + robot when docked as shown below. Then, update the desired workflow + to make the "Undock Endpoint" the first endpoint of the mission. + +
+
+ +
+
+ +For clarity, when creating a mission that begins and ends with the robot +at the dock, use the Undock Endpoint as the first endpoint and the Dock +Endpoint as the last one. + +
+
+ +
+
diff --git a/docs_indoornav_user_manual/using_indoornav/usage_background.mdx b/docs_indoornav_user_manual/using_indoornav/usage_background.mdx index 9ff252afd..2b2f54feb 100644 --- a/docs_indoornav_user_manual/using_indoornav/usage_background.mdx +++ b/docs_indoornav_user_manual/using_indoornav/usage_background.mdx @@ -1,27 +1,27 @@ ---- -title: IndoorNav Software Overview -sidebar_label: IndoorNav Software Overview -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -This section will explain the basic usage of IndoorNav. For more -complete documentation, and a deeper dive into all of the available -features, please refer to the guides at -[http://docs.ottomotors.com](https://docs.ottomotors.com/Archive/2-22/out/index-222.html?lang=en). - -The following figure shows the basic layout of the networking for -IndoorNav. - - - -The robot's main PC is located inside the robot and runs the `roscore` -process. All sensors are connected to the robot's main PC over USB or -ethernet, as required by the specific sensor. - -The IndoorNav backpack PC communicates over an ethernet connection with -the main PC. All of the localization and path-planning is done on the -backpack PC. The backpack PC does not have any direct connection to the -wireless network; all traffic to/from the user's web browser is routed -via the robot's main PC. +--- +title: IndoorNav Software Overview +sidebar_label: IndoorNav Software Overview +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +This section will explain the basic usage of IndoorNav. For more +complete documentation, and a deeper dive into all of the available +features, please refer to the guides at +[http://docs.ottomotors.com](https://docs.ottomotors.com/Archive/2-22/out/index-222.html?lang=en). + +The following figure shows the basic layout of the networking for +IndoorNav. + + + +The robot's main PC is located inside the robot and runs the `roscore` +process. All sensors are connected to the robot's main PC over USB or +ethernet, as required by the specific sensor. + +The IndoorNav backpack PC communicates over an ethernet connection with +the main PC. All of the localization and path-planning is done on the +backpack PC. The backpack PC does not have any direct connection to the +wireless network; all traffic to/from the user's web browser is routed +via the robot's main PC. diff --git a/docs_indoornav_user_manual/using_indoornav/web_gui.mdx b/docs_indoornav_user_manual/using_indoornav/web_gui.mdx index 1c1242593..a032726f8 100644 --- a/docs_indoornav_user_manual/using_indoornav/web_gui.mdx +++ b/docs_indoornav_user_manual/using_indoornav/web_gui.mdx @@ -1,41 +1,41 @@ ---- -title: Web GUI -sidebar_label: Web GUI -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -The easiest method of interacting with IndoorNav is via the web GUI. The -following conditions must be met in order for the web GUI to function -correctly: - -1. IndoorNav is running (see [Manually Starting IndoorNav](/docs_indoornav_user_manual/base_robot_config/config_starting_manually.mdx) - or [Automatically Starting IndoorNav](/docs_indoornav_user_manual/base_robot_config/config_starting_automatically.mdx), -2. the robot is connected to a wireless access point, -3. your laptop or desktop is connected to the same network as the - robot, -4. you know the robot's IP address on the wireless network (or can - resolve its hostname to the wireless IP address), and -5. port-forwarding has been enabled on the robot. - -The web interface operates over `http` on port `TCP/5000`. - -
-
- -
-
- -To access the web interface, open your web browser and navigate to the -robot's IP address on port 5000, e.g.: ```http://192.168.0.197:5000``` - -:::note - -Google Chrome 62.x or later is recommended. Other modern browsers, such -as Firefox 95.x or later and Chromium 95.x or later will likely also -work, but have not been tested as thoroughly as Google Chrome. - -::: - -The following sections explain specific features of the Web GUI. +--- +title: Web GUI +sidebar_label: Web GUI +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The easiest method of interacting with IndoorNav is via the web GUI. The +following conditions must be met in order for the web GUI to function +correctly: + +1. IndoorNav is running (see [Manually Starting IndoorNav](/docs_indoornav_user_manual/base_robot_config/config_starting_manually.mdx) + or [Automatically Starting IndoorNav](/docs_indoornav_user_manual/base_robot_config/config_starting_automatically.mdx), +2. the robot is connected to a wireless access point, +3. your laptop or desktop is connected to the same network as the + robot, +4. you know the robot's IP address on the wireless network (or can + resolve its hostname to the wireless IP address), and +5. port-forwarding has been enabled on the robot. + +The web interface operates over `http` on port `TCP/5000`. + +
+
+ +
+
+ +To access the web interface, open your web browser and navigate to the +robot's IP address on port 5000, e.g.: ```http://192.168.0.197:5000``` + +:::note + +Google Chrome 62.x or later is recommended. Other modern browsers, such +as Firefox 95.x or later and Chromium 95.x or later will likely also +work, but have not been tested as thoroughly as Google Chrome. + +::: + +The following sections explain specific features of the Web GUI. diff --git a/docs_outdoornav_user_manual/_category_.json b/docs_outdoornav_user_manual/_category_.json index c123e1bc5..f5966a95c 100644 --- a/docs_outdoornav_user_manual/_category_.json +++ b/docs_outdoornav_user_manual/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/docs_outdoornav_user_manual/api/_category_.json b/docs_outdoornav_user_manual/api/_category_.json index a6e539204..79c716587 100644 --- a/docs_outdoornav_user_manual/api/_category_.json +++ b/docs_outdoornav_user_manual/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/docs_outdoornav_user_manual/api/api_overview.mdx b/docs_outdoornav_user_manual/api/api_overview.mdx index 4a56435b3..3c6055d67 100644 --- a/docs_outdoornav_user_manual/api/api_overview.mdx +++ b/docs_outdoornav_user_manual/api/api_overview.mdx @@ -1,26 +1,26 @@ ---- -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 2 Jazzy](https://docs.ros.org/en/jazzy/index.html) API. -The message and services types for the API are defined at: -https://github.com/clearpathrobotics/clearpath_msgs/tree/onav-ros2/clearpath_outdoornav_msgs - +--- +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 2 Jazzy](https://docs.ros.org/en/jazzy/index.html) API. +The message and services types for the API are defined at: +https://github.com/clearpathrobotics/clearpath_msgs/tree/onav-ros2/clearpath_outdoornav_msgs + More details on the API will be provided in a future release of the documentation. \ No newline at end of file diff --git a/docs_outdoornav_user_manual/index.mdx b/docs_outdoornav_user_manual/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/docs_outdoornav_user_manual/index.mdx +++ b/docs_outdoornav_user_manual/index.mdx @@ -1,18 +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 +--- +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/docs_outdoornav_user_manual/overview/_category_.json b/docs_outdoornav_user_manual/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/docs_outdoornav_user_manual/overview/_category_.json +++ b/docs_outdoornav_user_manual/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/docs_outdoornav_user_manual/overview/overview_introduction.mdx b/docs_outdoornav_user_manual/overview/overview_introduction.mdx index 95c7e2f43..21a17e203 100644 --- a/docs_outdoornav_user_manual/overview/overview_introduction.mdx +++ b/docs_outdoornav_user_manual/overview/overview_introduction.mdx @@ -1,79 +1,79 @@ ---- -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. - -## Key Features - -Key features of OutdoorNav Software include: - -- Mission Planning and Autonomous Navigation - - - Robust GPS-based localization with sensor fusion of camera, IMU, LiDAR - and platform odometry - - Autonomous path following through a network of paths - - 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 - -- 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 autonomy API - -- 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 +--- +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. + +## Key Features + +Key features of OutdoorNav Software include: + +- Mission Planning and Autonomous Navigation + + - Robust GPS-based localization with sensor fusion of camera, IMU, LiDAR + and platform odometry + - Autonomous path following through a network of paths + - 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 + +- 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 autonomy API + +- 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 diff --git a/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx b/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx index 134fadcc5..072e31800 100644 --- a/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx +++ b/docs_outdoornav_user_manual/overview/overview_operating_conditions.mdx @@ -1,113 +1,113 @@ ---- -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 - -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. With -standard sensors: - -- Location accuracy (position & heading): Less than 5 cm and less than 2° -- Path tracking accuracy (approximate): 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. | -| 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 3D LiDARs. Obstacle detection and avoidance may not function in all weather conditions and must be disabled to navigate in heavy snow or rain. | -| 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. | -| 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. | +--- +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 + +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. With +standard sensors: + +- Location accuracy (position & heading): Less than 5 cm and less than 2° +- Path tracking accuracy (approximate): 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. | +| 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 3D LiDARs. Obstacle detection and avoidance may not function in all weather conditions and must be disabled to navigate in heavy snow or rain. | +| 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. | +| 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. | diff --git a/docs_outdoornav_user_manual/overview/overview_scope.mdx b/docs_outdoornav_user_manual/overview/overview_scope.mdx index baf0b9f2d..5b741ff5c 100644 --- a/docs_outdoornav_user_manual/overview/overview_scope.mdx +++ b/docs_outdoornav_user_manual/overview/overview_scope.mdx @@ -1,13 +1,13 @@ ---- -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 +--- +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). \ No newline at end of file diff --git a/docs_outdoornav_user_manual/quick_start/_category_.json b/docs_outdoornav_user_manual/quick_start/_category_.json index f92c8e916..6a14af931 100644 --- a/docs_outdoornav_user_manual/quick_start/_category_.json +++ b/docs_outdoornav_user_manual/quick_start/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Quick Start", - "position": 5 -} +{ + "label": "Quick Start", + "position": 5 +} diff --git a/docs_outdoornav_user_manual/safety.mdx b/docs_outdoornav_user_manual/safety.mdx index 1de70c909..3f2d66458 100644 --- a/docs_outdoornav_user_manual/safety.mdx +++ b/docs_outdoornav_user_manual/safety.mdx @@ -1,139 +1,139 @@ ---- -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. - -- 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. +--- +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. + +- 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/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/integration_husky_a200_observer.mdx b/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/integration_husky_a200_observer.mdx index b159fd324..c5bc8c6b5 100644 --- a/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/integration_husky_a200_observer.mdx +++ b/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/integration_husky_a200_observer.mdx @@ -1,110 +1,110 @@ ---- -title: Husky A200 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 A200 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 A200 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 A200 Observer exterior, front view
-
-
- -[PACS™](../../accessories/pacs.mdx) 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/sensors.mdx) and [Accessories](../../accessories/add-ons/add-ons.mdx) 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 A200 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 A200 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 A200 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 A200 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. - ---- - - - ---- - -## Support {#support} - - +--- +title: Husky A200 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 A200 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 A200 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 A200 Observer exterior, front view
+
+
+ +[PACS™](../../accessories/pacs.mdx) 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/sensors.mdx) and [Accessories](../../accessories/add-ons/add-ons.mdx) 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 A200 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 A200 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 A200 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 A200 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. + +--- + + + +--- + +## Support {#support} + + diff --git a/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/maintenance_husky_a200_observer.mdx b/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/maintenance_husky_a200_observer.mdx index e89ac140f..f4dd8e542 100644 --- a/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/maintenance_husky_a200_observer.mdx +++ b/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/maintenance_husky_a200_observer.mdx @@ -1,337 +1,337 @@ ---- -title: Husky A200 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](user_manual_husky_a200_observer#autonomous-missions) for further details. - This method requires that the [base station has been surveyed](user_manual_husky_a200_observer#survey-base-station), - the [Datum has been set to the coordinates of the test site](user_manual_husky_a200_observer#set-datum), - and that the [dock location has been set](user_manual_husky_a200_observer#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 A200 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 A200 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 A200 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 A200 Observer are exhaust fans and, as such, -the filters on those fans do not require regular maintenance. - ---- - -## Software Maintenance {#software_maintenance} - -### Getting New Packages - - - -:::note - -In addition to the core software packages, which can be upgraded through the commands -noted above, Husky A200 Observer also includes OutdoorNav software, which can be -upgraded. -Contact [Support](#support) if you need more details on updating Husky A200 Observer software. - -::: - -### 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 A200 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 A200 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_a200_observer.mdx#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 A200 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} - - +--- +title: Husky A200 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](user_manual_husky_a200_observer#autonomous-missions) for further details. + This method requires that the [base station has been surveyed](user_manual_husky_a200_observer#survey-base-station), + the [Datum has been set to the coordinates of the test site](user_manual_husky_a200_observer#set-datum), + and that the [dock location has been set](user_manual_husky_a200_observer#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 A200 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 A200 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 A200 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 A200 Observer are exhaust fans and, as such, +the filters on those fans do not require regular maintenance. + +--- + +## Software Maintenance {#software_maintenance} + +### Getting New Packages + + + +:::note + +In addition to the core software packages, which can be upgraded through the commands +noted above, Husky A200 Observer also includes OutdoorNav software, which can be +upgraded. +Contact [Support](#support) if you need more details on updating Husky A200 Observer software. + +::: + +### 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 A200 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 A200 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_a200_observer.mdx#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 A200 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_robots/legacy/ros1_robots/solutions/husky_a200_observer/tutorials_husky_a200_observer.mdx b/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/tutorials_husky_a200_observer.mdx index f9a439cb7..6c61caf48 100644 --- a/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/tutorials_husky_a200_observer.mdx +++ b/docs_robots/legacy/ros1_robots/solutions/husky_a200_observer/tutorials_husky_a200_observer.mdx @@ -1,46 +1,46 @@ ---- -title: Husky A200 Observer Tutorials -sidebar_label: Tutorials -sidebar_position: 3 ---- - -import ComponentIntroductionHuskyObserver from "/components/introduction_husky_a200_observer.mdx"; -import Support from "/components/support.mdx"; - - - -## Husky A200 Observer Overview - -### Introduction - -Husky A200 Observer is a fully integrated system that enables robotics developers to accelerate inspection solutions. -It is built on top of the versatile [Husky](../../../ros1_robots/outdoor_robots/husky/user_manual_husky.mdx) 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 A200 Observer is built on the the Husky platform. See also the [Husky Tutorials](../../../ros1_robots/outdoor_robots/husky/tutorials_husky.mdx#husky-ros-packages). - -::: - ---- - -## Using Husky A200 Observer {#using-husky-observer} - -### Simulating Husky A200 -To simulate the Husky A200 Observer, including its full navigation stack, contact [Support](#support). - ---- - -## Support {#support} - - +--- +title: Husky A200 Observer Tutorials +sidebar_label: Tutorials +sidebar_position: 3 +--- + +import ComponentIntroductionHuskyObserver from "/components/introduction_husky_a200_observer.mdx"; +import Support from "/components/support.mdx"; + + + +## Husky A200 Observer Overview + +### Introduction + +Husky A200 Observer is a fully integrated system that enables robotics developers to accelerate inspection solutions. +It is built on top of the versatile [Husky](../../../ros1_robots/outdoor_robots/husky/user_manual_husky.mdx) 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 A200 Observer is built on the the Husky platform. See also the [Husky Tutorials](../../../ros1_robots/outdoor_robots/husky/tutorials_husky.mdx#husky-ros-packages). + +::: + +--- + +## Using Husky A200 Observer {#using-husky-observer} + +### Simulating Husky A200 +To simulate the Husky A200 Observer, including its full navigation stack, contact [Support](#support). + +--- + +## Support {#support} + + diff --git a/docs_robots/outdoor_robots/husky/a300/maintenance_husky.mdx b/docs_robots/outdoor_robots/husky/a300/maintenance_husky.mdx index bf7f8ffc2..40e46d8bc 100644 --- a/docs_robots/outdoor_robots/husky/a300/maintenance_husky.mdx +++ b/docs_robots/outdoor_robots/husky/a300/maintenance_husky.mdx @@ -88,6 +88,9 @@ During this visual inspection, ensure the robot is turned on and verify that: - The Status Lights are functioning correctly by pressing an Emergency Stop button and checking for the Emergency Stop light pattern. - The robot was not damaged during the last operation. +- The cable ties used to secure all four sets of motor cables are not broken (there should be two cable ties on each motor's cables). +- All four sets of the motor cables are not touching the adjacent wheel, and are secured by cable ties in a way that would prevent this from happening. +- The motor cables have not been damaged due to contact with the wheels. :::note @@ -105,7 +108,7 @@ to ensure that any water has drained out through the drain plug, and allow Husky The air filter is used to prevent dirt and dust from entering the robot at the front air intake. It must be cleaned or replaced on a regular basis. High-dust environments will require -more frequenct maintenance. +more frequent maintenance. :::note diff --git a/docs_robots/outdoor_robots/husky/a300/troubleshooting_husky.mdx b/docs_robots/outdoor_robots/husky/a300/troubleshooting_husky.mdx index d77f1a707..f929fceed 100644 --- a/docs_robots/outdoor_robots/husky/a300/troubleshooting_husky.mdx +++ b/docs_robots/outdoor_robots/husky/a300/troubleshooting_husky.mdx @@ -39,7 +39,7 @@ the image above). Gently lift the front panel up and out to free it. The serial number is on the white label indicated. It will be of the form `A300-#####`. To reinstall the front panel, reinsert the metal rods into the rubber bushings and press the panel -into place. Then rotate the two thumscrews outward to lock it into position. +into place. Then rotate the two thumbscrews outward to lock it into position. --- diff --git a/docs_robots/outdoor_robots/husky/a300/user_manual_husky.mdx b/docs_robots/outdoor_robots/husky/a300/user_manual_husky.mdx index 6f92f4843..8203054a3 100644 --- a/docs_robots/outdoor_robots/husky/a300/user_manual_husky.mdx +++ b/docs_robots/outdoor_robots/husky/a300/user_manual_husky.mdx @@ -1679,7 +1679,7 @@ Husky A300 is compatible with ROS 2 Jazzy. ## Maintenance -See [Husky A300 Maintenance](maintenance_husky) for details on Husky maintenance. +See [Husky A300 Maintenance](maintenance_husky.mdx) for details on Husky maintenance. --- @@ -1697,11 +1697,31 @@ recycling center per appropriate local regulations. ## Troubleshooting -See [Husky A300 Troubleshooting](troubleshooting_husky) for details on Husky troubleshooting. +See [Husky A300 Troubleshooting](troubleshooting_husky.mdx) for details on Husky troubleshooting. --- -## Declarations +## Standards Compliance + +- CE-marked + - EN 61326-1:2013 + - EN 301 489-1 V1.9.2 + - EN 61010-1:2010, EN 61010-1:2010/A1:2019/AC:2019-04, EN 61010-1:2010/A1:2019 + - EN 301 489-1 V1.9.2 + - EN 301 893 V2.1.1 + - EN 300 328 V2.2.2 +- FCC Part 15 Subpart B +- FCC Part 18 +- ICES-002 +- ICES-003 + +### Declarations + +This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: +(1) This device may not cause harmful interference, and (2) this device must accept any interference received, +including interference that may cause undesired operation. + +CAN ICES-003(A) / NMB-003(A) :::note @@ -1711,86 +1731,6 @@ invalidate the markings and may require additional conformity assessments. ::: -### FCC Supplier's Declaration of Conformity - -**47 CFR § 2.1077 Compliance Information** - -**Husky A300** - -**Responsible Party** - -Rockwell Automation, Inc. -1201 South Second Street -Milwaukee, Wisconsin -53204-2410 - -**Point of Contact** - -Ryan Gariepy, CTO (OTTO Motors and Clearpath Robotics)
-ryan.gariepy@rockwellautomation.com
-1-844-733-6886 - -This device complies with Part 15 of the FCC Rules. - -Operation is subject to the following two conditions: (1) this device may -not cause harmful interference, and (2) this device must accept any -interference received, including interference that may cause undesired operation. - -Contains Transmitter Module FCC ID: PD9AX210NG - -Changes or modifications not expressly approved by Clearpath Robotics Inc. could void -the user's authority to operate the equipment. - -This equipment has been tested and found to comply with the limits for a Class A -digital device, pursuant to Part 15 of the FCC Rules. These limits are designed to provide -reasonable protection against harmful interference when the equipment is operated in a -commercial environment. This product generates, uses, and can radiate radio frequency -energy and, if not installed and used in accordance with the manufacturer's instruction -manual, may cause harmful interference with radio communications. Operation of this -product in a residential area is likely to cause harmful interference, in which case you will -be required to correct the interference at your own expense. - -These limits are designed to provide reasonable protection against harmful interference in -a non-residential installation. However, there is no guarantee that interference will not -occur in a particular installation. -If this equipment does cause harmful interference to radio or television reception, which can -be determined by turning the equipment off and on, the user is encouraged to try to correct -the interference by one or more of the following measures: - - Reorient or relocate the receiving antenna. - - Increase the separation between the equipment and receiver. - - Connect the equipment into an outlet on a circuit different from that which the receiver is connected. - - Consult the dealer or an experienced radio/TV technician for help. - -FCC Radiation Exposure Statement: This product complies with FCC §2.1091(b) for mobile RF exposure limits, -set forth for an uncontrolled environment and is safe for the intended operation as described in this manual. -Per FCC requirements, maintain a distance of more than 8 inches (20 cm) between any person and the host device. - -### Innovation, Science and Economic Development Canada (ISED) Compliance Notice - -Contains Transmitter Module IC: 1000M-AX210NG - -This device contains a license-exempt transmitter/receiver that complies with Innovation, -Science and Economic Development (ISED) Canada's license-exempt RSS(s). Operation is -subject to the following 2 conditions: (1) this device may not cause interference, and -(2) this device must accept any interference, including interference that may cause -undesired operation of the device. - -CAN ICES-003(A) / NMB-003(A)
-CAN ICES-002(A) / NMB-002(A) - -This Class A digital apparatus complies with Canadian ICES-002 and ICES-003. - -Under Industry Canada regulations, this radio transmitter many only operate using an -antenna of a type and maximum (or lesser) gain approved for the transmitter by Industry -Canada. To reduce potential radio interference to other users, the antenna type and its -gain should be so chosen that the equivalent isotropically radiated power (e.i.r.p.) is -not more than the necessary for successful communication. - -ISED Radiation Exposure Statement: This product complies with the Canadian Standard -RSS-102 for portable RF exposure limits, set forth for an uncontrolled environment -and is safe for the intended operation as described in this manual. Per ISED requirements, -maintain a distance of more than 8 inches (20 cm) between any person and the host device. - --- ## Support {#support} diff --git a/docs_robots/solutions/husky_a300_amp/_category_.json b/docs_robots/solutions/husky_a300_amp/_category_.json index 6ff9061f4..5805b9f37 100644 --- a/docs_robots/solutions/husky_a300_amp/_category_.json +++ b/docs_robots/solutions/husky_a300_amp/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Husky A300 AMP", - "position": 1 -} +{ + "label": "Husky A300 AMP", + "position": 1 +} diff --git a/docs_robots/solutions/husky_a300_observer/_category_.json b/docs_robots/solutions/husky_a300_observer/_category_.json index 4a0a1624b..f0fe14338 100644 --- a/docs_robots/solutions/husky_a300_observer/_category_.json +++ b/docs_robots/solutions/husky_a300_observer/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Husky A300 Observer", - "position": 2 -} +{ + "label": "Husky A300 Observer", + "position": 2 +} diff --git a/docs_versioned_docs/version-ros1noetic/components/maintenance/_wd_ssd_critical_update.mdx b/docs_versioned_docs/version-ros1noetic/components/maintenance/_wd_ssd_critical_update.mdx index af280c77f..4085b0810 100644 --- a/docs_versioned_docs/version-ros1noetic/components/maintenance/_wd_ssd_critical_update.mdx +++ b/docs_versioned_docs/version-ros1noetic/components/maintenance/_wd_ssd_critical_update.mdx @@ -1,12 +1,12 @@ -:::warning - -Some computers shipped with a WD Blue SA510 SATA SSD, for which -the manufacturer has posted a -[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). - -Failure to perform the firmware update could result in permanent failure of the SSD. - -::: - -[See these instructions](../../accessories/computers/mini_itx#wd-firmware-update) to check if your SSD is +:::warning + +Some computers shipped with a WD Blue SA510 SATA SSD, for which +the manufacturer has posted a +[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). + +Failure to perform the firmware update could result in permanent failure of the SSD. + +::: + +[See these instructions](../../accessories/computers/mini_itx#wd-firmware-update) to check if your SSD is affected and to perform the update. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/components/maintenance/_wd_ssd_critical_update.mdx b/docs_versioned_docs/version-ros2humble/components/maintenance/_wd_ssd_critical_update.mdx index af280c77f..4085b0810 100644 --- a/docs_versioned_docs/version-ros2humble/components/maintenance/_wd_ssd_critical_update.mdx +++ b/docs_versioned_docs/version-ros2humble/components/maintenance/_wd_ssd_critical_update.mdx @@ -1,12 +1,12 @@ -:::warning - -Some computers shipped with a WD Blue SA510 SATA SSD, for which -the manufacturer has posted a -[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). - -Failure to perform the firmware update could result in permanent failure of the SSD. - -::: - -[See these instructions](../../accessories/computers/mini_itx#wd-firmware-update) to check if your SSD is +:::warning + +Some computers shipped with a WD Blue SA510 SATA SSD, for which +the manufacturer has posted a +[critical firmware update notice](https://support-en.sandisk.com/app/answers/detailweb/a_id/50208#subject2). + +Failure to perform the firmware update could result in permanent failure of the SSD. + +::: + +[See these instructions](../../accessories/computers/mini_itx#wd-firmware-update) to check if your SSD is affected and to perform the update. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/components/yaml/sensors/garmin_18x.mdx b/docs_versioned_docs/version-ros2humble/components/yaml/sensors/garmin_18x.mdx index 945378bda..9a581fc48 100644 --- a/docs_versioned_docs/version-ros2humble/components/yaml/sensors/garmin_18x.mdx +++ b/docs_versioned_docs/version-ros2humble/components/yaml/sensors/garmin_18x.mdx @@ -21,7 +21,7 @@ gps: nmea_navsat_driver: frame_id: gps_0_link port: "/dev/clearpath/gps" - baud: 115200 + baud: 19200 ``` diff --git a/docs_versioned_docs/version-ros2humble/components/yaml/sensors/img/ouster_os1.png b/docs_versioned_docs/version-ros2humble/components/yaml/sensors/img/ouster_os1.png new file mode 100644 index 000000000..933859597 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/components/yaml/sensors/img/ouster_os1.png differ diff --git a/docs_versioned_docs/version-ros2humble/components/yaml/sensors/ouster_os1.mdx b/docs_versioned_docs/version-ros2humble/components/yaml/sensors/ouster_os1.mdx new file mode 100644 index 000000000..49918474c --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/components/yaml/sensors/ouster_os1.mdx @@ -0,0 +1,43 @@ + + + + + +
+
+
+ +
+
+		 +
+ +```yaml +lidar3d: + - model: ouster_os1 + urdf_enabled: true + launch_enabled: true + parent: default_mount + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + ros_parameters: + ouster_driver: + sensor_hostname: 192.168.131.20 + udp_dest: 192.168.131.100 + lidar_port: 7502 + imu_port: 7503 + proc_mask: IMU|PCL|SCAN|IMG|RAW|TLM + use_system_default_qos: false +``` + +
+
+ +#### Package and Setup +Ouster lidars use the [`ouster_ros`](https://github.com/ouster-lidar/ouster-ros) driver. This is +an open-source driver, maintained by the manufacturer. + +For more specifics on the way Clearpath's configuration system launches the `ouster_ros` nodes, +see the Ouster [launch file](https://github.com/clearpathrobotics/clearpath_robot/blob/humble/clearpath_sensors/launch/ouster_os1.launch.py) +and the [default parameter file](https://github.com/clearpathrobotics/clearpath_robot/blob/humble/clearpath_sensors/config/ouster_os1.yaml) +in `clearpath_sensors`. diff --git a/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/lidar3d.mdx b/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/lidar3d.mdx index 4377371ad..0ae1a3283 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/lidar3d.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/lidar3d.mdx @@ -6,8 +6,12 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- import VelodyneLidar from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/velodyne_lidar.mdx"; +import OusterLidar from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/ouster_os1.mdx"; Three dimensional LiDARs provide a pointcloud of all points detected by several planar scanners at various angles, which is published as a `sensor_msgs/PointCloud2` message. It is important to accurately position the LiDAR in the visual descriptiuon of the robot to ensured that the scanned points are accurate with respect to the robot. ### Velodyne Lidar + +### Ouster Lidar + diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/controller.mdx b/docs_versioned_docs/version-ros2humble/ros/installation/controller.mdx index 685e99e63..e028de17f 100644 --- a/docs_versioned_docs/version-ros2humble/ros/installation/controller.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/installation/controller.mdx @@ -1,7 +1,7 @@ --- title: Joystick Controller Pairing sidebar_label: Joystick Controller -sidebar_position: 4 +sidebar_position: 5 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_create.png b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_create.png new file mode 100644 index 000000000..45bb35669 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_create.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_details.png b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_details.png new file mode 100644 index 000000000..0f91f28c7 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_details.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_detect_board.png b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_detect_board.png new file mode 100644 index 000000000..d24920706 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_detect_board.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_flash.png b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_flash.png new file mode 100644 index 000000000..8584a6ef5 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_flash.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_progress.png b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_progress.png new file mode 100644 index 000000000..bdb38ea3e Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/installation/img/jetpack_progress.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/nvidia.mdx b/docs_versioned_docs/version-ros2humble/ros/installation/nvidia.mdx new file mode 100644 index 000000000..18bc08e95 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/installation/nvidia.mdx @@ -0,0 +1,264 @@ +--- +title: Nvidia Jetson Installation +sidebar_label: Nvidia Jetson Installation +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +This page explains how to install Ubuntu 22.04 and ROS 2 Humble on an Nvidia Jetson computer. + +For installation instructions on a standard `amd64` computer, see [Robot Installation](robot.mdx) + +Nvidia Jetson computers can only be used as the primary computer in Jackal, Dingo, and Ridgeback platforms. + +::: + +## Install SDK Manager + +To install the OS on Nvidia Jetson computers, download Nvidia's [SDK Manager](https://developer.nvidia.com/sdk-manager) +program. This program is available for Ubuntu (as a `.deb` package), Windows (as a `.exe`), and in a Docker container. + +Download and install the appropriate version for your desktop from [Nvidia's website](https://developer.nvidia.com/sdk-manager). + +## Install JetPack 6.2 and SDKs + +Follow the instructions for your Jetson computer to power it on and connect it via USB to your desktop. Open SDK Manager. + +
+
+ +
+
+ +### Select harget hardware + +Ensure the **Jetson** category at the top of the window is checked and that the **Target Hardware** matches your +model of Jetson computer. If the board is not detected, refer to the instructions provided with your Jetson computer +for any additional steps that may be be needed, such as entering bootloader mode. + +### Select SDK version + +Select SDK version `6.2.x` (`6.2.1` is the latest at the time of writing). + +### Additional SDKs + +If desired, you may install additional SDKs. These are not required for ROS 2 Humble, but may be needed for specific +applications you intend to run on your robot. + +### Start the installer + +After selecting the appropriate options, click the green **Continue** button in the lower right of the window. + +## Details and license + +Review the selected components. You may customize which specific components will be installed by checking or +unchecking them. + +
+
+ +
+
+ +Check the license agreement at the bottom of the window and click the green **Continue** button. + +If the **Download folder** and **SDKs install folder** specified at the bottom of the window do not already exist on +your computer you will be prompted to create them. If this happens, click the green **Create** button. + +
+
+ +
+
+ +If you are running on Ubuntu you may be asked to enter your password to run some commands as `root`. + +### Wait for the download and installation to progress + +Wait for JetPack to downloading and install. Depending on your internet connection speed this may take some +time. + +
+
+ +
+
+ +The download and installation progress is shown at the bottom of the screen. If you need to pause the process, you can +press the green **Pause** button and resume the installation at a later time. + +## Flash the Jetson + +:::note + +Some Jetson computers skip this step. Please refer to the instructions for your specific computer. + +For example, **Forcecr** boards use a different set of steps, [documented here](https://www.forecr.io/blogs/installation/jetpack-6-x-installation-for-dsboard-ornx). + +::: + +After the download has proceeded sufficiently, SDK Manager will prompt you to flash your Jetson computer. + +
+
+ +
+
+ +Enter the username and password you intend to use to log into the Jetson computer. By default Clearpath Robotics uses +the username `administrator` and the password `clearpath`. + +When ready, click the green **Flash** button at the bottom of the window. + +## Post-installation configuration + +:::note + +See Clearpath's [computer Jetson setup script documentation](https://github.com/clearpathrobotics/clearpath_computer_installer/blob/jetson-setup/README.md) +for mode details on post-installation configuration. + +::: + +Once the core OS and Jetson APIs are installed the next step is to install the necessary ROS components to allow the +computer to control your robot. + +Connect the Jetson to the internet, log in, and run the following command to download and run Clearpath's +Jetson setup script: + +```bash +wget -c https://raw.githubusercontent.com/clearpathrobotics/clearpath_computer_installer/refs/heads/jetson-setup/jetson-humble-setup.bash && bash -e jetson-humble-setup.bash +``` + +This script will: +- (re-)configure `apt` with addional sources; +- install additional `apt` and `pip` packages needed for Clearpath robots; +- install core ROS components; +- create and build a ROS workspace (`$HOME/colcon_ws`); +- install additional Linux kernel modules; +- configure your robot's initial `/etc/clearpath/robot.yaml` file; and +- optionally reconfigure carrier board USB connections to enable bluetooth (required for teleop). + +### Missing ROS dependencies + +Manually running `rosdep install` in the generated workspace will result in warnings about some missing dependencies. +This is normal; the missing dependencies are for Clearpath platforms that are not supported on Jetson computers. + +If you see warnings about the following dependencies being uninstallable, you may safely ignore them: + +| ROS Package | Debian Package | Notes | +|:--------------------- |:-------------------------------- |:---------------------------------------------------------------------------------------------------------------- | +| `gazebo_ros2_control` | `ros-humble-gazebo-ros2-control` | Needed for simulation support by `ros2_kortex` (Kinova manipulator driver). Not currently available for ARM CPUs | +| `sevcon_traction` | `ros-humble-sevcon-traction` | Needed by Warthog W200, which cannot use an Nvidia Jetson as its primary computer | +| `valence_bms_driver` | `ros-humble-valence-bms-driver` | Needed for Valence batteries, which are not used in Jackal, Dingo, nor Ridgeback | + +## Building additional kernel modules + +At the time of writing, JetPack 6.1 installs the kernel `5.15.148-tegra`. This kernel by default does not include the +`uinput` and `slcan` modules. Clearpath has [pre-built copies](https://github.com/clearpathrobotics/clearpath_computer_installer/tree/jetson-setup) +of these modules for kernel `5.15.148-tegra`. + +If you have a different kernel, or want to build these modules yourself, follow +[Nvidia's developer guide](https://docs.nvidia.com/jetson/archives/r36.4.4/DeveloperGuide/SD/Kernel/KernelCustomization.html). +The essential steps are summarized below, but refer to Nvidia's kernel customization guide for more details. + +:::note + +The following instructions assume you are building the kernel and modules directly on the Jetson. To cross-compile, +refer to Nvidia's developer guide. + +::: + +### Install prerequisites + +Run the following command: + +```bash +sudo apt-get install build-essential bc flex bison libssl-dev zstd +``` + +### Download and extract the kernel sources + +:::note + +At the time of writing, the latest kernel sources are available at https://developer.nvidia.com/embedded/jetson-linux-r3644 + +::: + +Run the following commands: + +```bash +cd $HOME +wget https://developer.nvidia.com/downloads/embedded/l4t/r36_release_v4.4/sources/public_sources.tbz2 +tar xf public_sources.tbz2 +cd Linux_for_Tegra/source +tar xf kernel_src.tbz2 +``` + +### Customize the kernel modules + +To enable the `slcan` and `uinput` modules you must edit the kernel configuration file. + +```bash +echo "CONFIG_CAN_SLCAN=m" >> $HOME/Linux_for_Tegra/source/kernel/kernel-jammy-src/arch/arm64/configs/defconfig +echo "CONFIG_INPUT_UINPUT=m" >> $HOME/Linux_for_Tegra/source/kernel/kernel-jammy-src/arch/arm64/configs/defconfig +``` + +### Build the kernel and modules + +:::note + +This step can take some time. Be patient. + +::: + +Run the following commands to build the kernel and modules: + +```bash +cd $HOME/Linux_for_Tegra/source +mkdir kernel_out +./nvbuild.sh +``` + +### Install the modules + +After the build finishes, run the following commands to install the new modules: + +```bash +cd $HOME/Linux_for_Tegra/source/kernel_out/kernel/kernel-jammy-src +sudo cp drivers/net/can/socat.ko /lib/modules/$(uname -r)/kernel/drivers/net/can/ +sudo cp drivers/input/misc/uinput.ko /lib/modules/$(uname -r)/kernel/drivers/input/misc/ +sudo depmod +sudo modprobe slcan +sudo modprobe uinput +``` + +## Installing firmware updates + +If you need to [install firmware updates](robot#firmware-update) for your robot, you must install the +`clearpath_firmware` package on an `amd64` [offboard computer](offboard_pc); the +`clearpath_firmware` package is not available for ARM processors as a debian package. + +Connect the robot's MCU directly to the offboard computer (using either ethernet or USB, as appropriate for your +model of robot) and run +```bash +ros2 run clearpath_firmware flash +``` +on the offboard computer to update the firmware. diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx b/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx index 8d7e4a795..bd774a62b 100644 --- a/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx @@ -1,7 +1,7 @@ --- title: Offboard Computer Setup sidebar_label: Offboard Computer -sidebar_position: 3 +sidebar_position: 4 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/robot.mdx b/docs_versioned_docs/version-ros2humble/ros/installation/robot.mdx index 678e5252c..3d6036ef5 100644 --- a/docs_versioned_docs/version-ros2humble/ros/installation/robot.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/installation/robot.mdx @@ -13,13 +13,16 @@ import ComputerNetworkingSetupInstall from "../../components/networking/_compute ## Operating System (OS) {#operating-system} ROS 2 Humble uses Ubuntu 22.04 as its Tier 1 operating system. -Though other operating systems are supported, it is highly recommended to use Ubuntu 22.04. +Though other operating systems are supported, it is highly recommended to use Ubuntu 22.04. The preferred method is using the Clearpath Robotics ISO image, which is covered in this section. :::note The Clearpath Robotics ISO image only targets x86 computers (`amd64` architecture). +For installation on [Nvidia Jetson](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/) devices +see [Nvidia Installation](nvidia.mdx). + ::: Clearpath provides a lightly customized installation image of Ubuntu 22.04 that has the needed script to setup the robot. diff --git a/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/gazebo.mdx b/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/gazebo.mdx index 52b564f4c..bbb8626a6 100644 --- a/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/gazebo.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/gazebo.mdx @@ -1,7 +1,7 @@ --- title: Manipulation in Gazebo Ignition sidebar_label: Manipulation in Simulation -sidebar_position: 3 +sidebar_position: 1 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/remote.mdx b/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/remote.mdx new file mode 100644 index 000000000..5a4913442 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/tutorials/manipulation/remote.mdx @@ -0,0 +1,65 @@ +--- +title: Manipulation across Multiple Machines +sidebar_label: Multiple Machines +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +MoveIt! can require significant resources to generate complex manipulator trajectories. Ideally, a single powerful computer would handle the robot's nodes, sensor drivers, manipulator controllers, and MoveIt!. However, if a secondary computer is available onboard the robot and on the same local network, it could be used to handle some of the load of the primary platform computer. + +# MoveIt on Secondary Computer +The manipulators' controllers can be launched on the primary platform computer, while the motion planning can be launched independently on the secondary computer. + +The secondary computer does not need to be connected over ethernet to the primary platform computer, but doing so simplifies the networking setup which will not be covered in this tutorial. For more information on setting up networks with the ROS 2 middleware see the [networking section](../../networking/overview.mdx). + +## Setup +The secondary computer must have the same environment as the primary platform computer. Ensure that they both have the same version of packages, and if workspaces are required to build packages from source, they should be mirrored and built on the two computers. Then a `clearpath` setup directory must be created with the same `robot.yaml` as the one on the robot, see [offboard computer setup instructions](../../installation/offboard_pc.mdx) for more details. For the remainder of this tutorial, the `clearpath` setup directory will be assumed to be in the `home` directory. + +## Launching MoveIt! +Source all required workspaces on the secondary computer and generate all description, configuration, and launch files. +```bash +source /opt/ros/humble/setup.bash +``` + +### Generate Environment Setup +Generate the environment setup bash file. This file will contain any environment variables required to setup the networking between the multiple computer setup. +```bash +ros2 run clearpath_generator_common generate_bash -s $HOME/clearpath/ +``` + +This script will generate the `$HOME/clearpath/setup.bash` with the environment required to communicate with the primary platform computer. + +### Generate Description Files +Then, generate the description files: +```bash +ros2 run clearpath_generator_common generate_description -s $HOME/clearpath/ +ros2 run clearpath_generator_common generate_semantic_description -s $HOME/clearpath/ +``` +These scripts will generate the `robot.urdf.xacro`, `robot.srdf.xacro`, and `robot.srdf` files in the `$HOME/clearpath` directory which contain necessary robot description information to launch MoveIt!. + +### Generate Launch and Configuration Files +Then, generate the MoveIt! launch file and parameter file: +```bash +ros2 run clearpath_generator_robot generate_launch -s $HOME/clearpath/ +ros2 run clearpath_generator_robot generate_param -s $HOME/clearpath/ +``` + +These scripts will generate the `manipulators/launch/manipulators.launch.py` and `manipulators/config/moveit.config` files. + +### Launch +Once these files are all generated, launch MoveIt! by passing it the path to the directory: +``` +ros2 launch clearpath_manipulators moveit.launch.py setup_path:=$HOME/clearpath/ +``` + +## Launching RViz +Once MoveIt! is running, open RViz with the MoveIt MotionPlanning plugin, with the appropriate namespace, and interactive markers. To do so, create a new terminal, source the workspace, and call the `view_moveit` launch file: +``` +ros2 launch clearpath_viz view_moveit.launch.py namespace:='' +``` + +Make sure to pass the same namespace as the robot's. For example, a robot with namespace `a300_0001` will have topics such as `/a300_0001/platform/mcu/status` and `/a300_0001/manipulators/arm_0_joint_trajectory_controller/controller_state`. To launch its viewing command: +``` +ros2 launch clearpath_viz view_moveit.launch.py namespace:='a300_0001' +``` diff --git a/docs_versioned_docs/version-ros2jazzy/components/_clearpath_firmware.mdx b/docs_versioned_docs/version-ros2jazzy/components/_clearpath_firmware.mdx index faee52edd..1f05b518c 100644 --- a/docs_versioned_docs/version-ros2jazzy/components/_clearpath_firmware.mdx +++ b/docs_versioned_docs/version-ros2jazzy/components/_clearpath_firmware.mdx @@ -171,7 +171,7 @@ sudo apt-get install ros-jazzy-clearpath-firmware The DX100 MCU is mounted near the HMI panel towards the rear of the robot. To access it, remove the antennas and the center channel panel. - Connect the MCU to the onboard computer using a mini-USB cable connected to the port as shown below: + Connect the MCU to the onboard computer using a micro-USB cable connected to the port as shown below:
diff --git a/docs_versioned_docs/version-ros2jazzy/components/networking/_computer_networking_setup_install.mdx b/docs_versioned_docs/version-ros2jazzy/components/networking/_computer_networking_setup_install.mdx index 94e0fa1cc..5daa8a78a 100644 --- a/docs_versioned_docs/version-ros2jazzy/components/networking/_computer_networking_setup_install.mdx +++ b/docs_versioned_docs/version-ros2jazzy/components/networking/_computer_networking_setup_install.mdx @@ -1,6 +1,15 @@ -Clearpath robots use [`netplan`](https://netplan.io/) to configure all network connections, including wired and -wireless interfaces. The `netplan` package is installed on Ubuntu by default. +The `clearpath_computer_setup` package offers a terminal menu tool for configuring a robot computer. +The main feature of this tool is the ability to generate `netplan` configurations. The `clearpath_computer_setup` +package is available on the [Clearpath package server](../../ros/installation/robot.mdx#clearpath-package-server). -To edit the `netplan` configuration files you will also need a text editor. The `nano` and -`vi` editors are included by default, but additional editors such as `vim` or `emacs` can -also be installed using the `apt` command. +It should be installed on the robot's computer: + +``` +sudo apt install python3-clearpath-computer-setup +``` + +To run the tool, call: + +``` +sudo clearpath-computer-setup +``` diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_enclosure.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_enclosure.mdx new file mode 100644 index 000000000..39dc3d0e4 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_enclosure.mdx @@ -0,0 +1,39 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: enclosure + type: a300.amp_enclosure + model: default + parent: base_link + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true +``` +
+ +The top of the enclosure features user rails running down the full length, to allow easy mounting +of additional payloads. The `a300.amp_enclosure` URDF includes the following links that can be set +as the `parent_link` of other attachments: + +- `${name}_center_mount`: the centre of the upper surface of the enclosure. Items mounted to the + user rails should measure from this point. +- `${name}_antenna_mount`: the standard parent for the AMP Sensor Arch, located at the rear of the + user rails +- `${name}_front_lidar_mount`: located on the front face of the enclosure, this is the default location + for the AMP's front-facing 3D lidar +- `${name}_ins_mount`: located on the rear face of the enclosure, this is the default location for + the AMP's INS sensor + diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_sensor_arch.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_sensor_arch.mdx new file mode 100644 index 000000000..1d37839d9 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_sensor_arch.mdx @@ -0,0 +1,35 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: sensor_arch + type: a300.amp_sensor_arch + model: default + parent: enclosure_antenna_mount + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true +``` +
+ +The AMP sensor arch includes the following links to attach sensors and other accessories: +- `${name}_front_camera_mount`: located under the centre-top of the arch, this is the default + location for the front-facing teleoperation camera +- `${name}_rear_camera_mount`: located under the centre-top of the arch, this is the default + location for the rear-facing teleoperation camera +- `${name}_lidar_mount`: default mounting location for a secondary 3D lidar. This mount is only + usable when an additional bracket is physically installed on the arch. +- `${name}_left_antenna_mount`: the default mounting location for the GNSS/INS sensor's left antenna +- `${name}_right_antenna_mount`: the default mounting location for the GNSS/INS sensor's right antenna diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/bumper.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/bumper.mdx new file mode 100644 index 000000000..b1937ad70 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/bumper.mdx @@ -0,0 +1,34 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: front_bumper + type: a300.bumper + model: default + parent: front_bumper_mount + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true + - name: rear_bumper + type: a300.bumper + model: default + parent: rear_bumper_mount + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true +``` +
+ +The bumpers can be extended by setting the `extension` parameter. diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/amp_enclosure.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/amp_enclosure.png new file mode 100644 index 000000000..aa76f4c8c Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/amp_enclosure.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/amp_sensor_arch.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/amp_sensor_arch.png new file mode 100644 index 000000000..c4a41f061 Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/amp_sensor_arch.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/bumpers.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/bumpers.png new file mode 100644 index 000000000..5931096fe Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/bumpers.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/spotlights.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/spotlights.png new file mode 100644 index 000000000..af7d46afe Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/spotlights.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/top_plate_default.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/top_plate_default.png new file mode 100644 index 000000000..32a46ee64 Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/top_plate_default.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/top_plate_pacs.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/top_plate_pacs.png new file mode 100644 index 000000000..fb6df2e30 Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/top_plate_pacs.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/wireless_charger.png b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/wireless_charger.png new file mode 100644 index 000000000..5047f3742 Binary files /dev/null and b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/img/wireless_charger.png differ diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/spotlight.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/spotlight.mdx new file mode 100644 index 000000000..78e7e00d1 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/spotlight.mdx @@ -0,0 +1,38 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: driving_light_1 + type: a300.spotlight + parent: sensor_arch_front_left_corner_mount + xyz: [0.0, 0.0, -0.08] + rpy: [0.0, 0.5235987755982988, 0.5235987755982988] + - name: driving_light_2 + type: a300.spotlight + parent: sensor_arch_front_right_corner_mount + xyz: [0.0, 0.0, -0.08] + rpy: [0.0, 0.5235987755982988, -0.5235987755982988] + - name: driving_light_3 + type: a300.spotlight + parent: sensor_arch_rear_left_corner_mount + xyz: [0.0, 0.0, -0.08] + rpy: [0.0, 0.5235987755982988, -0.5235987755982988] + - name: driving_light_4 + type: a300.spotlight + parent: sensor_arch_rear_right_corner_mount + xyz: [0.0, 0.0, -0.08] + rpy: [0.0, 0.5235987755982988, 0.5235987755982988] +``` +
diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_default.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_default.mdx new file mode 100644 index 000000000..7519a94f7 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_default.mdx @@ -0,0 +1,31 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: top_plate + type: a300.top_plate + model: default + parent: default_mount + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true +``` +
+ +The default top plate has 3 mounting locations that can be used as the `parent_link` for sensors and other +attachments: +- `${name}_front_mount` at the front edge of the plate, +- `${name}_rear_mount` at the rear edge of the plate, and +- `${name}_default_mount` located in the centre of the plate. diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_pacs.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_pacs.mdx new file mode 100644 index 000000000..95e241b32 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_pacs.mdx @@ -0,0 +1,30 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: top_plate + type: a300.top_plate + model: pacs + parent: default_mount + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true +``` +
+ +Attach accessories to the top plate mounts by setting the accessory's `parent` parameter to one of the grid mounting +locations displayed above. The grid mounting locations span from `${name}_mount_a1` to `${name}_mount_e9`, where the +front left-most location is the `a1` mount and the rear right-most location is the `e9` mount. The letters correspond +to the columns and the number to the rows. diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/wireless_charger.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/wireless_charger.mdx new file mode 100644 index 000000000..2c9bb712d --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/wireless_charger.mdx @@ -0,0 +1,29 @@ + + + + + +
+
+
+ +
+
+		 + +```yaml +platform: + attachments: + - name: wireless_charger + type: a300.wireless_charger + model: default + parent: base_link + xyz: [0.0, 0.0, 0.0] + rpy: [0.0, 0.0, 0.0] + enabled: true +``` +
+ +The A300 can optionally be equipped with a wireless charging coil, mounted to the the right side of the robot. + +The `${name}_face` link is located in the centre of the charging coil's face, with the X axis pointing outwards. diff --git a/docs_versioned_docs/version-ros2jazzy/components/yaml/sensors/garmin_18x.mdx b/docs_versioned_docs/version-ros2jazzy/components/yaml/sensors/garmin_18x.mdx index 2c51e3905..bd2e557b9 100644 --- a/docs_versioned_docs/version-ros2jazzy/components/yaml/sensors/garmin_18x.mdx +++ b/docs_versioned_docs/version-ros2jazzy/components/yaml/sensors/garmin_18x.mdx @@ -21,7 +21,7 @@ gps: nmea_navsat_driver: frame_id: gps_0_link port: "/dev/clearpath/gps" - baud: 115200 + baud: 19200 ``` diff --git a/docs_versioned_docs/version-ros2jazzy/ros/api/mcu_api.mdx b/docs_versioned_docs/version-ros2jazzy/ros/api/mcu_api.mdx index a4ddf6fac..e083dcbca 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/api/mcu_api.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/api/mcu_api.mdx @@ -25,6 +25,7 @@ toc_max_heading_level: 4 ## MCU services -| Service | Service type | Server | Description | QoS | Platform | -| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------ | :------------- | :----------------------------------- | -| platform/mcu/configure | [clearpath_platform_msgs/ConfigureMcu](https://github.com/clearpathrobotics/clearpath_msgs/blob/jazzy/clearpath_platform_msgs/srv/ConfigureMcu.srv) | MCU node | Configure MCU domain ID and namespace | System default | A300, J100, DX100, DX150, R100, W200 | +| Service | Service type | Server | Description | QoS | Platform | +| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------ | :------------- | :----------------------------------- | +| platform/mcu/configure | [clearpath_platform_msgs/ConfigureMcu](https://github.com/clearpathrobotics/clearpath_msgs/blob/jazzy/clearpath_platform_msgs/srv/ConfigureMcu.srv) | MCU node | Configure MCU domain ID and namespace | System default | A300, J100, DX100, DX150, R100, W200 | +| platform/mcu/clear_estop_needs_reset | [std_srvs/Empty](https://github.com/ros2/common_interfaces/blob/jazzy/std_srvs/srv/Empty.srv) | MCU node | Clears a Needs Reset State | System default | A300 | diff --git a/docs_versioned_docs/version-ros2jazzy/ros/changelog.mdx b/docs_versioned_docs/version-ros2jazzy/ros/changelog.mdx index c05e6f592..22d92e8c6 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/changelog.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/changelog.mdx @@ -10,39 +10,72 @@ import Style from '/assets/css/changelog.css'; ## Current versions: -:::note -Nested packages are part of the top repository. -::: - -- clearpath_msgs: ![GitHub Tag](https://img.shields.io/github/v/tag/clearpathrobotics/clearpath_msgs?label=latest) - - clearpath_motor_msgs - - clearpath_msgs - - clearpath_platform_msgs -- clearpath_config: ![GitHub Tag](https://img.shields.io/github/v/tag/clearpathrobotics/clearpath_config?label=latest) -- clearpath_common: ![GitHub Tag](https://img.shields.io/github/v/tag/clearpathrobotics/clearpath_common?label=latest) - - clearpath_bt_joy - - clearpath_common - - clearpath_control - - clearpath_customization - - clearpath_description - - clearpath_diagnostics - - clearpath_generator_common - - clearpath_manipulators - - clearpath_manipulators_description - - clearpath_mounts_description - - clearpath_platform_description - - clearpath_sensors_description -- clearpath_robot: ![GitHub Tag](https://img.shields.io/github/v/tag/clearpathrobotics/clearpath_robot?label=latest) - - clearpath_generator_robot - - clearpath_platform - - lynx_motor_driver - - puma_motor_driver - - clearpath_robot - - clearpath_sensors - - clearpath_tests - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Github RepositoryVersionROS Packages
clearpath_msgsGitHub Tag +
    +
  • clearpath_motor_msgs
    • +
  • clearpath_msgs
    • +
  • clearpath_platform_msgs
    • +
+
clearpath_configGitHub Tag +
    +
  • clearpath_config
    • +
+
clearpath_commonGitHub Tag +
    +
  • clearpath_bt_joy
    • +
  • clearpath_common
    • +
  • clearpath_control
    • +
  • clearpath_customization
    • +
  • clearpath_description
    • +
  • clearpath_diagnostics
    • +
  • clearpath_generator_common
    • +
  • clearpath_manipulators
    • +
  • clearpath_manipulators_description
    • +
  • clearpath_mounts_description
    • +
  • clearpath_platform_description
    • +
  • clearpath_sensors_description
    • +
+
clearpath_robotGitHub Tag +
    +
  • clearpath_generator_robot
    • +
  • clearpath_platform
    • +
  • lynx_motor_driver
    • +
  • puma_motor_driver
    • +
  • clearpath_robot
    • +
  • clearpath_sensors
    • +
  • clearpath_tests
    • +
+
## [2.6] 2025-07-04 @@ -55,15 +88,15 @@ Nested packages are part of the top repository. - Added support for W200 - Enabled foxglove bridge by default - Added A300 AMP attachments, samples -- Added foxglove dependency +- Added foxglove dependency - Enabled dependency on sevcon and valence bms - Updated grab-diagnostics to latest ### Fixed - Fixed W200 Diff Drive Parameters - Re-enable publishing controller input to joy_teleop/cmd_vel -- Dropped A200 controller manager update rate -- Fixed expected diagnostics rates +- Dropped A200 controller manager update rate +- Fixed expected diagnostics rates - Fixed missing dependency lms1xx ## [2.5] 2025-05-30 diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/_category_.json b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/_category_.json index 2687e472b..ae5aadafa 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/_category_.json +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/_category_.json @@ -1,4 +1,4 @@ { "label": "Attachments", - "position": 2 + "position": 3 } diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a200.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a200.mdx index d6f9dd87e..aa3a78463 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a200.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a200.mdx @@ -1,7 +1,7 @@ --- title: A200 Attachments sidebar_label: A200 -sidebar_position: 2 +sidebar_position: 3 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a300.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a300.mdx new file mode 100644 index 000000000..fe9f75ff8 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/a300.mdx @@ -0,0 +1,65 @@ +--- +title: A300 Attachments +sidebar_label: A300 +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- +import A300AmpEnclosure from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_enclosure.mdx"; +import A300AmpSensorArch from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/amp_sensor_arch.mdx"; +import A300Bumper from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/bumper.mdx"; +import A300Spotlight from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/spotlight.mdx"; +import A300TopPlateDefault from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_default.mdx"; +import A300TopPlatePacs from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/top_plate_pacs.mdx"; +import A300WirelessCharger from "/docs_versioned_docs/version-ros2jazzy/components/yaml/attachments/a300/wireless_charger.mdx"; + +## Bumper + +The A300 can have bumpers. By default, we have two bumpers, on the front and rear of the robot. + + + + +## Top Plate + +The A300 description supports two types of top plates that modify the mounting links of the robot. + +### Default + +The **default** top plate is mounted on top of the robot. + +
+ +### PACS +The **PACS** top is physically identical to the **default** plate, but adds PACS-compatible mounting links. + +
+ +## Wireless Charger + + + +## AMP Attachments + +The Husky AMP (Autonomous Mobile Platform) has large enclosure on top to contain additional computers, sensors, and +power-distribution equipment and an arch to support additional sensors. These attachments can be added to +the A300 just like any other attachment. + +### AMP Enclosure + +If the AMP Enclosure is used, the [top plate](#top-plate) should be omitted. + + + +### AMP Sensor Arch + +The AMP sensor arch is used to attach additional sensors and antennas. + + + +### Spotlights + +The AMP is equipped with multiple spotlights to assist in teleoperation in dark environments. The models also include +simulated light sources when used with [Gazebo](../../../../tutorials/simulator/overview.mdx) + + diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/dx1X0.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/dx1X0.mdx index acd2e631c..5e2a3b37c 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/dx1X0.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/dx1X0.mdx @@ -1,7 +1,7 @@ --- title: DD1X0 and DO1X0 Attachments sidebar_label: DD1X0 & DO1X0 -sidebar_position: 5 +sidebar_position: 6 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/j100.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/j100.mdx index 2f51ad011..d148c67e2 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/j100.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/j100.mdx @@ -1,7 +1,7 @@ --- title: J100 Attachments sidebar_label: J100 -sidebar_position: 3 +sidebar_position: 4 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/r100.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/r100.mdx index 838cbd470..29988935a 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/r100.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/r100.mdx @@ -1,7 +1,7 @@ --- title: R100 Attachments sidebar_label: R100 -sidebar_position: 6 +sidebar_position: 7 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/w200.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/w200.mdx index 956170b13..d8c6c7d1c 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/w200.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/attachments/w200.mdx @@ -1,7 +1,7 @@ --- title: W200 Attachments sidebar_label: W200 -sidebar_position: 4 +sidebar_position: 5 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/battery.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/battery.mdx index f5f0fc85e..b4599d84c 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/battery.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/battery.mdx @@ -1,7 +1,7 @@ --- title: Battery sidebar_label: Battery -sidebar_position: 3 +sidebar_position: 4 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/can.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/can.mdx index 83a4bc5ec..ffe1e1526 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/can.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/can.mdx @@ -1,7 +1,7 @@ --- title: CAN Adapters sidebar_label: CAN Adapters -sidebar_position: 8 +sidebar_position: 9 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/controller.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/controller.mdx index c2fdb4512..5f8c24c93 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/controller.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/controller.mdx @@ -1,10 +1,12 @@ --- title: Controller sidebar_label: Controller -sidebar_position: 4 +sidebar_position: 5 toc_min_heading_level: 2 toc_max_heading_level: 5 --- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; We support the following types of controllers on all platforms: - **ps4**: standard Playstation4 controller (bluetooth). @@ -18,6 +20,51 @@ Switching between each is done by setting the `controller` parameter under the ` controller: ps4 # one of ps4, ps5, logitech, xbox ``` +## Default Button Mappings + +By default, Clearpath platforms use the left and right triggers (typically buttons L1, R1) as the normal deadman and turbo deadman buttons respectively. The vertical axis of the left joystick will control linear speed in the X direction, and the horizontal axis controls angular speed. For omnidirectional robots, +the horizontal axis of the right joystick will control linear speed in the Y direction. + +### Changing Button Mappings + +If you wish to change the default button mappings, this can be modified by using the +[`extras.ros_parameters`](extras) field in `robot.yaml`. First, find the [default configuration](https://github.com/clearpathrobotics/clearpath_common/tree/jazzy/clearpath_control/config/generic) file for your controller. +The comments at the top of the file will describe the axis mappings relative to the controller buttons. This varies between controllers. + +Next, modify the `teleop_twist_joy_node` parameters with your updated button mappings. Here are some examples: + + + +```yaml +extras: + ros_parameters: + teleop_twist_joy_node: + axis_linear.x: 4 + axis_angular.yaw: 3 + enable_button: 5 + enable_turbo_button: 4 +``` + + +```yaml +extras: + ros_parameters: + teleop_twist_joy_node: + axis_linear.y: 0 + axis_angular.yaw: 3 +``` + + +```yaml +extras: + ros_parameters: + teleop_twist_joy_node: + enable_button: 6 + enable_turbo_button: 7 +``` + + + ## Teleop Speeds By default, holding the left trigger button of the controller enables driving at "normal" speeds @@ -52,12 +99,12 @@ extras: **Normal speed parameters** - `scale_linear.x` sets the maximum forward/reverse velocity -- `scale_linear.y` sets the maximum left/right velocity (Dingo-O and Ridgeback only) +- `scale_linear.y` sets the maximum left/right velocity (Omnidirectional control only) - `scale_angular.z` sets the maximum angular velocity **Turbo speed parameters** - `scale_linear_turbo.x` sets the maximum forward/reverse velocity -- `scale_linear_turbo.y` sets the maximum left/right velocity (Dingo-O and Ridgeback only) +- `scale_linear_turbo.y` sets the maximum left/right velocity (Omnidirectional control only) - `scale_angular_turbo.z` sets the maximum angular velocity :::warning @@ -66,4 +113,26 @@ Do not set the normal or turbo velocity limits higher than the robot's maximum v may make the robot difficult to control. The robot will not exceed its maximum speed, but the scaling on the joystick may result in awkward clipping, causing teleoperation to be jerky. -::: \ No newline at end of file +::: + +## Changing the `joy` device + +By default the `joy_node` will open one of the following devices, created by a `udev` rule included in +the `clearpath_robot` package: + +| Controller type | Linux `joy` device | +|:--------------- |:------------------ | +| `ps4` | `/dev/input/ps4` | +| `ps5` | `/dev/input/ps5` | +| `xbox` | `/dev/input/xbox` | +| `logitech` | `/dev/input/f710` | + +To manually specify a different device file or symlink, use the [`extras.ros_parameters`](extras) field in +`robot.yaml`, for example: + +```yaml +extras: + ros_parameters: + joy_node: + dev: /dev/input/js0 +``` diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/drivetrain.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/drivetrain.mdx new file mode 100644 index 000000000..5dab9e492 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/drivetrain.mdx @@ -0,0 +1,99 @@ +--- +title: Drivetrain +sidebar_label: Drivetrain +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Each platform comes with a default drivetrain controller and set of wheels. Some platforms support different controllers, and some support multiple wheel types. The `drivetrain` section determines which velocity controller to load, and which wheels to define in the robot description. + +The following drivetrain controllers are supported: +- `diff_4wd`: Differential four-wheel drive +- `diff_fwd`: Differential front-wheel drive +- `diff_rwd`: Differential rear-wheel drive +- `omni_4wd`: Omnidirectional four-wheel drive + +:::note + +The control type is determined by which wheels are controlled, not how many motors a platform has. An A200 has one motor per side which control two motors each, so it can only be `diff_4wd`. + +::: + +The following wheel types are supported: +- `outdoor`: Rugged outdoor wheels +- `indoor`: Smooth indoor wheels +- `mecanum`: Roller wheels for omnidirectional control +- `tracks`: Continuous track system +- `caster`: Uncontrolled caster wheels + +The `drivetrain` section defines the keys `control` and `wheels` to set these parameters. Under `wheel`, the `front` and `rear` wheels are set separately. Some example configurations are shown below. + + + +``` +drivetrain: + control: diff_4wd + wheels: + front: outdoor + rear: outdoor +``` + + + +``` +drivetrain: + control: omni_4wd + wheels: + front: mecanum + rear: meceanum +``` + + +``` +drivetrain: + control: diff_fwd + wheels: + front: indoor + rear: caster +``` + + +``` +drivetrain: + control: diff_rwd + wheels: + front: caster + rear: outdoor +``` + + + +:::note + +Not all configurations are valid. For example, an `omni_4wd` controller must be matched with four `mecanum` wheels. Also, `caster` wheels cannot be attached to wheels which are controlled. + +::: + + +## Supported controllers and wheels + +| Platform | Control | Front Wheels | Rear Wheels | +| :------: | :-------------------------------------------------------------: | :----------------------------------------: | :----------------------------------------: | +| A200 | [`diff_4wd`] | [`outdoor`]
`indoor` | [`outdoor`]
`indoor` | +| A300 | [`diff_4wd`]
`diff_fwd`
`diff_rwd`
`omni_4wd` | [`outdoor`]
`mecanum`
`caster` | [`outdoor`]
`mecanum`
`caster` | +| J100 | [`diff_4wd`] | [`outdoor`] | [`outdoor`] | +| W200 | [`diff_4wd`] | [`outdoor`]
`tracks` | [`outdoor`]
`tracks` | +| DD100 | [`diff_fwd`] | [`indoor`] | [`caster`] | +| DO100 | [`omni_4wd`]
`diff_4wd` | [`mecanum`] | [`mecanum`] | +| DD150 | [`diff_fwd`] | [`indoor`] | [`caster`] | +| DO150 | [`omni_4wd`]
`diff_4wd` | [`mecanum`] | [`mecanum`] | +| R100 | [`omni_4wd`]
`diff_4wd` | [`mecanum`] | [`mecanum`] | + +:::note + +Default configurations are noted with square brackets. + +::: \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/ekf.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/ekf.mdx index 38f6ab11a..ccacb4f9e 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/ekf.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/ekf.mdx @@ -1,7 +1,7 @@ --- title: Enable/Disable EKF sidebar_label: Enable EKF -sidebar_position: 5 +sidebar_position: 6 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx index 0726a93ff..b57d619dc 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/extras.mdx @@ -1,7 +1,7 @@ --- title: Extras sidebar_label: Extras -sidebar_position: 9 +sidebar_position: 10 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/foxglove_bridge.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/foxglove_bridge.mdx index f9edc9b98..59c7cfef4 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/foxglove_bridge.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/foxglove_bridge.mdx @@ -1,7 +1,7 @@ --- title: Enable/Disable Foxglove Bridge sidebar_label: Enable Foxglove Bridge -sidebar_position: 7 +sidebar_position: 8 toc_min_heading_level: 2 toc_max_heading_level: 5 --- @@ -10,11 +10,11 @@ By default, all Clearpath platforms launch a [Foxglove bridge node](https://docs as part of the diagnostics features. This is required for the [Cockpit ROS 2 Diagnostic extension](../../../cockpit/ros2_diagnostics.mdx). If the Cockpit webserver is not being used then the node can be disabled. -| Key | Value / Datatype | Description | -| :---------------------: | :--------------: | ------------------------------------------------------------- | -| enable_foxglove_bridge: | boolean | Enables or disables the Foxglove bridge node. Default: `false` | +| Key | Value / Datatype | Description | +| :---------------------: | :--------------: | ------------------------------------------------------------------------------- | +| enable_foxglove_bridge: | boolean | Enables or disables the Foxglove bridge node. Default: `true` as of version 2.6 | -For example, to disable the EKF node: +For example, to disable the Foxglove bridge node: ```yaml platform: diff --git a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/wireless_watcher.mdx b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/wireless_watcher.mdx index 0408e288a..f595a1ada 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/wireless_watcher.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/config/yaml/platform/wireless_watcher.mdx @@ -1,7 +1,7 @@ --- title: Enable/Disable Wireless Watcher sidebar_label: Enable Wireless Watcher -sidebar_position: 6 +sidebar_position: 7 toc_min_heading_level: 2 toc_max_heading_level: 5 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/installation/controller.mdx b/docs_versioned_docs/version-ros2jazzy/ros/installation/controller.mdx index 7509a8ca3..1d15d12bb 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/installation/controller.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/installation/controller.mdx @@ -1,7 +1,7 @@ --- title: Joystick Controller Pairing sidebar_label: Joystick Controller -sidebar_position: 5 +sidebar_position: 7 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/installation/cuda.mdx b/docs_versioned_docs/version-ros2jazzy/ros/installation/cuda.mdx new file mode 100644 index 000000000..7a739e8fa --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/ros/installation/cuda.mdx @@ -0,0 +1,112 @@ +--- +title: CUDA Installation +sidebar_label: CUDA Installation +sidebar_position: 8 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +CUDA is a proprietary framework developed by Nvidia. To use CUDA you must have a compatible GPU from Nvidia. + +::: + +## Verify your GPU supports CUDA + +To check that you have an Nvidia GPU, run the following command: + +```bash +lspci | grep -i nvidia +``` + +Check that +1. there is at least one graphics card listed, and +2. that your GPU model [supports CUDA](https://developer.nvidia.com/cuda-gpus) + +## Add Nvidia package sources + +The easiest way to install CUDA is to add Nvidia's `apt` sources to your configuration. Run the following +commands on the robot: + +```bash +wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb +sudo dpkg -i cuda-keyring_1.1-1_all.deb +sudo apt-get update +``` + +## Install CUDA + +:::note + +If you have a realtime Linux kernel installed (`PREEMPT_RT`) you may encounter errors when installing CUDA, as it +does not officially support realtime kernels. To work around these errors add `IGNORE_PREEMPT_RT_PRESENCE=1` +before any `apt` or `apt-get` commands, e.g. +``` +sudo IGNORE_PREEMPT_RT_PRESENCE=1 apt-get install cuda-toolkit +``` + +::: + +To install CUDA, run the following command: +```bash +sudo apt-get install cuda-toolkit +``` + +Optionally you can also install all GDS packages: +```bash +sudo apt-get install nvidia-gds +``` + +Reboot the computer after installing the packages. + +## Configure environment + +:::note + +At the time of writing, CUDA `12.9` is the latest version. The instructions below assume this version is +being installed, but if you installed a different version you will need to modify the instructions +accordingly. + +::: + +After rebooting, it is recommended to modify `$HOME/.bashrc` to update your environment variables to +enable CUDA tools. Add the following to `.bashrc`: + +``` +export PATH=/usr/local/cuda-12.9/bin${PATH:+:${PATH}} +export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/cuda-12.9/lib64 +``` + +After modifying `.bashrc` either close the terminal and re-open it or run `source $HOME/.bashrc` to apply +the changes. + +### CUDA samples + +You can optionally download and build the [CUDA samples](https://github.com/NVIDIA/cuda-samples) to verify +your installation: + +```bash +git clone https://github.com/NVIDIA/cuda-samples.git +cd cuda-samples +mkdir build +cd build +cmake .. +make +``` + +Run the `deviceQuery` sample from the `build` directory to make sure CUDA can run correctly on your system: +```bash +./Samples/1_Utilities/deviceQuery/deviceQuery +``` +You should see `Result = PASS` at the bottom of the output, indicating a CUDA-capable GPU was is +detected and usable. + +Refer the [CUDA samples documentation](https://github.com/NVIDIA/cuda-samples/tree/master?tab=readme-ov-file#samples-list) +for details on additional sample programs. + +## External Links + +- [CUDA installation guide for Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/) +- [CUDA supported GPUs](https://developer.nvidia.com/cuda-gpus) +- [CUDA samples](https://github.com/NVIDIA/cuda-samples) diff --git a/docs_versioned_docs/version-ros2jazzy/ros/installation/nvidia.mdx b/docs_versioned_docs/version-ros2jazzy/ros/installation/nvidia.mdx new file mode 100644 index 000000000..7c3845b30 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/ros/installation/nvidia.mdx @@ -0,0 +1,17 @@ +--- +title: Nvidia Jetson Installation +sidebar_label: Nvidia Jetson Installation +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Nvidia does not currently support installing Ubuntu 24.04 on Jetson computers. ROS 2 Jazzy cannot +be used on Jetson computers at this time. + +To install Ubuntu 22.04 and ROS 2 Humble on a Jetson computer, see the +[Humble installation guide](/docs/ros2humble/ros/installation/nvidia). + +::: diff --git a/docs_versioned_docs/version-ros2jazzy/ros/installation/offboard_pc.mdx b/docs_versioned_docs/version-ros2jazzy/ros/installation/offboard_pc.mdx index 14456cfe6..b12923af9 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/installation/offboard_pc.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/installation/offboard_pc.mdx @@ -1,7 +1,7 @@ --- title: Offboard Computer Setup sidebar_label: Offboard Computer -sidebar_position: 4 +sidebar_position: 5 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/installation/updates.mdx b/docs_versioned_docs/version-ros2jazzy/ros/installation/updates.mdx index 6891555fc..6ccffe0bb 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/installation/updates.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/installation/updates.mdx @@ -2,7 +2,7 @@ title: Installing Updates sidebar_label: Installing Updates sidebar_position: 1 -toc_min_heading_level: 2 +toc_min_heading_level: 4 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/installation/upgrading.mdx b/docs_versioned_docs/version-ros2jazzy/ros/installation/upgrading.mdx index 61810bce0..b863024c1 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/installation/upgrading.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/installation/upgrading.mdx @@ -1,7 +1,7 @@ --- title: Upgrading to Jazzy sidebar_label: Upgrading to Jazzy -sidebar_position: 2 +sidebar_position: 6 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/networking/computer_setup.mdx b/docs_versioned_docs/version-ros2jazzy/ros/networking/computer_setup.mdx index 05614be60..175162024 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/networking/computer_setup.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/networking/computer_setup.mdx @@ -5,130 +5,565 @@ sidebar_position: 2 import ComputerNetworkingSetupInstall from "../../components/networking/_computer_networking_setup_install.mdx"; import StandardClearpathBridgeSetup from "../../components/networking/_standard_clearpath_bridge_setup.mdx"; - - -## Connecting to an Existing Wi-Fi Network {#netplan-wifi} - -Use `netplan` to connect your robot to an existing wireless network. - -First, determine the name of your wireless interface by running `iwconfig` you should see -an entry similar to this: - -``` -wlp59s0 IEEE 802.11 ESSID:off/any - Mode:Managed Access Point: Not-Associated Tx-Power=off - Retry short limit:7 RTS thr:off Fragment thr:off - Power Management:on -``` - -The interface name is in the left column, starting with `w`. - -Once you have identified your interface, edit or create a file -called `/etc/netplan/60-wifi.yaml` containing the following: - -```yaml -network: - wifis: - MY_WIFI_INTERFACE: - optional: true - access-points: - MY_WIFI_SSID: - password: MY_WIFI_PASSWORD - dhcp4: true -``` - -with the following substitutions: -1. Replace `MY_WIFI_INTERFACE` with the name of the interface you identified in the first step, - e.g. `wlp59s0` -2. Replace `MY_WIFI_SSID` with the SSID of your network. -3. Replace `MY_WIFI_PASSWORD` with your network's password. - -For example: - -```yaml -network: - wifis: - wlp59s0: - optional: true - access-points: - BabCom: - password: peekaboo - dhcp4: true -``` +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; -This configuration will connect your robot via DHCP to your WPA2/3 wireless network. If you -need to use a static IP address, modify the file to contain the following: - -```yaml -network: - wifis: - MY_WIFI_INTERFACE: - optional: true - access-points: - MY_WIFI_SSID: - password: MY_WIFI_PASSWORD - dhcp4: false - dhcp4-overrides: - send-hostname: true - addresses: - - MY_STATIC_IP/MY_SUBNET - nameservers: - addresses: - - MY_NAMESERVER -``` +:::note -with the same substitutions noted earlier, plus -1. Replace `MY_STATIC_IP` with the desired static IP address. -2. Replace `MY_SUBNET` with the length of your network's subnet mask (typically `24` or `16`) -3. Replace `MY_NAMESERVER` with the IP address of your DNS server You may add multiple DNS servers - with each one on its own line. - -For example: - -```yaml -network: - wifis: - wlp59s0: - optional: true - access-points: - BabCom: - password: peekaboo - dhcp4: false - dhcp4-overrides: - send-hostname: true - addresses: - - 10.25.0.134/16 - nameservers: - addresses: - - 10.25.0.10 - - 8.8.8.8 - - 8.8.4.4 -``` + -Once you have edited the netplan configuration file, run the following two commands: -1. `sudo netplan --debug generate` -- this will verify that the netplan configuration files can - be read properly. Correct any errors before proceeding. -2. `sudo netplan try` -- this will try running the new configuration, but will automatically - roll back if it doesn't work correctly. -3. `sudo netplan apply` -- this will apply the new configuration to your network interfaces. +::: -:::note +## Connecting to an Existing Wi-Fi Network {#netplan-wifi} -By convention, all Netplan configuration files should be prefixed with two numbers indicating the -order in which the file should be read. Files are read in alphanumeric order, with `00-` prefixes -first and `99-` prefixes last. + + + + Use the `sudo clearpath-computer-setup` command to connect your robot to an existing wireless network. + + ``` + ___ _ _ ___ _ ___ _ + | _ \___| |__ ___| |_ / __|___ _ __ _ __ _ _| |_ ___ _ _ / __| ___| |_ _ _ _ __ + | / _ \ '_ \/ _ \ _| | (__/ _ \ ' \| '_ \ || | _/ -_) '_| \__ \/ -_) _| || | '_ \ + |_|_\___/_.__/\___/\__| \___\___/_|_|_| .__/\_,_|\__\___|_| |___/\___|\__|\_,_| .__/ + |_| |_| + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + > Netplan Setup + + About + Exit -If multiple files define the same configuration, the last-read file will override the earlier -definitions. + ``` -Once all files have been processed the result is amalgamated to create the system's Netplan -confguration. + Select `Netplan Setup` and press the `ENTER` key. -::: + ``` + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + Bridge Setup + Ethernet Setup + > Wifi Setup + + Pre-set Configurations + + Read Configuration YAML + Write Configuration YAML + Apply Configuration Changes + View Netplan Configurations + + ``` + + Use the arrow keys to select `Wifi Setup` and press `ENTER`. + + If you have multiple wifi interfaces, use the arrow keys to select the one you wish to configure. If + you only have one interface, it will be seleced automatically. + + ``` + __ ___ ___ _ ___ _ + \ \ / (_) __(_) / __| ___| |_ _ _ _ __ + \ \/\/ /| | _|| | \__ \/ -_) _| || | '_ \ + \_/\_/ |_|_| |_| |___/\___|\__|\_,_| .__/ + |_| + Interface Menu + Press Q, Esc, or CTRL+C to go back. + -------------------------------------------- + > Wi-Fi 'wlp59s0' Setup + + ``` + + Press `ENTER` once you have selected the interface to configure. + + ``` + __ ___ ___ _ ___ _ + \ \ / (_) __(_) / __| ___| |_ _ _ _ __ + \ \/\/ /| | _|| | \__ \/ -_) _| || | '_ \ + \_/\_/ |_|_| |_| |___/\___|\__|\_,_| .__/ + |_| + Press Q, Esc, or CTRL+C to go back. + -------------------------------------------- + > SSID: ssid + Password: password + + Save Settings + Reset Settings + + ``` + + Select `SSID` and press `ENTER`. You will be prompted to enter the SSID of your wireless network. + + ``` + Wi-Fi Network SSID + ------------------ + SSID (ssid): + + ``` + + Then select `Password` and press `ENTER` + + ``` + __ ___ ___ _ ___ _ + \ \ / (_) __(_) / __| ___| |_ _ _ _ __ + \ \/\/ /| | _|| | \__ \/ -_) _| || | '_ \ + \_/\_/ |_|_| |_| |___/\___|\__|\_,_| .__/ + |_| + Press Q, Esc, or CTRL+C to go back. + -------------------------------------------- + > SSID: ssid + Password: password + + Save Settings + Reset Settings + + ``` + + Type in the password for your wireless network and press `ENTER`. The password is case-sensitive. Note that + only `wpa` family encryption is supported using this tool. If your network requires certificates you + must manually configure Netplan. + + ``` + Wi-Fi Network Password + ---------------------- + Password (password): + + ``` + + Type the SSID of your network and press `ENTER`. Note that the SSID is case-sensitive. + + Finally, select `Save Settings` and press the `ENTER` key. + + ``` + __ ___ ___ _ ___ _ + \ \ / (_) __(_) / __| ___| |_ _ _ _ __ + \ \/\/ /| | _|| | \__ \/ -_) _| || | '_ \ + \_/\_/ |_|_| |_| |___/\___|\__|\_,_| .__/ + |_| + Press Q, Esc, or CTRL+C to go back. + -------------------------------------------- + SSID: ssid + Password: password + + > Save Settings + Reset Settings + ``` + + Once you have configured the wireless interfaces, press `Esc` until you return to + the main menu. Select `Write Configuration YAML` and press `ENTER` + + ``` + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + Bridge Setup + Ethernet Setup + Wifi Setup + + Pre-set Configurations + + Read Configuration YAML + > Write Configuration YAML + Apply Configuration Changes + View Netplan Configurations + + ``` + + Enter the path `/etc/netplan/60-wifi.yaml` and press `ENTER`. + + ``` + After saving, run `Apply` to update Netplan. + -------------------------------------------- + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Save YAML: + Enter path to Netplan Configuration YAML + > + + ``` + + Finally, select `Apply Configuration changes` and press `ENTER`. + + ``` + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Apply Netplan Configuration: + - changes will not take effect until you + apply the configuration. + - applying changes may take a 15-30 seconds + depending on the system. + - depending on the new changes, + you may be disconnected from the system. + + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + > Apply Changes + Cancel + + ``` + + Select `Apply Changes` and press `ENTER`. If you are logged into the robot via SSH you may lose your + connection when applying the changes. If this happens, simply open a new terminal and log in again. + + + First, determine the name of your wireless interface by running `iwconfig` you should see + an entry similar to this: + + ``` + wlp59s0 IEEE 802.11 ESSID:off/any + Mode:Managed Access Point: Not-Associated Tx-Power=off + Retry short limit:7 RTS thr:off Fragment thr:off + Power Management:on + ``` + + The interface name is in the left column, starting with `w`. + + Once you have identified your interface, edit or create a file + called `/etc/netplan/60-wifi.yaml` containing the following: + + ```yaml + network: + wifis: + MY_WIFI_INTERFACE: + optional: true + access-points: + MY_WIFI_SSID: + password: MY_WIFI_PASSWORD + dhcp4: true + ``` + + with the following substitutions: + 1. Replace `MY_WIFI_INTERFACE` with the name of the interface you identified in the first step, + e.g. `wlp59s0` + 2. Replace `MY_WIFI_SSID` with the SSID of your network. + 3. Replace `MY_WIFI_PASSWORD` with your network's password. + + For example: + + ```yaml + network: + wifis: + wlp59s0: + optional: true + access-points: + BabCom: + password: peekaboo + dhcp4: true + ``` + + This configuration will connect your robot via DHCP to your WPA2/3 wireless network. If you + need to use a static IP address, modify the file to contain the following: + + ```yaml + network: + wifis: + MY_WIFI_INTERFACE: + optional: true + access-points: + MY_WIFI_SSID: + password: MY_WIFI_PASSWORD + dhcp4: false + dhcp4-overrides: + send-hostname: true + addresses: + - MY_STATIC_IP/MY_SUBNET + nameservers: + addresses: + - MY_NAMESERVER + ``` + + with the same substitutions noted earlier, plus + 1. Replace `MY_STATIC_IP` with the desired static IP address. + 2. Replace `MY_SUBNET` with the length of your network's subnet mask (typically `24` or `16`) + 3. Replace `MY_NAMESERVER` with the IP address of your DNS server You may add multiple DNS servers + with each one on its own line. + + For example: + + ```yaml + network: + wifis: + wlp59s0: + optional: true + access-points: + BabCom: + password: peekaboo + dhcp4: false + dhcp4-overrides: + send-hostname: true + addresses: + - 10.25.0.134/16 + nameservers: + addresses: + - 10.25.0.10 + - 8.8.8.8 + - 8.8.4.4 + ``` + + Once you have edited the netplan configuration file, run the following two commands: + 1. `sudo netplan --debug generate` -- this will verify that the netplan configuration files can + be read properly. Correct any errors before proceeding. + 2. `sudo netplan try` -- this will try running the new configuration, but will automatically + roll back if it doesn't work correctly. + 3. `sudo netplan apply` -- this will apply the new configuration to your network interfaces. + + :::note + + By convention, all Netplan configuration files should be prefixed with two numbers indicating the + order in which the file should be read. Files are read in alphanumeric order, with `00-` prefixes + first and `99-` prefixes last. + + If multiple files define the same configuration, the last-read file will override the earlier + definitions. + + Once all files have been processed the result is amalgamated to create the system's Netplan + confguration. + + ::: + + ## Standard Clearpath Bridge - + + + + Use the `sudo clearpath-computer-setup` command to connect your robot to an existing wireless network. + + ``` + ___ _ _ ___ _ ___ _ + | _ \___| |__ ___| |_ / __|___ _ __ _ __ _ _| |_ ___ _ _ / __| ___| |_ _ _ _ __ + | / _ \ '_ \/ _ \ _| | (__/ _ \ ' \| '_ \ || | _/ -_) '_| \__ \/ -_) _| || | '_ \ + |_|_\___/_.__/\___/\__| \___\___/_|_|_| .__/\_,_|\__\___|_| |___/\___|\__|\_,_| .__/ + |_| |_| + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + > Netplan Setup + + About + Exit + + ``` + + Select `Netplan Setup` and press the `ENTER` key. + + ``` + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + > Bridge Setup + Ethernet Setup + Wifi Setup + + Pre-set Configurations + + Read Configuration YAML + Write Configuration YAML + Apply Configuration Changes + View Netplan Configurations + + ``` + + If you do not have a bridge defined, use the arrow keys to select `Bridge Setup` and press `ENTER`. + + ``` + ___ _ _ ___ _ + | _ )_ _(_)__| |__ _ ___ / __| ___| |_ _ _ _ __ + | _ \ '_| / _` / _` / -_) \__ \/ -_) _| || | '_ \ + |___/_| |_\__,_\__, \___| |___/\___|\__|\_,_| .__/ + |___/ |_| + Interface Menu + Press Q, Esc, or CTRL+C to go back. + --------------------------------------------------- + > Add Bridge + Remove Bridge + + ``` + + Use the arrow keys to select `Add Bridge` and press `ENTER`. + + Enter the name of the bridge you want to create. By default the first bridge should be called + `br0`. Press `ENTER` to continue. + + ``` + Bridge interface name must start with 'br' + ------------------------------------------ + Enter name of bridge to add. + > + + ``` + + Select the bridge to edit (`br0` by default) and press `ENTER`. + + ``` + ___ _ _ ___ _ + | _ )_ _(_)__| |__ _ ___ / __| ___| |_ _ _ _ __ + | _ \ '_| / _` / _` / -_) \__ \/ -_) _| || | '_ \ + |___/_| |_\__,_\__, \___| |___/\___|\__|\_,_| .__/ + |___/ |_| + Interface Menu + Press Q, Esc, or CTRL+C to go back. + --------------------------------------------------- + > Bridge 'br0' Setup + + Add Bridge + Remove Bridge + + ``` + + Enable or disable DHCP for IPv4 and IPv6 as desired. + + ``` + ___ _ _ ___ _ + | _ )_ _(_)__| |__ _ ___ / __| ___| |_ _ _ _ __ + | _ \ '_| / _` / _` / -_) \__ \/ -_) _| || | '_ \ + |___/_| |_\__,_\__, \___| |___/\___|\__|\_,_| .__/ + |___/ |_| + Bridge 'br0' Configuration + Press Q, Esc, or CTRL+C to go back. + --------------------------------------------------- + > dhcp4 : [yes] + dhcp6 : [no] + bridged : [[]] + addresses : [[]] + + ``` + + To select what interfaces to bridge together, select `bridged` and press `ENTER`. Use the arrow + keys to select each interface you want to add to the bridge and press the spacebar to check/uncheck it. + + ``` + br0 bridged + Press Q, Esc, or CTRL+C to reset. + Press Enter to accept changes and exit. + --------------------------------------- + > [ ] enp3s0 + [ ] enp4s0 + [ ] wlp59s0 + + Press , for multi-selection and to accept + + ``` + + Press `ENTER` once you have selected all of the desired interfaces to bridge. + + To add static IP addresses to the bridge, select `addresses` and press `ENTER`. + + ``` + ___ _ _ ___ _ + | _ )_ _(_)__| |__ _ ___ / __| ___| |_ _ _ _ __ + | _ \ '_| / _` / _` / -_) \__ \/ -_) _| || | '_ \ + |___/_| |_\__,_\__, \___| |___/\___|\__|\_,_| .__/ + |___/ |_| + Bridge 'br0' Configuration + Press Q, Esc, or CTRL+C to go back. + --------------------------------------------------- + dhcp4 : [yes] + dhcp6 : [no] + bridged : [['enp3s0', 'enp4s0']] + > addresses : [[]] + + ``` + + Select `Add IP Address` and enter `192.168.131.1/24` to create the robot's internal network. + + ``` + Select option to edit, add, or remove bridge IP addresses: + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------- + > Add IP Address + Remove IP Address + + ``` + + Once you have added all desired static IP addresses to the bridge, press `Esc` until you return to + the main menu. Select `Write Configuration YAML` and press `ENTER` + + ``` + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + Bridge Setup + Ethernet Setup + Wifi Setup + + Pre-set Configurations + + Read Configuration YAML + > Write Configuration YAML + Apply Configuration Changes + View Netplan Configurations + + ``` + + Enter the path `/etc/netplan/50-clearpath-bridge.yaml` and press `ENTER`. + + ``` + After saving, run `Apply` to update Netplan. + -------------------------------------------- + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Save YAML: + Enter path to Netplan Configuration YAML + > + + ``` + + Finally, select `Apply Configuration changes` and press `ENTER`. + + ``` + _ _ _ _ ___ __ _ _ _ + | \| |___| |_ _ __| |__ _ _ _ / __|___ _ _ / _(_)__ _ _ _ _ _ __ _| |_(_)___ _ _ + | .` / -_) _| '_ \ / _` | ' \ | (__/ _ \ ' \| _| / _` | || | '_/ _` | _| / _ \ ' \ + |_|\_\___|\__| .__/_\__,_|_||_| \___\___/_||_|_| |_\__, |\_,_|_| \__,_|\__|_\___/_||_| + |_| |___/ + Apply Netplan Configuration: + - changes will not take effect until you + apply the configuration. + - applying changes may take a 15-30 seconds + depending on the system. + - depending on the new changes, + you may be disconnected from the system. + + Press Q, Esc, or CTRL+C to go back. + ---------------------------------------------------------------------------------------- + > Apply Changes + Cancel + + ``` + + Select `Apply Changes` and press `ENTER`. If you are logged into the robot via SSH you may lose your + connection when applying the changes. If this happens, simply open a new terminal and log in again. + + + + + + ## Determining the robot's IP address {#determine-ip-address} diff --git a/docs_versioned_docs/version-ros2jazzy/ros/troubleshooting.mdx b/docs_versioned_docs/version-ros2jazzy/ros/troubleshooting.mdx index 34a6b5c32..de8262f32 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/troubleshooting.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/troubleshooting.mdx @@ -21,13 +21,14 @@ computer; the firmware is ROS-distribution-specific, and must have a version com One significant change between ROS 1 and ROS 2 is that Clearpath robots using ROS 2 Humble or Jazzy have their MCUs boot to a reset state. To establish communication between the robot's primary computer you must press a button on the robot: + - on Ridgeback or Husky A300 press the e-stop reset button located on the rear of the robot - on Jackal or Dingo, press the MCU disconnect () button ## Robot's COMM light is off after upgrading to ROS 2 Most Clearpath robots have an MCU that must also be updated. Ensure you have installed the correct -MCU firmware for your ROS distribution. Refer to your robot's [user manual](/docs_robots/robots) +MCU firmware for your ROS distribution. Refer to your robot's [user manual](/docs_robots/robots) for instructions on updating the MCU firmware. USB or serial-based MCUs require [`udev` rules](https://github.com/clearpathrobotics/clearpath_robot/blob/jazzy/clearpath_robot/debian/udev) @@ -36,6 +37,7 @@ to be installed on the robot. If you have installed the ROS 2 packages as `.deb` packages (using the `apt` or `apt-get` command) these udev rules will be installed automatically. Verify that `/usr/lib/udev/rules.d/60-ros-jazzy-clearpath-robot.rules` exists in your system. If it does not, try reinstalling the `clearpath_robot` ROS package: + ```bash sudo apt-get update sudo apt-get install --reinstall ros-jazzy-clearpath-robot @@ -43,6 +45,7 @@ sudo apt-get install --reinstall ros-jazzy-clearpath-robot If you have installed the packages from source (i.e. they are built in a `colcon` workspace), make sure you have installed the udev rules by running these commands: + ``` sudo cp /path/to/colcon_ws/src/clearpath_robot/clearpath_robot/debian/udev /etc/udev/rules.d/60-clearpath-robot.rules sudo udevadm control --reload-rules @@ -54,17 +57,22 @@ sudo udevadm trigger The command to install the firmware will exit normally if the firmware is successfully installed. If you do not see any error messages then the program finished normally. To double-check, _immediately after_ running the firmware installation command you can run + ```bash echo $? ``` + to print the exit code of the previous command. If this prints `0` then the previous command finished normally. To verify that the version of the MCU firmware running on your robot, run + ```bash ros2 topic echo /a300_00000/platform/mcu/status --once ``` + (replacing `a300_00000` with your robot's root namespace). The result will look something like this: + ```yaml header: stamp: @@ -81,12 +89,16 @@ connection_uptime: nanosec: 338000000 --- ``` + The `firmware_version` field shows the MCU firmware version currently running. Ensure that this matches the version you just installed: + ``` ros2 pkg xml clearpath_firmware ``` + This command will print the `clearpath_firmware` package's meta-data: + ```xml clearpath_firmware @@ -114,6 +126,7 @@ This command will print the `clearpath_firmware` package's meta-data: ``` + The `version` tag near the top should match the `firmware_version` field of the MCU status message. In this case, both are `2.4.1`, indicating the latest firmware is installed. @@ -122,6 +135,7 @@ In this case, both are `2.4.1`, indicating the latest firmware is installed. An invalid `robot.yaml` file may result in one or more of the `clearpath-*` systemd jobs to crash or for the simulation to fail to start. Check the ROS output for errors errors with any of the following prefixes: + - `generate_description` - `clearpath_config` - `clearpath_config_live` @@ -194,3 +208,21 @@ names in common. See [ROS 2 communication](networking/ros2_networking/ros2_communication) for more information about configuring domain IDs. + +## Mixing ROS 2 Humble and Jazzy + +Communication between Humble and Jazzy devices is not supported due to differences in middleware versions. Attempting to discover or communicate with a Humble robot using a Jazzy computer, or vice versa, will cause nodes and services to fail. In this failure mode, you may see one or more of the following errors: + +``` +eprosima::fastcdr::exception::NotEnoughMemoryException +``` + +``` +'Bad alloc' exception deserializing message of type rmw_dds_common::msg::dds_::ParticipantEntitiesInfo_., at ./src/type_support_common.cpp:123 +``` + +``` +Fast CDR exception deserializing message of type rmw_dds_common::msg::dds_::ParticipantEntitiesInfo_., at ./src/type_support_common.cpp:118 +``` + +It is recommended that all ROS 2 devices on a network use the same ROS 2 distribution and middleware. diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/gazebo.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/gazebo.mdx index d0e666d7e..1f412c2c8 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/gazebo.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/gazebo.mdx @@ -1,7 +1,7 @@ --- title: Manipulation in Gazebo Harmonic sidebar_label: Manipulation in Simulation -sidebar_position: 3 +sidebar_position: 1 toc_min_heading_level: 2 toc_max_heading_level: 4 --- diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/remote.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/remote.mdx new file mode 100644 index 000000000..67120a8d1 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/manipulation/remote.mdx @@ -0,0 +1,65 @@ +--- +title: Manipulation across Multiple Machines +sidebar_label: Multiple Machines +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +MoveIt! can require significant resources to generate complex manipulator trajectories. Ideally, a single powerful computer would handle the robot's nodes, sensor drivers, manipulator controllers, and MoveIt!. However, if a secondary computer is available onboard the robot and on the same local network, it could be used to handle some of the load of the primary platform computer. + +# MoveIt on Secondary Computer +The manipulators' controllers can be launched on the primary platform computer, while the motion planning can be launched independently on the secondary computer. + +The secondary computer does not need to be connected over ethernet to the primary platform computer, but doing so simplifies the networking setup which will not be covered in this tutorial. For more information on setting up networks with the ROS 2 middleware see the [networking section](../../networking/overview.mdx). + +## Setup +The secondary computer must have the same environment as the primary platform computer. Ensure that they both have the same version of packages, and if workspaces are required to build packages from source, they should be mirrored and built on the two computers. Then a `clearpath` setup directory must be created with the same `robot.yaml` as the one on the robot, see [offboard computer setup instructions](../../installation/offboard_pc.mdx) for more details. For the remainder of this tutorial, the `clearpath` setup directory will be assumed to be in the `home` directory. + +## Launching MoveIt! +Source all required workspaces on the secondary computer and generate all description, configuration, and launch files. +```bash +source /opt/ros/jazzy/setup.bash +``` + +### Generate Environment Setup +Generate the environment setup bash file. This file will contain any environment variables required to setup the networking between the multiple computer setup. +```bash +ros2 run clearpath_generator_common generate_bash -s $HOME/clearpath/ +``` + +This script will generate the `$HOME/clearpath/setup.bash` with the environment required to communicate with the primary platform computer. + +### Generate Description Files +Then, generate the description files: +```bash +ros2 run clearpath_generator_common generate_description -s $HOME/clearpath/ +ros2 run clearpath_generator_common generate_semantic_description -s $HOME/clearpath/ +``` +These scripts will generate the `robot.urdf.xacro`, `robot.srdf.xacro`, and `robot.srdf` files in the `$HOME/clearpath` directory which contain necessary robot description information to launch MoveIt!. + +### Generate Launch and Configuration Files +Then, generate the MoveIt! launch file and parameter file: +```bash +ros2 run clearpath_generator_robot generate_launch -s $HOME/clearpath/ +ros2 run clearpath_generator_robot generate_param -s $HOME/clearpath/ +``` + +These scripts will generate the `manipulators/launch/manipulators.launch.py` and `manipulators/config/moveit.config` files. + +### Launch +Once these files are all generated, launch MoveIt! by passing it the path to the directory: +``` +ros2 launch clearpath_manipulators moveit.launch.py setup_path:=$HOME/clearpath/ +``` + +## Launching RViz +Once MoveIt! is running, open RViz with the MoveIt MotionPlanning plugin, with the appropriate namespace, and interactive markers. To do so, create a new terminal, source the workspace, and call the `view_moveit` launch file: +``` +ros2 launch clearpath_viz view_moveit.launch.py namespace:='' +``` + +Make sure to pass the same namespace as the robot's. For example, a robot with namespace `a300_0001` will have topics such as `/a300_0001/platform/mcu/status` and `/a300_0001/manipulators/arm_0_joint_trajectory_controller/controller_state`. To launch its viewing command: +``` +ros2 launch clearpath_viz view_moveit.launch.py namespace:='a300_0001' +``` diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx index 7f54abef6..db173c047 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx @@ -29,12 +29,11 @@ to `false`. ::: -**1.** [Start the simulation and Nav2](nav2.mdx#launching-the-simulation-and-nav2) -by following steps 1-3 of the Nav2 startup - -**2.** Open a terminal and run +To start localization using [AMCL](https://docs.nav2.org/configuration/packages/configuring-amcl.html) +[follow the steps](nav2.mdx#launching-the-simulation-and-nav2) described in the Nav2 +startup. When you get to step 4, run ```bash -ros2 launch clearpath_nav2_demos localization.launch.py use_sim_time:=true +ros2 launch clearpath_nav2_demos localiztion.launch.py use_sim_time:=true ``` The default map used by `localization.launch.py` is a @@ -43,8 +42,3 @@ If you are using a custom map, pass it in with the `map` launch argument: ```bash ros2 launch clearpath_nav2_demos localization.launch.py use_sim_time:=true map:=/path/to/my/map.yaml ``` - -**3.** [Start Rviz](nav2.mdx#launching-the-simulation-and-nav2) and set the robot's initial pose -estimate by following steps 5-6 of the Nav2 startup - -**4.** Give the robot a navigation goal using the [Nav2 Goal](nav2.mdx#nav2-goal) tool. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx index 666bd9312..68eb6f2a7 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx @@ -30,23 +30,23 @@ ros2 launch clearpath_gz simulation.launch.py If the simulation does not start automatically, press the large orange "play" button in the bottom left corner. -**3.** Open a second terminal and launch nav2: - +**3.** Open a second terminal and start Rviz. If you are using a physical robot or running the simulation +on an external server, this step must be should on your workstation, not on the robot or simulation server itself. ``` -ros2 launch clearpath_nav2_demos nav2.launch.py use_sim_time:=true +ros2 launch clearpath_viz view_navigation.launch.py namespace:=a300_0000 use_sim_time:=true ``` **4.** Open a third terminal and start either [SLAM](slam.mdx) or [Localization](localization.mdx), depdending on whether or not you want to create a new map or use a pre-existing map. -**5.** Open a fourth terminal and start Rviz. If you are using a physical robot or running the simulation -on an external server, this step must be should on your workstation, not on the robot or simulation server itself. +**5.** Set the initial pose of the robot using the [**2D Pose Estimate**](#2d-pose-estimate) tool in RViz. + +**6.** Open fourth second terminal and launch nav2: + ``` -ros2 launch clearpath_viz view_navigation.launch.py namespace:=a300_0000 +ros2 launch clearpath_nav2_demos nav2.launch.py use_sim_time:=true ``` -**6.** Set the initial pose of the robot using the [**2D Pose Estimate**](#2d-pose-estimate) tool in RViz. - **7.** Give the robot a navigation goal using the [**Nav2 Goal**](#nav2-goal) tool in RViz. ## Nav2 Tools in Rviz diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx index 3d890b9af..fbcd3e7e5 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx @@ -32,18 +32,15 @@ to `false`. ::: -**1.** [Start the simulation and Nav2](nav2.mdx#launching-the-simulation-and-nav2) -by following steps 1-3 of the Nav2 startup - -**2.** Open a terminal and run +To start SLAM, [follow the steps](nav2.mdx#launching-the-simulation-and-nav2) described in the Nav2 +startup. When you get to step 4, run ```bash ros2 launch clearpath_nav2_demos slam.launch.py use_sim_time:=true ``` -**3.** [Start Rviz](nav2.mdx#launching-the-simulation-and-nav2) and set the robot's initial pose -estimate by following steps 5-6 of the Nav2 startup +### Building the map -**4.** Drive the robot around the world. Ensure you have mapped the region you want the robot +Drive the robot around the world. Ensure you have mapped the region you want the robot to navigate through autonomously.
@@ -56,10 +53,10 @@ to navigate through autonomously.
-**5.** Save the map by opening a new terminal and running +### Saving the map + +To save the map, open a new terminal and run ```bash ros2 run nav2_map_server map_saver_cli -f "map_name" --ros-args -p map_subscribe_transient_local:=true -r __ns:=/a300_0000 ``` - -**6.** Give the robot a navigation goal using the [Nav2 Goal](nav2.mdx#nav2-goal) tool. \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 4c48edf21..686e00c32 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1,265 +1,265 @@ -// @ts-check -// Note: type annotations allow type checking and IDEs autocompletion - -import {themes as prismThemes} from 'prism-react-renderer'; - -const lightCodeTheme = prismThemes.github; -const darkCodeTheme = prismThemes.dracula; -import remarkMath from 'remark-math'; -import rehypeKatex from 'rehype-katex'; - -/** @type {import('@docusaurus/types').Config} */ -const config = { - title: "Clearpath Robotics Documentation", - url: "https://docs.clearpathrobotics.com", - baseUrl: "/", - onBrokenLinks: "throw", - onBrokenMarkdownLinks: "throw", - onBrokenAnchors: "throw", - favicon: "img/website_images/favicon.ico", - - i18n: { - defaultLocale: "en", - locales: ["en"], - }, - - presets: [ - [ - "classic", - { - docs: false, - theme: { - customCss: require.resolve("./src/css/custom.css"), - }, - sitemap: { - ignorePatterns: ['**/components/**'], - }, - }, - ], - ], - - plugins: [ - [ - "@docusaurus/plugin-content-docs", - { - id: "docs", - path: "docs", - routeBasePath: "docs", - sidebarPath: require.resolve("./sidebars-docs.js"), - remarkPlugins: [remarkMath], - rehypePlugins: [rehypeKatex], - showLastUpdateTime: true, - versions: { - ros2jazzy: { - label: 'ROS 2 Jazzy', - }, - ros2humble: { - label: 'ROS 2 Humble', - }, - ros1noetic: { - label: 'ROS 1 Noetic', - } - }, - includeCurrentVersion: false, - admonitions: { - keywords: ['safety-danger', 'safety-warning', 'safety-caution'], - extendDefaults: true, - }, - }, - ], - [ - "@docusaurus/plugin-content-docs", - { - id: "docs_robots", - path: "docs_robots", - routeBasePath: "docs_robots", - sidebarPath: require.resolve("./sidebars.js"), - remarkPlugins: [remarkMath], - rehypePlugins: [rehypeKatex], - showLastUpdateTime: true, - admonitions: { - keywords: ['safety-danger', 'safety-warning', 'safety-caution'], - extendDefaults: true, - }, - }, - ], - [ - "@docusaurus/plugin-content-docs", - { - id: "indoornav_user_manual", - path: "docs_indoornav_user_manual", - routeBasePath: "docs_indoornav_user_manual", - sidebarPath: require.resolve("./sidebars.js"), - remarkPlugins: [remarkMath], - rehypePlugins: [rehypeKatex], - showLastUpdateTime: true, - }, - ], - [ - "@docusaurus/plugin-content-docs", - { - id: "outdoornav_user_manual", - path: "docs_outdoornav_user_manual", - routeBasePath: "docs_outdoornav_user_manual", - sidebarPath: require.resolve("./sidebars.js"), - remarkPlugins: [remarkMath], - rehypePlugins: [rehypeKatex], - showLastUpdateTime: true, - includeCurrentVersion: false, - }, - ], - [ - "@docusaurus/plugin-content-docs", - { - id: "components", - path: "components", - remarkPlugins: [remarkMath], - rehypePlugins: [rehypeKatex], - admonitions: { - keywords: ['safety-danger', 'safety-warning', 'safety-caution'], - extendDefaults: true, - }, - }, - ], - [ - "@docusaurus/theme-mermaid", - {} - ], - ], - - themeConfig: - /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ - ({ - navbar: { - title: " ", - logo: { - alt: "Clearpath Robotics", - src: "img/website_images/logo_rockwell_pipe_clearpath_colour.png", - srcDark: "img/website_images/logo_rockwell_pipe_clearpath_white.png", - }, - items: [ - { - type: "doc", - docId: "robots", - label: "Robots", - position: "left", - docsPluginId: "docs_robots", - }, - { - type: "docsVersion", - to: "/docs/ros/", - label: "Software", - position: "left", - docsPluginId: "docs", - }, - { - type: "docsVersion", - label: "OutdoorNav", - position: "left", - docsPluginId: "outdoornav_user_manual", - }, - { - type: "doc", - docId: "index", - label: "IndoorNav", - position: "left", - docsPluginId: "indoornav_user_manual", - }, - { - type: 'docsVersionDropdown', - position: 'right', - dropdownActiveClassDisabled: true, - docsPluginId: "docs" - }, - { - type: 'docsVersionDropdown', - position: 'right', - dropdownActiveClassDisabled: true, - docsPluginId: "outdoornav_user_manual", - }, - { - to: "about", - label: "About", - position: "right", - }, - { - to: "https://github.com/clearpathrobotics/cpr-documentation", - label: "GitHub", - position: "right", - }, - { - to: "https://store.clearpathrobotics.com/", - label: "Store", - position: "right", - }, - { - to: "https://clearpathrobotics.com/", - label: "Home", - position: "right", - }, - ], - }, - docs: { - sidebar: { - autoCollapseCategories: true, - hideable: true, - }, - }, - footer: { - copyright: `Clearpath Robotics, by Rockwell Automation. All rights reserved. © Clearpath Robotics, Inc., a Rockwell Automation Company. All rights reserved.`, - }, - prism: { - theme: lightCodeTheme, - darkTheme: darkCodeTheme, - }, - mermaid: { - theme: {light: "default", dark: 'dark'}, - }, - markdown: { - mermaid: true, - }, - algolia: { - // The application ID provided by Algolia - appId: 'R6SHOZP2CR', - - // Public API key: it is safe to commit it - apiKey: '656811d089022bbc909acf46732dd073', - - indexName: 'clearpathrobotics', - - // Optional: see doc section below - contextualSearch: true, - - // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them. - //externalUrlRegex: 'external\\.com|domain\\.com', - - // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs - //replaceSearchResultPathname: { - // from: '/docs/', // or as RegExp: /\/docs\// - // to: '/', - //}, - - // Optional: Algolia search parameters - searchParameters: {}, - - // Optional: path for search page that enabled by default (`false` to disable it) - searchPagePath: 'search', - - // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default) - insights: false, - - //... other Algolia params - }, - }), - - stylesheets: [ - { - href: "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css", - type: "text/css", - integrity: "sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM", - crossorigin: "anonymous", - }, - ], -}; - -module.exports = config; +// @ts-check +// Note: type annotations allow type checking and IDEs autocompletion + +import {themes as prismThemes} from 'prism-react-renderer'; + +const lightCodeTheme = prismThemes.github; +const darkCodeTheme = prismThemes.dracula; +import remarkMath from 'remark-math'; +import rehypeKatex from 'rehype-katex'; + +/** @type {import('@docusaurus/types').Config} */ +const config = { + title: "Clearpath Robotics Documentation", + url: "https://docs.clearpathrobotics.com", + baseUrl: "/", + onBrokenLinks: "throw", + onBrokenMarkdownLinks: "throw", + onBrokenAnchors: "throw", + favicon: "img/website_images/favicon.ico", + + i18n: { + defaultLocale: "en", + locales: ["en"], + }, + + presets: [ + [ + "classic", + { + docs: false, + theme: { + customCss: require.resolve("./src/css/custom.css"), + }, + sitemap: { + ignorePatterns: ['**/components/**'], + }, + }, + ], + ], + + plugins: [ + [ + "@docusaurus/plugin-content-docs", + { + id: "docs", + path: "docs", + routeBasePath: "docs", + sidebarPath: require.resolve("./sidebars-docs.js"), + remarkPlugins: [remarkMath], + rehypePlugins: [rehypeKatex], + showLastUpdateTime: true, + versions: { + ros2jazzy: { + label: 'ROS 2 Jazzy', + }, + ros2humble: { + label: 'ROS 2 Humble', + }, + ros1noetic: { + label: 'ROS 1 Noetic', + } + }, + includeCurrentVersion: false, + admonitions: { + keywords: ['safety-danger', 'safety-warning', 'safety-caution'], + extendDefaults: true, + }, + }, + ], + [ + "@docusaurus/plugin-content-docs", + { + id: "docs_robots", + path: "docs_robots", + routeBasePath: "docs_robots", + sidebarPath: require.resolve("./sidebars.js"), + remarkPlugins: [remarkMath], + rehypePlugins: [rehypeKatex], + showLastUpdateTime: true, + admonitions: { + keywords: ['safety-danger', 'safety-warning', 'safety-caution'], + extendDefaults: true, + }, + }, + ], + [ + "@docusaurus/plugin-content-docs", + { + id: "indoornav_user_manual", + path: "docs_indoornav_user_manual", + routeBasePath: "docs_indoornav_user_manual", + sidebarPath: require.resolve("./sidebars.js"), + remarkPlugins: [remarkMath], + rehypePlugins: [rehypeKatex], + showLastUpdateTime: true, + }, + ], + [ + "@docusaurus/plugin-content-docs", + { + id: "outdoornav_user_manual", + path: "docs_outdoornav_user_manual", + routeBasePath: "docs_outdoornav_user_manual", + sidebarPath: require.resolve("./sidebars.js"), + remarkPlugins: [remarkMath], + rehypePlugins: [rehypeKatex], + showLastUpdateTime: true, + includeCurrentVersion: false, + }, + ], + [ + "@docusaurus/plugin-content-docs", + { + id: "components", + path: "components", + remarkPlugins: [remarkMath], + rehypePlugins: [rehypeKatex], + admonitions: { + keywords: ['safety-danger', 'safety-warning', 'safety-caution'], + extendDefaults: true, + }, + }, + ], + [ + "@docusaurus/theme-mermaid", + {} + ], + ], + + themeConfig: + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ({ + navbar: { + title: " ", + logo: { + alt: "Clearpath Robotics", + src: "img/website_images/logo_rockwell_pipe_clearpath_colour.png", + srcDark: "img/website_images/logo_rockwell_pipe_clearpath_white.png", + }, + items: [ + { + type: "doc", + docId: "robots", + label: "Robots", + position: "left", + docsPluginId: "docs_robots", + }, + { + type: "docsVersion", + to: "/docs/ros/", + label: "Software", + position: "left", + docsPluginId: "docs", + }, + { + type: "docsVersion", + label: "OutdoorNav", + position: "left", + docsPluginId: "outdoornav_user_manual", + }, + { + type: "doc", + docId: "index", + label: "IndoorNav", + position: "left", + docsPluginId: "indoornav_user_manual", + }, + { + type: 'docsVersionDropdown', + position: 'right', + dropdownActiveClassDisabled: true, + docsPluginId: "docs" + }, + { + type: 'docsVersionDropdown', + position: 'right', + dropdownActiveClassDisabled: true, + docsPluginId: "outdoornav_user_manual", + }, + { + to: "about", + label: "About", + position: "right", + }, + { + to: "https://github.com/clearpathrobotics/cpr-documentation", + label: "GitHub", + position: "right", + }, + { + to: "https://store.clearpathrobotics.com/", + label: "Store", + position: "right", + }, + { + to: "https://clearpathrobotics.com/", + label: "Home", + position: "right", + }, + ], + }, + docs: { + sidebar: { + autoCollapseCategories: true, + hideable: true, + }, + }, + footer: { + copyright: `Clearpath Robotics, by Rockwell Automation. All rights reserved. © Clearpath Robotics, Inc., a Rockwell Automation Company. All rights reserved.`, + }, + prism: { + theme: lightCodeTheme, + darkTheme: darkCodeTheme, + }, + mermaid: { + theme: {light: "default", dark: 'dark'}, + }, + markdown: { + mermaid: true, + }, + algolia: { + // The application ID provided by Algolia + appId: 'R6SHOZP2CR', + + // Public API key: it is safe to commit it + apiKey: '656811d089022bbc909acf46732dd073', + + indexName: 'clearpathrobotics', + + // Optional: see doc section below + contextualSearch: true, + + // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them. + //externalUrlRegex: 'external\\.com|domain\\.com', + + // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs + //replaceSearchResultPathname: { + // from: '/docs/', // or as RegExp: /\/docs\// + // to: '/', + //}, + + // Optional: Algolia search parameters + searchParameters: {}, + + // Optional: path for search page that enabled by default (`false` to disable it) + searchPagePath: 'search', + + // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default) + insights: false, + + //... other Algolia params + }, + }), + + stylesheets: [ + { + href: "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css", + type: "text/css", + integrity: "sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM", + crossorigin: "anonymous", + }, + ], +}; + +module.exports = config; diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_endpoints/api_endpoints.mdx index c65c4150b..e1169e6e2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_endpoints/api_endpoints.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_endpoints/api_endpoints.mdx @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/api_examples.mdx index 32daf5e7b..a8bdda373 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/api_examples.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/api_examples.mdx @@ -1,20 +1,20 @@ ---- -title: API Examples -sidebar_label: API Examples -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -The OutdoorNav API examples are now available and accesible to everyone. A -[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along -with some example scripts are available to build and use for our application. - -A few examples scripts follow with detailed explanations: - -- [Execute Mission from File](./mission_from_file.mdx) -- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) -- [Status Monitoring](./monitor_status.mdx) - -The documentation for the Python API library can be built following the -instructions in the above linked GitHub repository. +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav API examples are now available and accesible to everyone. A +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +with some example scripts are available to build and use for our application. + +A few examples scripts follow with detailed explanations: + +- [Execute Mission from File](./mission_from_file.mdx) +- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) +- [Status Monitoring](./monitor_status.mdx) + +The documentation for the Python API library can be built following the +instructions in the above linked GitHub repository. diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_from_file.mdx index eff0f7686..0abb4ea90 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_from_file.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_from_file.mdx @@ -1,210 +1,210 @@ ---- -title: Mission from YAML File -sidebar_label: Mission from YAML File -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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" -``` +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.10.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_with_custom_tasks.mdx index 30ec477ea..af8335aa6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_with_custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/mission_with_custom_tasks.mdx @@ -1,233 +1,233 @@ ---- -title: Mission with Custom Tasks -sidebar_label: Mission with Custom Tasks -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -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.mdx) 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. - - +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +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.mdx) 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.10.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/monitor_status.mdx index 077a9fcf5..a6fb416c5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/monitor_status.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_examples/monitor_status.mdx @@ -1,152 +1,152 @@ ---- -title: Monitor Status -sidebar_label: Monitor Status -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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. +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.10.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_overview.mdx index 3b69afd02..503de14dc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/api/api_overview.mdx @@ -1,61 +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions +- [Definitions](api_endpoints/definitions.mdx): 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.10.0/cpr_hardware.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/cpr_hardware.mdx index f60527ff9..2d1efdd01 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/cpr_hardware.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/cpr_hardware.mdx @@ -1,405 +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](getting_started/system_setup.mdx#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. +--- +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](getting_started/system_setup.mdx#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.10.0/customized_tuning/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/_category_.json index 4c27a4d91..d38b7f55c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix C: Tuning & Customization", - "position": 14 +{ + "label": "Appendix C: Tuning & Customization", + "position": 14 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/sensor_customization.mdx index 9d9f115aa..f2cce53a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/sensor_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/sensor_customization.mdx @@ -1,9 +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. +--- +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.10.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/_category_.json index d62e291a4..4b3e7b596 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index 516393373..0125d8ddc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -1,9 +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. +--- +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.10.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 4b90f6008..6b105ecb3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/footprint_tuning.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -1,9 +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. +--- +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.10.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_overview.mdx index 851df29b0..77fbabeb9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_overview.mdx @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/_category_.json index fb6592a90..0e2dc60a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/navigation_parameters.mdx index 8c986090b..7cd7b1448 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/navigation_parameters.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -1,167 +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. +--- +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.10.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/user_interface_customization.mdx index c67bca22a..1e7d39c97 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/user_interface_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/customized_tuning/user_interface_customization.mdx @@ -1,9 +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. +--- +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.10.0/faq.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/faq.mdx index 82d0a296b..cbdd33dc4 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/faq.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/faq.mdx @@ -1,194 +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.mdx#mission-execution)) or, - ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). - -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.mdx) 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.mdx). - 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.mdx). - -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.mdx) and contact - [Support](./support.mdx) 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.mdx#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.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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.mdx#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.mdx). - -5. **What to do if my custom task is not working?** - - Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) 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.mdx#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) - +--- +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.mdx#mission-execution)) or, + ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). + +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.mdx) 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.mdx). + 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.mdx). + +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.mdx) and contact + [Support](./support.mdx) 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.mdx#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.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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.mdx#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.mdx). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) 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.mdx#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.10.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/_category_.json index 732c6cb78..3bf04f17d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/features/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav Features", - "position": 8 -} +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/custom_tasks.mdx index 32c3115ee..de2c855a0 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/features/custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/custom_tasks.mdx @@ -1,203 +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 -``` +--- +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.10.0/features/mission_scheduler.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/mission_scheduler.mdx index 95c870612..0afdfcaf3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/features/mission_scheduler.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/mission_scheduler.mdx @@ -1,43 +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 +--- +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.10.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/navigation.mdx index e4c0b8644..a55482503 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/features/navigation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/navigation.mdx @@ -1,38 +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.mdx#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`).| +--- +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.mdx#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.10.0/features/rosbag_recorder.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/rosbag_recorder.mdx index 503d94ae7..f102726e5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/features/rosbag_recorder.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/features/rosbag_recorder.mdx @@ -1,34 +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. +--- +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.10.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/_category_.json index 8b4a486d9..9a9747ef6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/first_time_checklist.mdx index c4d9dece3..d90e0c8e5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/first_time_checklist.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/first_time_checklist.mdx @@ -1,114 +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#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.10.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/system_setup.mdx index e5062958f..79397185d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/system_setup.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/system_setup.mdx @@ -1,236 +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.mdx). - -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.mdx) 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. +--- +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.mdx). + +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.mdx) 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.10.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/terminal_interface.mdx index 43e9dedc1..76de4f412 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/terminal_interface.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/terminal_interface.mdx @@ -1,141 +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 +--- +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.10.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/tf_validation.mdx index 72327dbc3..ab05b15f1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/tf_validation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/getting_started/tf_validation.mdx @@ -1,80 +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
-
-
- -::: +--- +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.10.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/index.mdx @@ -1,18 +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 +--- +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.10.0/integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/_category_.json index e9e0ff1dd..adbe22cba 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix A: UGV Integration Requirements", - "position": 12 +{ + "label": "Appendix A: UGV Integration Requirements", + "position": 12 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/hardware_integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/hardware_integration_requirements/_category_.json index 75ebaf1b4..7950de6b7 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/hardware_integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/hardware_integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Hardware Kit Installation", - "position": 2 -} +{ + "label": "Hardware Kit Installation", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/integration_overview.mdx index 00cf8a071..72d78ae31 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/integration_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/integration_overview.mdx @@ -1,34 +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. | +--- +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.10.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/interface_control_requirements.mdx index a603485bb..d9906ed65 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/interface_control_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/interface_control_requirements.mdx @@ -1,119 +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.mdx#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). +--- +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.mdx#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.10.0/integration_requirements/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/software_integration_instructions.mdx index 41efff44f..454f93c94 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/software_integration_instructions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/integration_requirements/software_integration_instructions.mdx @@ -1,145 +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: -- [Interface Control Checklist](interface_control_requirements.mdx) - -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/hardware_integration_requirements.mdx). - -``` 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.mdx) -::: - -### 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.mdx) to start using the software. +--- +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](interface_control_requirements.mdx) + +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/hardware_integration_requirements.mdx). + +``` 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.mdx) +::: + +### 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.mdx) to start using the software. diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_hardware_requirements.mdx index b6abe65eb..0883eba88 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_hardware_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_hardware_requirements.mdx @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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.10.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_introduction.mdx index 83bfa1d64..4f3f1bf7d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_introduction.mdx @@ -1,93 +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 +--- +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.10.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_operating_conditions.mdx index c02228aa5..6e0b17a54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_operating_conditions.mdx @@ -1,177 +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. - +--- +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.10.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_scope.mdx index ba0092f1c..f1a326070 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/overview/overview_scope.mdx @@ -1,15 +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). - - +--- +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.10.0/release_notes.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/release_notes.mdx index 104d27077..34f127dbc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/release_notes.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/release_notes.mdx @@ -1,253 +1,253 @@ ---- -title: Release Notes -sidebar_label: Release Notes -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -import Style from '/assets/css/changelog.css'; - -
- -## 0.10.0 - -### New Features - -- Added the ability to start mission from a specific Waypoint -- Added the ability to resume mission from current location -- Added the option to include on-start and on-stop tasks to a Mission -- Added the option to continue a Mission if a Task should fail -- Full release of the API examples repository to the public (link API examples top level page) - -### API Features - -- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api)) - - Mission.action added from_start and *start_waypoint_uuid* fields - - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields -- Message Definition changes - - Mission.msg: added an array of on_start and and array of on_stop tasks fields - - Task.msg: added a boolean allow_failure field -- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) -- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features - -### Bug Fixes - -- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location -- 1764: Importing missions with docking tasks fails to bring in docks - -### Known Issues - -- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint -- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect - -## 0.9.0 - -### New Features - -- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) -- 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.mdx)) -- 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.mdx)): - - /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.mdx)) - - 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.mdx#localizationstatus)). -- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#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.mdx#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.mdx) - 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. - +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Style from '/assets/css/changelog.css'; + +
+ +## 0.10.0 + +### New Features + +- Added the ability to start mission from a specific Waypoint +- Added the ability to resume mission from current location +- Added the option to include on-start and on-stop tasks to a Mission +- Added the option to continue a Mission if a Task should fail +- Full release of the API examples repository to the public (link API examples top level page) + +### API Features + +- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api)) + - Mission.action added from_start and *start_waypoint_uuid* fields + - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields +- Message Definition changes + - Mission.msg: added an array of on_start and and array of on_stop tasks fields + - Task.msg: added a boolean allow_failure field +- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) +- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features + +### Bug Fixes + +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location +- 1764: Importing missions with docking tasks fails to bring in docks + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) +- 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.mdx)) +- 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.mdx)): + - /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.mdx)) + - 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.mdx#localizationstatus)). +- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#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.mdx#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.mdx) + 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. +
\ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/safety.mdx index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/safety.mdx @@ -1,144 +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. +--- +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.10.0/simulation.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/simulation.mdx index 44cff5f7a..86043ef71 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/simulation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/simulation.mdx @@ -1,20 +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 +--- +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.10.0/support.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/support.mdx index 9212d99f2..4da40f82f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/support.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/support.mdx @@ -1,11 +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"; - +--- +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.10.0/web_user_interface/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/_category_.json index a07ca158b..31b780353 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Web User Interface", - "position": 6 -} +{ + "label": "Web User Interface", + "position": 6 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_autonomous_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_autonomous_mode.mdx index 164380eb7..66d0ee9d6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_autonomous_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_autonomous_mode.mdx @@ -1,411 +1,411 @@ ---- -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.mdx) 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. The user can -also rename the mission and apply Tasks to when the Mission starts and stops. - -### Rename Mission - -To rename the Mission click the Mission name as it appears in the upper left -hand corner. This should change the text into an input box that can then be -modified. Press enter/click aside to save the change. - -### Mission Tasks - -A Mission can have Tasks assigned to when it starts and when it stops. These -Tasks will run in the order they are listed in and will always run whenever the Mission -starts or stops. - -### 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). Waypoints in the table will also have a small icon to indicate - if tasks are assigned to the Waypoint accordingly. - - - 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.mdx#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 or as a start Mission Task; - that way, the UGV will automatically continue towards its next - Waypoint once undocked. - - :::note - - If the users places the Undock Task in the start Mission event the first Waypoint should be - approximately 2-3 meters behind the UGVs docked position. - - ::: - - - 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.mdx) section - for details on how to develop custom tasks for your application. -4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is - checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. - If its not checked, the Mission will become cancelled upon the Task's failure. -5. 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. - -:::note - -Waypoints that have a heading or tolerance assigned to them will show a different colour -on their settings icon. - -::: - -
-
- -
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 - -There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently -selected Mission by clicking the "Play" button . -Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button -to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by -obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on -"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. - -
-
- -
Starting from a specific Waypoint
-
-
- -When the Mission has been started the Play button will turn green, regardless of how it has been started. - -### 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. +--- +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.mdx) 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. The user can +also rename the mission and apply Tasks to when the Mission starts and stops. + +### Rename Mission + +To rename the Mission click the Mission name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Mission Tasks + +A Mission can have Tasks assigned to when it starts and when it stops. These +Tasks will run in the order they are listed in and will always run whenever the Mission +starts or stops. + +### 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). Waypoints in the table will also have a small icon to indicate + if tasks are assigned to the Waypoint accordingly. + + - 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.mdx#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 or as a start Mission Task; + that way, the UGV will automatically continue towards its next + Waypoint once undocked. + + :::note + + If the users places the Undock Task in the start Mission event the first Waypoint should be + approximately 2-3 meters behind the UGVs docked position. + + ::: + + - 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.mdx) section + for details on how to develop custom tasks for your application. +4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is + checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. + If its not checked, the Mission will become cancelled upon the Task's failure. +5. 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. + +:::note + +Waypoints that have a heading or tolerance assigned to them will show a different colour +on their settings icon. + +::: + +
+
+ +
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 + +There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently +selected Mission by clicking the "Play" button . +Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button +to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by +obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on +"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. + +
+
+ +
Starting from a specific Waypoint
+
+
+ +When the Mission has been started the Play button will turn green, regardless of how it has been started. + +### 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.10.0/web_user_interface/ui_manual_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_manual_mode.mdx index 055882848..7c049a0a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_manual_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_manual_mode.mdx @@ -1,49 +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.mdx) 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 +--- +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.mdx) 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.10.0/web_user_interface/ui_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_overview.mdx index 4e27e07e9..697054240 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.10.0/web_user_interface/ui_overview.mdx @@ -1,422 +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 - http://localhost:8000/{z}/{x}/{-y}.png. 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. +--- +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 + http://localhost:8000/{z}/{x}/{-y}.png. 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_docs/version-0.11.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_endpoints/api_endpoints.mdx index c65c4150b..e1169e6e2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_endpoints/api_endpoints.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_endpoints/api_endpoints.mdx @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/api_examples.mdx index 32daf5e7b..a8bdda373 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/api_examples.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/api_examples.mdx @@ -1,20 +1,20 @@ ---- -title: API Examples -sidebar_label: API Examples -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -The OutdoorNav API examples are now available and accesible to everyone. A -[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along -with some example scripts are available to build and use for our application. - -A few examples scripts follow with detailed explanations: - -- [Execute Mission from File](./mission_from_file.mdx) -- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) -- [Status Monitoring](./monitor_status.mdx) - -The documentation for the Python API library can be built following the -instructions in the above linked GitHub repository. +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav API examples are now available and accesible to everyone. A +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +with some example scripts are available to build and use for our application. + +A few examples scripts follow with detailed explanations: + +- [Execute Mission from File](./mission_from_file.mdx) +- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) +- [Status Monitoring](./monitor_status.mdx) + +The documentation for the Python API library can be built following the +instructions in the above linked GitHub repository. diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_from_file.mdx index eff0f7686..0abb4ea90 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_from_file.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_from_file.mdx @@ -1,210 +1,210 @@ ---- -title: Mission from YAML File -sidebar_label: Mission from YAML File -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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" -``` +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.11.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_with_custom_tasks.mdx index 30ec477ea..af8335aa6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_with_custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/mission_with_custom_tasks.mdx @@ -1,233 +1,233 @@ ---- -title: Mission with Custom Tasks -sidebar_label: Mission with Custom Tasks -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -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.mdx) 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. - - +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +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.mdx) 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.11.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/monitor_status.mdx index 077a9fcf5..a6fb416c5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/monitor_status.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_examples/monitor_status.mdx @@ -1,152 +1,152 @@ ---- -title: Monitor Status -sidebar_label: Monitor Status -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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. +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.11.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_overview.mdx index d9c6d616e..1bcb0ad92 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/api/api_overview.mdx @@ -1,63 +1,63 @@ ---- -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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions -- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) - that are used for creating, deleting, and modifying OutdoorNav Mission Schedules -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions +- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) + that are used for creating, deleting, and modifying OutdoorNav Mission Schedules +- [Definitions](api_endpoints/definitions.mdx): 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.11.0/cpr_hardware.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/cpr_hardware.mdx index f60527ff9..2d1efdd01 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/cpr_hardware.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/cpr_hardware.mdx @@ -1,405 +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](getting_started/system_setup.mdx#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. +--- +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](getting_started/system_setup.mdx#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.11.0/customized_tuning/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/_category_.json index 4c27a4d91..d38b7f55c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix C: Tuning & Customization", - "position": 14 +{ + "label": "Appendix C: Tuning & Customization", + "position": 14 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/sensor_customization.mdx index 9d9f115aa..f2cce53a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/sensor_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/sensor_customization.mdx @@ -1,9 +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. +--- +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.11.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/_category_.json index d62e291a4..4b3e7b596 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index 516393373..0125d8ddc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -1,9 +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. +--- +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.11.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 4b90f6008..6b105ecb3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/footprint_tuning.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -1,9 +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. +--- +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.11.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_overview.mdx index 851df29b0..77fbabeb9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_overview.mdx @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/_category_.json index fb6592a90..0e2dc60a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/navigation_parameters.mdx index b88562a4b..d4a2b559d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/navigation_parameters.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -1,169 +1,169 @@ ---- -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 -/opt/onav//app/autonomy/params//navigation/controls_general.yaml -/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml -/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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. +--- +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 +/opt/onav//app/autonomy/params//navigation/controls_general.yaml +/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml +/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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.11.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/user_interface_customization.mdx index c67bca22a..1e7d39c97 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/user_interface_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/customized_tuning/user_interface_customization.mdx @@ -1,9 +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. +--- +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.11.0/faq.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/faq.mdx index a086c4479..aad07b058 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/faq.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/faq.mdx @@ -1,194 +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.mdx#mission-execution)) or, - ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). - -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.mdx) 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) gets stored on - UGV's computer at the following location: `/opt/onav/saved_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.mdx). - 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.mdx). - -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.mdx) and contact - [Support](./support.mdx) 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.mdx#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.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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.mdx#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.mdx). - -5. **What to do if my custom task is not working?** - - Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) 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.mdx#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) - +--- +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.mdx#mission-execution)) or, + ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). + +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.mdx) 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) gets stored on + UGV's computer at the following location: `/opt/onav/saved_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.mdx). + 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.mdx). + +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.mdx) and contact + [Support](./support.mdx) 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.mdx#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.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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.mdx#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.mdx). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) 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.mdx#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.11.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/_category_.json index 732c6cb78..3bf04f17d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/features/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav Features", - "position": 8 -} +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/custom_tasks.mdx index 5b1176997..056e3ff54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/features/custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/custom_tasks.mdx @@ -1,206 +1,206 @@ ---- -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 -**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* -is the currently running version of OutdoorNav. 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 -``` +--- +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 +**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* +is the currently running version of OutdoorNav. 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.11.0/features/mission_scheduler.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/mission_scheduler.mdx index 95c870612..0afdfcaf3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/features/mission_scheduler.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/mission_scheduler.mdx @@ -1,43 +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 +--- +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.11.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/navigation.mdx index 852097a08..afbd5fe09 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/features/navigation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/navigation.mdx @@ -1,38 +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 -`/opt/onav//config/autonomy.env` file, where *onav_version* -is the currently running version of OutdoorNav. 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.mdx#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`).| +--- +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 +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. 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.mdx#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.11.0/features/rosbag_recorder.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/rosbag_recorder.mdx index 70a6c6877..25fa0cdab 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/features/rosbag_recorder.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/features/rosbag_recorder.mdx @@ -1,34 +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 `/opt/onav/saved_files/rosbags/` directory. +--- +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 `/opt/onav/saved_files/rosbags/` directory. diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/_category_.json index 8b4a486d9..9a9747ef6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/first_time_checklist.mdx index c4d9dece3..d90e0c8e5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/first_time_checklist.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/first_time_checklist.mdx @@ -1,114 +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#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.11.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/system_setup.mdx index ed52d7259..eedaae28f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/system_setup.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/system_setup.mdx @@ -1,239 +1,239 @@ ---- -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.mdx). - -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). Upon startup the user will be presented with a page that -shows the End-User License Agreement. This page will be visible each -time the UGV is restarted but only on the first navigation to the page. -The EULA should be reviewed prior to using the system. - -## 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.mdx) 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. +--- +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.mdx). + +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). Upon startup the user will be presented with a page that +shows the End-User License Agreement. This page will be visible each +time the UGV is restarted but only on the first navigation to the page. +The EULA should be reviewed prior to using the system. + +## 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.mdx) 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.11.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/terminal_interface.mdx index 8afafb7ca..b0fefc902 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/terminal_interface.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/terminal_interface.mdx @@ -1,249 +1,249 @@ ---- -title: Command Line Interface -sidebar_label: Command Line Interface -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -By default, the OutdoorNav Software begins automatically when the system -is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), -the set of commands that can be used by developers who are debugging -the system or who want more precise control for managing the OutdoorNav -software. - -## 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 separate OutdoorNav Computer, -first `ssh` to the UGV using the details provided in the UGV user -manual. Then, if a separate OutdoorNav Computer exists, you can -connect to it by running: - -``` bash -ssh administrator@192.168.131.5 -``` - -## OutdoorNav CLI Installation - -The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not -been installed on your system, it can be installed by running the following -on the OutdoorNav Computer: - -```bash -sudo apt-get install python3-onav-cli -``` - -:::note - -The command above requires that the Clearpath Package Server has been -configured on your OutdoorNav Computer. This is pre-configured on -Clearpath robots. Refer to details on the -[Clearpath Package Server](http://packages.clearpathrobotics.com/) if -this is not configured on your computer. - -::: - -## Listing the OutdoorNav CLI Commands and Getting Help - -To list all of the CLI commands, run the following on the OutdoorNav Computer: - -```bash -onav help -``` - -The CLI commands are: - -- `install`: Download and configure OutdoorNav -- `key`: Get, set, or delete your OutdoorNav license key -- `download`: Download OutdoorNav, but do not configure it -- `configure`: (Re)configure OutdoorNav -- `upgrade`: Upgrade OutdoorNav to the latest vesion -- `uninstall`: Uninstall OutdoorNav -- `depends`: Verify and install dependencies -- `start`: Start OutdoorNav -- `stop`: Stop OutdoorNav -- `status`: Check the status of OutdoorNav -- `logs`: View OutdoorNav logs -- `versions`: Print versions available to install -- `help`: Show available commands - -To get help on an individual command, use the `-h` option. For example, to -get help on the `install` command, run `onav install -h`: - -``` -usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION - -positional arguments: - VERSION The OutdoorNav version to install (e.g. 0.11.0) - -optional arguments: - -h, --help show this help message and exit - -k KEY, --key KEY Your OutdoorNav installation key - -b, --backpack Configure in backpack/bridged mode - -c, --clean Clean any configurations from a prior installation -``` - -## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} - -On UGV startup, all the sensors, the user interface, as well as the -autonomy software are set to start automatically. When debugging or when -greater control is desired, the CLI can be used to start and stop -the OutdoorNav software, in whole or in part. - -To see the current status of OutdoorNav software, run: - -```bash -onav status -``` - -To start the OutdoorNav software if it is not running, use the following command, -which starts the latest version of the software by default: - -```bash -onav start -``` - -To stop the OutdoorNav software, run: - -```bash -onav stop -``` - -## Stopping and Restarting the Autonomy Software Only - -To use the UGV without the autonomy software, use the following -command to stop the nodes and prevent them from automatic startup: - -``` bash -onav stop -s autonomy -``` - -The autonomy software can be restarted by running: - -``` bash -onav start -s autonomy -``` - -## 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 -onav stop -s sensors -``` - -:::note - -This command will only disable the drivers for the sensors that are started -by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, -and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense -cameras, 2D Lidars). - -::: - -The sensors software can be restarted by running: - -``` -onav start -s sensors -``` - -## Accessing the OutdoorNav Software Logs - -To check the logs of the OutdoorNav software, use the `onav logs` command -with the appropriate service. For example, to view the logs for the sensors -service, run: - -```bash -onav logs sensors -``` - -## Installing the OutdoorNav Software - -OutdoorNav is typically pre-installed on Clearpath robots, so most users should -not need to do a first-time installation of the software, though the process -is outlined below as a reference. - -As a first step, confirm that the robot has internet access. For example, confirm -that the following command is successful: - -``` -ping 8.8.8.8 -``` - -Second, the required dependencies need to be installed by running: - -```bash -onav depends -``` - -Third, a key needs to be added onto the robot to enable the installation -process. Contact [Clearpath Support](../support) if you did not receive your key. -To add your key, run the following, replacing `` with the actual value: - -```bash -onav key -``` - -Fourth, list the versions available for installation by running: - -```bash -onav versions -``` - -Fifth, install the OutdoorNav software for the desired version (typically the -newest version), by running the following, replacing `` with -the version to be installed: - -```bash -onav install -``` - -When prompted, trigger the reboot. - -Finally, following the reboot, run the following command to start the OutdoorNav -software. This will only be required the first time after installation. - -```bash -onav start -``` - -## Upgrading the OutdoorNav Software - -After receiving a notice that a new version of the OutdoorNav Software is -available, use the `onav install` command with the appropriate version. -Note that `onav install` runs the following commands in sequence: - -- `onav download` -- `onav configure` -- `onav upgrade` - -For example, to upgrade from 0.11.0 to 0.12.0, run the following command: - -``` -onav install 0.12.0 -``` - -:::note - -The `download` step requires internet access to download the new software. -Confirm that the OutdoorNav Computer has internet access by running a command -such as: - -``` -ping 8.8.8.8 -``` - -::: - -## Uninstalling Old Versions of OutdoorNav Software - -If old versions of OutdoorNav software are no longer being used, they can -be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 -run: - -``` -onav uninstall 0.11.0 +--- +title: Command Line Interface +sidebar_label: Command Line Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +By default, the OutdoorNav Software begins automatically when the system +is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), +the set of commands that can be used by developers who are debugging +the system or who want more precise control for managing the OutdoorNav +software. + +## 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 separate OutdoorNav Computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. Then, if a separate OutdoorNav Computer exists, you can +connect to it by running: + +``` bash +ssh administrator@192.168.131.5 +``` + +## OutdoorNav CLI Installation + +The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not +been installed on your system, it can be installed by running the following +on the OutdoorNav Computer: + +```bash +sudo apt-get install python3-onav-cli +``` + +:::note + +The command above requires that the Clearpath Package Server has been +configured on your OutdoorNav Computer. This is pre-configured on +Clearpath robots. Refer to details on the +[Clearpath Package Server](http://packages.clearpathrobotics.com/) if +this is not configured on your computer. + +::: + +## Listing the OutdoorNav CLI Commands and Getting Help + +To list all of the CLI commands, run the following on the OutdoorNav Computer: + +```bash +onav help +``` + +The CLI commands are: + +- `install`: Download and configure OutdoorNav +- `key`: Get, set, or delete your OutdoorNav license key +- `download`: Download OutdoorNav, but do not configure it +- `configure`: (Re)configure OutdoorNav +- `upgrade`: Upgrade OutdoorNav to the latest vesion +- `uninstall`: Uninstall OutdoorNav +- `depends`: Verify and install dependencies +- `start`: Start OutdoorNav +- `stop`: Stop OutdoorNav +- `status`: Check the status of OutdoorNav +- `logs`: View OutdoorNav logs +- `versions`: Print versions available to install +- `help`: Show available commands + +To get help on an individual command, use the `-h` option. For example, to +get help on the `install` command, run `onav install -h`: + +``` +usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION + +positional arguments: + VERSION The OutdoorNav version to install (e.g. 0.11.0) + +optional arguments: + -h, --help show this help message and exit + -k KEY, --key KEY Your OutdoorNav installation key + -b, --backpack Configure in backpack/bridged mode + -c, --clean Clean any configurations from a prior installation +``` + +## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} + +On UGV startup, all the sensors, the user interface, as well as the +autonomy software are set to start automatically. When debugging or when +greater control is desired, the CLI can be used to start and stop +the OutdoorNav software, in whole or in part. + +To see the current status of OutdoorNav software, run: + +```bash +onav status +``` + +To start the OutdoorNav software if it is not running, use the following command, +which starts the latest version of the software by default: + +```bash +onav start +``` + +To stop the OutdoorNav software, run: + +```bash +onav stop +``` + +## Stopping and Restarting the Autonomy Software Only + +To use the UGV without the autonomy software, use the following +command to stop the nodes and prevent them from automatic startup: + +``` bash +onav stop -s autonomy +``` + +The autonomy software can be restarted by running: + +``` bash +onav start -s autonomy +``` + +## 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 +onav stop -s sensors +``` + +:::note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars). + +::: + +The sensors software can be restarted by running: + +``` +onav start -s sensors +``` + +## Accessing the OutdoorNav Software Logs + +To check the logs of the OutdoorNav software, use the `onav logs` command +with the appropriate service. For example, to view the logs for the sensors +service, run: + +```bash +onav logs sensors +``` + +## Installing the OutdoorNav Software + +OutdoorNav is typically pre-installed on Clearpath robots, so most users should +not need to do a first-time installation of the software, though the process +is outlined below as a reference. + +As a first step, confirm that the robot has internet access. For example, confirm +that the following command is successful: + +``` +ping 8.8.8.8 +``` + +Second, the required dependencies need to be installed by running: + +```bash +onav depends +``` + +Third, a key needs to be added onto the robot to enable the installation +process. Contact [Clearpath Support](../support) if you did not receive your key. +To add your key, run the following, replacing `` with the actual value: + +```bash +onav key +``` + +Fourth, list the versions available for installation by running: + +```bash +onav versions +``` + +Fifth, install the OutdoorNav software for the desired version (typically the +newest version), by running the following, replacing `` with +the version to be installed: + +```bash +onav install +``` + +When prompted, trigger the reboot. + +Finally, following the reboot, run the following command to start the OutdoorNav +software. This will only be required the first time after installation. + +```bash +onav start +``` + +## Upgrading the OutdoorNav Software + +After receiving a notice that a new version of the OutdoorNav Software is +available, use the `onav install` command with the appropriate version. +Note that `onav install` runs the following commands in sequence: + +- `onav download` +- `onav configure` +- `onav upgrade` + +For example, to upgrade from 0.11.0 to 0.12.0, run the following command: + +``` +onav install 0.12.0 +``` + +:::note + +The `download` step requires internet access to download the new software. +Confirm that the OutdoorNav Computer has internet access by running a command +such as: + +``` +ping 8.8.8.8 +``` + +::: + +## Uninstalling Old Versions of OutdoorNav Software + +If old versions of OutdoorNav software are no longer being used, they can +be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 +run: + +``` +onav uninstall 0.11.0 ``` \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/tf_validation.mdx index 72327dbc3..ab05b15f1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/tf_validation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/getting_started/tf_validation.mdx @@ -1,80 +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
-
-
- -::: +--- +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.11.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/index.mdx @@ -1,18 +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 +--- +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.11.0/integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/_category_.json index e9e0ff1dd..adbe22cba 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix A: UGV Integration Requirements", - "position": 12 +{ + "label": "Appendix A: UGV Integration Requirements", + "position": 12 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/hardware_integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/hardware_integration_requirements/_category_.json index 75ebaf1b4..7950de6b7 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/hardware_integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/hardware_integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Hardware Kit Installation", - "position": 2 -} +{ + "label": "Hardware Kit Installation", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/integration_overview.mdx index 00cf8a071..72d78ae31 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/integration_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/integration_overview.mdx @@ -1,34 +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. | +--- +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.11.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/interface_control_requirements.mdx index a603485bb..d9906ed65 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/interface_control_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/interface_control_requirements.mdx @@ -1,119 +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.mdx#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). +--- +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.mdx#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.11.0/integration_requirements/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/software_integration_instructions.mdx index 8126e0719..006096b68 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/software_integration_instructions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/integration_requirements/software_integration_instructions.mdx @@ -1,122 +1,122 @@ ---- -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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: -- [Interface Control Checklist](interface_control_requirements.mdx) - -All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. - -### Install Command-line Interface Tool (CLI) {#install-cli} - - -{` -sudo apt update -sudo apt install python3-onav-cli -`} - - -### Install OutdoorNav - - -{` -onav install -k -`} - - -where `license_key` is the license key that you have been assigned. Only one license key can be used per UGV. - -### 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 /opt/onav//config -nano autonomy.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/Stop the OutdoorNav - -To start up the OutdoorNav software run: - - -{` -onav start -`} - - -If you wish to start individual profiles or services, run `onav start -h` to see available profiles/services. - -To stop the OutdoorNav software run: - - -{` -onav stop -`} - - -For more information and available ONAV CLI commands, see the [Terminal Interface](../getting_started/terminal_interface.mdx) section. - -### 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 - -rostopic echo -n 1 /localization/odom - -# GNSS units -rostopic echo /sensors/gps_/fix - -# IMU (if included) -rostopic echo -n 1 /sensors/imu_/data - -# 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 --noarr -rostopic echo -n 1 /sensors/stereo_0/image --noarr -rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw --noarr - -# Realsense D435 Rear (if included) -rostopic echo -n 1 /sensors/stereo_1/pointcloud --noarr -rostopic echo -n 1 /sensors/stereo_1/image --noarr -rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw --noarr -``` - -\ 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.mdx) to start using the software. +--- +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](interface_control_requirements.mdx) + +All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. + +### Install Command-line Interface Tool (CLI) {#install-cli} + + +{` +sudo apt update +sudo apt install python3-onav-cli +`} + + +### Install OutdoorNav + + +{` +onav install -k +`} + + +where `license_key` is the license key that you have been assigned. Only one license key can be used per UGV. + +### 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 /opt/onav//config +nano autonomy.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/Stop the OutdoorNav + +To start up the OutdoorNav software run: + + +{` +onav start +`} + + +If you wish to start individual profiles or services, run `onav start -h` to see available profiles/services. + +To stop the OutdoorNav software run: + + +{` +onav stop +`} + + +For more information and available ONAV CLI commands, see the [Terminal Interface](../getting_started/terminal_interface.mdx) section. + +### 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 + +rostopic echo -n 1 /localization/odom + +# GNSS units +rostopic echo /sensors/gps_/fix + +# IMU (if included) +rostopic echo -n 1 /sensors/imu_/data + +# 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 --noarr +rostopic echo -n 1 /sensors/stereo_0/image --noarr +rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw --noarr + +# Realsense D435 Rear (if included) +rostopic echo -n 1 /sensors/stereo_1/pointcloud --noarr +rostopic echo -n 1 /sensors/stereo_1/image --noarr +rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw --noarr +``` + +\ 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.mdx) to start using the software. diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_hardware_requirements.mdx index b6abe65eb..0883eba88 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_hardware_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_hardware_requirements.mdx @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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.11.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_introduction.mdx index 83bfa1d64..4f3f1bf7d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_introduction.mdx @@ -1,93 +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 +--- +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.11.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_operating_conditions.mdx index c02228aa5..6e0b17a54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_operating_conditions.mdx @@ -1,177 +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. - +--- +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.11.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_scope.mdx index ba0092f1c..f1a326070 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/overview/overview_scope.mdx @@ -1,15 +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). - - +--- +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.11.0/release_notes.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/release_notes.mdx index e6d963319..bb165f281 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/release_notes.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/release_notes.mdx @@ -1,279 +1,279 @@ ---- -title: Release Notes -sidebar_label: Release Notes -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -import Style from '/assets/css/changelog.css'; - -
- -## 0.11.0 - -### New Features - -- Command Line Tool used to install/update/manage OutdoorNav -- Added the End User License Agreement to the UI upon start up -- Light and PTZ Pan/Tilt controls can now be mapped to a controller -- OutdoorNav/IndoorNav switch over improvements -- Can now place waypoints at UGV location via shortcut key (Shift + X) - -### API Features - -- Can now delete multiple mission objects (missions, waypoints, tasks) in single call -- Stack Light can now be manually overridden/muted -- Added ability to import single missions to the robot - -### Bug Fixes - -- 1688: Move PTZ task only ever uses the first PTZ camera's positions -- 2011: Filter false "Move PTZ Failure" notifications when moving PTZ camera - -### Known Issues - -- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint -- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect - -## 0.10.0 - -### New Features - -- Added the ability to start mission from a specific Waypoint -- Added the ability to resume mission from current location -- Added the option to include on-start and on-stop tasks to a Mission -- Added the option to continue a Mission if a Task should fail -- Full release of the API examples repository to the public (link API examples top level page) - -### API Features - -- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api)) - - Mission.action added from_start and *start_waypoint_uuid* fields - - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields -- Message Definition changes - - Mission.msg: added an array of on_start and and array of on_stop tasks fields - - Task.msg: added a boolean allow_failure field -- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) -- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features - -### Bug Fixes - -- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location -- 1764: Importing missions with docking tasks fails to bring in docks - -### Known Issues - -- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint -- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect - -## 0.9.0 - -### New Features - -- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) -- 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.mdx)) -- 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.mdx)): - - /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.mdx)) - - 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.mdx#localizationstatus)). -- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#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.mdx#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.mdx) - 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. - +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Style from '/assets/css/changelog.css'; + +
+ +## 0.11.0 + +### New Features + +- Command Line Tool used to install/update/manage OutdoorNav +- Added the End User License Agreement to the UI upon start up +- Light and PTZ Pan/Tilt controls can now be mapped to a controller +- OutdoorNav/IndoorNav switch over improvements +- Can now place waypoints at UGV location via shortcut key (Shift + X) + +### API Features + +- Can now delete multiple mission objects (missions, waypoints, tasks) in single call +- Stack Light can now be manually overridden/muted +- Added ability to import single missions to the robot + +### Bug Fixes + +- 1688: Move PTZ task only ever uses the first PTZ camera's positions +- 2011: Filter false "Move PTZ Failure" notifications when moving PTZ camera + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.10.0 + +### New Features + +- Added the ability to start mission from a specific Waypoint +- Added the ability to resume mission from current location +- Added the option to include on-start and on-stop tasks to a Mission +- Added the option to continue a Mission if a Task should fail +- Full release of the API examples repository to the public (link API examples top level page) + +### API Features + +- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api)) + - Mission.action added from_start and *start_waypoint_uuid* fields + - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields +- Message Definition changes + - Mission.msg: added an array of on_start and and array of on_stop tasks fields + - Task.msg: added a boolean allow_failure field +- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) +- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features + +### Bug Fixes + +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location +- 1764: Importing missions with docking tasks fails to bring in docks + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) +- 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.mdx)) +- 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.mdx)): + - /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.mdx)) + - 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.mdx#localizationstatus)). +- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#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.mdx#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.mdx) + 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. +
\ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/safety.mdx index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/safety.mdx @@ -1,144 +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. +--- +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.11.0/simulation.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/simulation.mdx index 44cff5f7a..86043ef71 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/simulation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/simulation.mdx @@ -1,20 +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 +--- +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.11.0/support.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/support.mdx index 9212d99f2..4da40f82f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/support.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/support.mdx @@ -1,11 +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"; - +--- +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.11.0/web_user_interface/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/_category_.json index a07ca158b..31b780353 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Web User Interface", - "position": 6 -} +{ + "label": "Web User Interface", + "position": 6 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_autonomous_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_autonomous_mode.mdx index 61acab879..3248ccad0 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_autonomous_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_autonomous_mode.mdx @@ -1,434 +1,434 @@ ---- -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.mdx) 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. The user can -also rename the mission and apply Tasks to when the Mission starts and stops. - -### Rename Mission - -To rename the Mission click the Mission name as it appears in the upper left -hand corner. This should change the text into an input box that can then be -modified. Press enter/click aside to save the change. - -### Mission Tasks - -A Mission can have Tasks assigned to when it starts and when it stops. These -Tasks will run in the order they are listed in and will always run whenever the Mission -starts or stops. - -### 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). Waypoints in the table will also have a small icon to indicate - if tasks are assigned to the Waypoint accordingly. - - - 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.mdx#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 **/opt/onav/saved_files/media/...** directory 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 **/opt/onav/saved_files/media/...** 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 or as a start Mission Task; - that way, the UGV will automatically continue towards its next - Waypoint once undocked. - - :::note - - If the users places the Undock Task in the start Mission event the first Waypoint should be - approximately 2-3 meters behind the UGVs docked position. - - ::: - - - 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.mdx) section - for details on how to develop custom tasks for your application. -4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is - checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. - If its not checked, the Mission will become cancelled upon the Task's failure. -5. 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. - -:::note - -Waypoints that have a heading or tolerance assigned to them will show a different colour -on their settings icon. - -::: - -
-
- -
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 - -There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently -selected Mission by clicking the "Play" button . -Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button -to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by -obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on -"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. - -
-
- -
Starting from a specific Waypoint
-
-
- -When the Mission has been started the Play button will turn green, regardless of how it has been started. - -### 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. - -## Switching to IndoorNav - -If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. -To switch between the modes in OutdoorNav select the 'Navigation Mode' option found -in the hamburger menu. This will navigate to a page that shows the current mode and -provides an option to switch. When in IndoorNav mode the user may navigate to -the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen -below. - -
-
- -
-
- -:::note - -When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will -disable OutdoorNav UI features related to Autonomy but will still allow users the -option to view camera streams. - +--- +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.mdx) 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. The user can +also rename the mission and apply Tasks to when the Mission starts and stops. + +### Rename Mission + +To rename the Mission click the Mission name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Mission Tasks + +A Mission can have Tasks assigned to when it starts and when it stops. These +Tasks will run in the order they are listed in and will always run whenever the Mission +starts or stops. + +### 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). Waypoints in the table will also have a small icon to indicate + if tasks are assigned to the Waypoint accordingly. + + - 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.mdx#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 **/opt/onav/saved_files/media/...** directory 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 **/opt/onav/saved_files/media/...** 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 or as a start Mission Task; + that way, the UGV will automatically continue towards its next + Waypoint once undocked. + + :::note + + If the users places the Undock Task in the start Mission event the first Waypoint should be + approximately 2-3 meters behind the UGVs docked position. + + ::: + + - 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.mdx) section + for details on how to develop custom tasks for your application. +4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is + checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. + If its not checked, the Mission will become cancelled upon the Task's failure. +5. 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. + +:::note + +Waypoints that have a heading or tolerance assigned to them will show a different colour +on their settings icon. + +::: + +
+
+ +
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 + +There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently +selected Mission by clicking the "Play" button . +Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button +to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by +obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on +"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. + +
+
+ +
Starting from a specific Waypoint
+
+
+ +When the Mission has been started the Play button will turn green, regardless of how it has been started. + +### 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. + +## Switching to IndoorNav + +If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. +To switch between the modes in OutdoorNav select the 'Navigation Mode' option found +in the hamburger menu. This will navigate to a page that shows the current mode and +provides an option to switch. When in IndoorNav mode the user may navigate to +the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen +below. + +
+
+ +
+
+ +:::note + +When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will +disable OutdoorNav UI features related to Autonomy but will still allow users the +option to view camera streams. + ::: \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_manual_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_manual_mode.mdx index 055882848..7c049a0a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_manual_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_manual_mode.mdx @@ -1,49 +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.mdx) 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 +--- +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.mdx) 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.11.0/web_user_interface/ui_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_overview.mdx index e9957ce7e..4a8e60269 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.11.0/web_user_interface/ui_overview.mdx @@ -1,423 +1,423 @@ ---- -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. - This action can also be triggered by using the shortcut key combination Shift + X. - -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 - http://localhost:8000/{z}/{x}/{-y}.png. 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. +--- +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. + This action can also be triggered by using the shortcut key combination Shift + X. + +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 + http://localhost:8000/{z}/{x}/{-y}.png. 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_docs/version-0.12.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx index c65c4150b..e1169e6e2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx index 333bd1355..eb556d30a 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx @@ -1,21 +1,21 @@ ---- -title: API Examples -sidebar_label: API Examples -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -The OutdoorNav API examples are now available and accesible to everyone. A -[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along -with some example scripts are available to build and use for our application. - -A few examples scripts follow with detailed explanations: - -- [Execute Mission from File](./mission_from_file.mdx) -- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) -- [Status Monitoring](./monitor_status.mdx) -- [Network of Paths](./network_of_paths.mdx) - -The documentation for the Python API library can be built following the -instructions in the above linked GitHub repository. +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav API examples are now available and accesible to everyone. A +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +with some example scripts are available to build and use for our application. + +A few examples scripts follow with detailed explanations: + +- [Execute Mission from File](./mission_from_file.mdx) +- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) +- [Status Monitoring](./monitor_status.mdx) +- [Network of Paths](./network_of_paths.mdx) + +The documentation for the Python API library can be built following the +instructions in the above linked GitHub repository. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx index eff0f7686..0abb4ea90 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx @@ -1,210 +1,210 @@ ---- -title: Mission from YAML File -sidebar_label: Mission from YAML File -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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" -``` +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.12.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_with_custom_tasks.mdx index 30ec477ea..af8335aa6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_with_custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_with_custom_tasks.mdx @@ -1,233 +1,233 @@ ---- -title: Mission with Custom Tasks -sidebar_label: Mission with Custom Tasks -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -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.mdx) 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. - - +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +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.mdx) 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.12.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/monitor_status.mdx index 077a9fcf5..a6fb416c5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/monitor_status.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/monitor_status.mdx @@ -1,152 +1,152 @@ ---- -title: Monitor Status -sidebar_label: Monitor Status -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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. +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.12.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_overview.mdx index d9c6d616e..1bcb0ad92 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_overview.mdx @@ -1,63 +1,63 @@ ---- -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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions -- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) - that are used for creating, deleting, and modifying OutdoorNav Mission Schedules -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions +- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) + that are used for creating, deleting, and modifying OutdoorNav Mission Schedules +- [Definitions](api_endpoints/definitions.mdx): 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.12.0/cpr_hardware.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/cpr_hardware.mdx index f60527ff9..2d1efdd01 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/cpr_hardware.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/cpr_hardware.mdx @@ -1,405 +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](getting_started/system_setup.mdx#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. +--- +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](getting_started/system_setup.mdx#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.12.0/customized_tuning/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/_category_.json index 4c27a4d91..d38b7f55c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix C: Tuning & Customization", - "position": 14 +{ + "label": "Appendix C: Tuning & Customization", + "position": 14 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx index 9d9f115aa..f2cce53a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx @@ -1,9 +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. +--- +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.12.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/_category_.json index d62e291a4..4b3e7b596 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index 516393373..0125d8ddc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -1,9 +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. +--- +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.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 4b90f6008..6b105ecb3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -1,9 +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. +--- +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.12.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_overview.mdx index 851df29b0..77fbabeb9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_overview.mdx @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json index fb6592a90..0e2dc60a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx index b88562a4b..d4a2b559d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -1,169 +1,169 @@ ---- -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 -/opt/onav//app/autonomy/params//navigation/controls_general.yaml -/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml -/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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. +--- +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 +/opt/onav//app/autonomy/params//navigation/controls_general.yaml +/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml +/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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.12.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/user_interface_customization.mdx index c67bca22a..1e7d39c97 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/user_interface_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/user_interface_customization.mdx @@ -1,9 +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. +--- +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.12.0/faq.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/faq.mdx index 374e05b3a..ec2efaef4 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/faq.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/faq.mdx @@ -1,194 +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_waypoint_mode.mdx#mission-execution)) or, - ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). - -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.mdx) 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) gets stored on - UGV's computer at the following location: `/opt/onav/saved_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.mdx). - 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.mdx). - -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.mdx) and contact - [Support](./support.mdx) 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.mdx#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_waypoint_mode.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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_waypoint_mode.mdx#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.mdx). - -5. **What to do if my custom task is not working?** - - Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) instructions. When adding the - custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_waypoint_mode.mdx#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) - +--- +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_waypoint_mode.mdx#mission-execution)) or, + ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). + +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.mdx) 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) gets stored on + UGV's computer at the following location: `/opt/onav/saved_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.mdx). + 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.mdx). + +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.mdx) and contact + [Support](./support.mdx) 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.mdx#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_waypoint_mode.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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_waypoint_mode.mdx#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.mdx). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) instructions. When adding the + custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_waypoint_mode.mdx#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.12.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/_category_.json index 732c6cb78..3bf04f17d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav Features", - "position": 8 -} +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx index 74f5e010c..036ffe225 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx @@ -1,105 +1,105 @@ ---- -title: Assisted Teleoperation -sidebar_label: Assisted Teleoperation -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -:::danger SAFETY WARNING - -Making changes to any of the following variables will decrease system safety. It is recommended that users -only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx). - -::: - -:::note - -Changes to any of the following variables will only take effect after power cycling the UGV. - -::: - - -As of version 0.12.0, the OutdoorNav software contains an assisted teleoperation feature that will help users -teleoperate their UGV safely, without worry of colliding into obstacles. - -
-
- -
Block Diagram of Assisted Teleoperation Twist Mux
-
-
- - -The assisted teleoperation feature is intended to work with the following sources of velocity input: - -| Input source | Topic | -|--------------|--------| -| UI Joystick | `/ui_teleop/cmd_vel` | -| PS4 Controlller | `/bluetooth_teleop/cmd_vel` or `/joy_teleop/cmd_vel`| -| Logitech Controller | `/joy_teleop/cmd_vel` | - - -The Assisted teleop feature will **NOT** work on the following sources of velocity input: - -| Input source | Topic | -|--------------|-------| -| External Command | `/cmd_vel` | -| Keyboard Command | `/kb_teleop/cmd_vel` | -| Interactive Marker | `/twist_marker_server/cmd_vel` | - -The Assisted Teleoperation feature can be activated/deactivated according to your required application requirements. -This can be done by setting the **ENABLE_ASSISTED_TELEOP** environment variable in the -`/opt/onav//config/autonomy.env` file, where *onav_version* -is the currently running version of OutdoorNav. - -## Functionality - -The intended purpose for the assisted teleoperation feature is to provide some software level safety for users while they are teleoperating the UGV. -This feature is intended to solely provide software level safety and does not use any hardware level PLCs to trigger a motor disconnect. It is to be -treated as a tool that provides a sense of security to the user, such that they will not accidentally crash the UGV any obstacles. The feature -constantly monitors the 2D/3D LiDAR sensor data that it is provided and uses this information to control the velocity of the UGV. As the UGV -approaches obstacles, it will decrease the velocity of the UGV and will bring the UGV to a complete stop if the user continues to drive -towards the oncoming obstacle. - -For visualization details of the assisted teleoperation feature, please consult the [UI Manual Mode](../web_user_interface/ui_manual_mode.mdx) page. - -### Enable/Disable from the UI - -From the OutdoorNav UI you are able to enable/disable the "Teleop Assist" by using the toggle that is located by the UI joystick. - -### Enable/Disable using Joystick - -To disable the "Teleop Assist" when driving the UGV with the PS4 or Logitech controllers, you will need to press and hold the following button: - -| Controller Type | Button | -|--------------|-------| -| PS4 controller | **O** | -| Logitech controller | **B** | - -### Error/Warnings - -OutdoorNav will throw warnings and display them on the UI related to the status of the assisted teleoperation feature. -Below are the errors/warnings you may see: - -| Error/Warning | Reason | -|---------------|--------| -| **"Error: Failed to communicate with the Assisted Teleop node"** | The assisted teleoperation node is not running or has crashed | -| **"Error: No sensors configured"** | The assisted teleoperation node is running but no sensors have been configured to be used as obstacle detection sources | -| **"Error: Invalid twist_mux configuration"** | The twists mux configuration has been modified and does not satisfy the requirements for safe operation under the requirements of assisted teleoperation | -| **"Error: Unknown platform type"** | The assisted teleoperation node cannot determine the type of platform you are on | -| **"WARNING: Assisted teleoperation OFF due to service"** | The UI toggle switch or the `/assisted_teleop/enable` service has disabled assisted teloperation | -| **"WARNING: Assisted teleoperation OFF due to joystick override"** | The enable/disable button on the UGV remote joystick has been pressed | -| **"WARNING: Assisted teleoperation OFF due to sensor timeout"** | Communication has been lost between the assisted teloperation node and one of the configured 2D/3D detection sensors. | -| **"Warning: Robot is in a collision state and cannot be driven while assisted teleop is enabled. Please disable assisted teleop to recover."** | The robot is is a state where is is too close to an obstacle. This will mostly occur when you are at a charge dock but may also occur if you are driving/rotating in a tight space. You may need to disable the Teleop Assist to continue remote operation | - - -## Limitations - -The assisted teleoperation features has similar limitations to those of our collision avoidance features. -Performance degradation will be experiences in rain and/or snow conditions, as well as in tall grass environments. -The assisted teleoperation feature also only work if obstacles are detected by the 3D sensors. If obstacles appear -in any of the UGVs blind spots, the assisted teleoperation feature will not prevent collision with these obstacles. +--- +title: Assisted Teleoperation +sidebar_label: Assisted Teleoperation +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::danger SAFETY WARNING + +Making changes to any of the following variables will decrease system safety. It is recommended that users +only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx). + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + + +As of version 0.12.0, the OutdoorNav software contains an assisted teleoperation feature that will help users +teleoperate their UGV safely, without worry of colliding into obstacles. + +
+
+ +
Block Diagram of Assisted Teleoperation Twist Mux
+
+
+ + +The assisted teleoperation feature is intended to work with the following sources of velocity input: + +| Input source | Topic | +|--------------|--------| +| UI Joystick | `/ui_teleop/cmd_vel` | +| PS4 Controlller | `/bluetooth_teleop/cmd_vel` or `/joy_teleop/cmd_vel`| +| Logitech Controller | `/joy_teleop/cmd_vel` | + + +The Assisted teleop feature will **NOT** work on the following sources of velocity input: + +| Input source | Topic | +|--------------|-------| +| External Command | `/cmd_vel` | +| Keyboard Command | `/kb_teleop/cmd_vel` | +| Interactive Marker | `/twist_marker_server/cmd_vel` | + +The Assisted Teleoperation feature can be activated/deactivated according to your required application requirements. +This can be done by setting the **ENABLE_ASSISTED_TELEOP** environment variable in the +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. + +## Functionality + +The intended purpose for the assisted teleoperation feature is to provide some software level safety for users while they are teleoperating the UGV. +This feature is intended to solely provide software level safety and does not use any hardware level PLCs to trigger a motor disconnect. It is to be +treated as a tool that provides a sense of security to the user, such that they will not accidentally crash the UGV any obstacles. The feature +constantly monitors the 2D/3D LiDAR sensor data that it is provided and uses this information to control the velocity of the UGV. As the UGV +approaches obstacles, it will decrease the velocity of the UGV and will bring the UGV to a complete stop if the user continues to drive +towards the oncoming obstacle. + +For visualization details of the assisted teleoperation feature, please consult the [UI Manual Mode](../web_user_interface/ui_manual_mode.mdx) page. + +### Enable/Disable from the UI + +From the OutdoorNav UI you are able to enable/disable the "Teleop Assist" by using the toggle that is located by the UI joystick. + +### Enable/Disable using Joystick + +To disable the "Teleop Assist" when driving the UGV with the PS4 or Logitech controllers, you will need to press and hold the following button: + +| Controller Type | Button | +|--------------|-------| +| PS4 controller | **O** | +| Logitech controller | **B** | + +### Error/Warnings + +OutdoorNav will throw warnings and display them on the UI related to the status of the assisted teleoperation feature. +Below are the errors/warnings you may see: + +| Error/Warning | Reason | +|---------------|--------| +| **"Error: Failed to communicate with the Assisted Teleop node"** | The assisted teleoperation node is not running or has crashed | +| **"Error: No sensors configured"** | The assisted teleoperation node is running but no sensors have been configured to be used as obstacle detection sources | +| **"Error: Invalid twist_mux configuration"** | The twists mux configuration has been modified and does not satisfy the requirements for safe operation under the requirements of assisted teleoperation | +| **"Error: Unknown platform type"** | The assisted teleoperation node cannot determine the type of platform you are on | +| **"WARNING: Assisted teleoperation OFF due to service"** | The UI toggle switch or the `/assisted_teleop/enable` service has disabled assisted teloperation | +| **"WARNING: Assisted teleoperation OFF due to joystick override"** | The enable/disable button on the UGV remote joystick has been pressed | +| **"WARNING: Assisted teleoperation OFF due to sensor timeout"** | Communication has been lost between the assisted teloperation node and one of the configured 2D/3D detection sensors. | +| **"Warning: Robot is in a collision state and cannot be driven while assisted teleop is enabled. Please disable assisted teleop to recover."** | The robot is is a state where is is too close to an obstacle. This will mostly occur when you are at a charge dock but may also occur if you are driving/rotating in a tight space. You may need to disable the Teleop Assist to continue remote operation | + + +## Limitations + +The assisted teleoperation features has similar limitations to those of our collision avoidance features. +Performance degradation will be experiences in rain and/or snow conditions, as well as in tall grass environments. +The assisted teleoperation feature also only work if obstacles are detected by the 3D sensors. If obstacles appear +in any of the UGVs blind spots, the assisted teleoperation feature will not prevent collision with these obstacles. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx index 5b1176997..056e3ff54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx @@ -1,206 +1,206 @@ ---- -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 -**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* -is the currently running version of OutdoorNav. 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 -``` +--- +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 +**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* +is the currently running version of OutdoorNav. 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.12.0/features/mission_scheduler.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/mission_scheduler.mdx index aef2ea67a..27828578c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/mission_scheduler.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/mission_scheduler.mdx @@ -1,50 +1,50 @@ ---- -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. - -:::note - -Presently only Waypoint Missions can be scheduled with the scheduler. A future update will allow users to schedule both Map and -Waypoint Missions together in a single schedule. - -::: - -
-
- -
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 +--- +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. + +:::note + +Presently only Waypoint Missions can be scheduled with the scheduler. A future update will allow users to schedule both Map and +Waypoint Missions together in a single schedule. + +::: + +
+
+ +
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.12.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/navigation.mdx index d2e0284df..5b4dfa2df 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/navigation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/navigation.mdx @@ -1,38 +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 -`/opt/onav//config/autonomy.env` file, where *onav_version* -is the currently running version of OutdoorNav. 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 drive 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_waypoint_mode.mdx#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`).| +--- +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 +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. 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 drive 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_waypoint_mode.mdx#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.12.0/features/rosbag_recorder.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/rosbag_recorder.mdx index 70a6c6877..25fa0cdab 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/rosbag_recorder.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/rosbag_recorder.mdx @@ -1,34 +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 `/opt/onav/saved_files/rosbags/` directory. +--- +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 `/opt/onav/saved_files/rosbags/` directory. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json index 8b4a486d9..9a9747ef6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx index e7298e8ae..9044c8da1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx @@ -1,114 +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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_waypoint_mode.mdx#mission-creation). - -### ☐ After creating a new mission, can you execute the mission? - -To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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_waypoint_mode.mdx#mission-creation). + +### ☐ After creating a new mission, can you execute the mission? + +To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#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.mdx#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.mdx#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.12.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/system_setup.mdx index c8060f356..173227ff2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/system_setup.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/system_setup.mdx @@ -1,230 +1,230 @@ ---- -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.mdx). - -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). Upon startup the user will be presented with a page that -shows the End-User License Agreement. This page will be visible each -time the UGV is restarted but only on the first navigation to the page. -The EULA should be reviewed prior to using the system. - -## 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.mdx) 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). - - - Overview of how to send missions using the Map mode. - - - Overview of how to send missions using the Waypoint mode. - -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. +--- +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.mdx). + +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). Upon startup the user will be presented with a page that +shows the End-User License Agreement. This page will be visible each +time the UGV is restarted but only on the first navigation to the page. +The EULA should be reviewed prior to using the system. + +## 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.mdx) 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). + + - Overview of how to send missions using the Map mode. + + - Overview of how to send missions using the Waypoint mode. + +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.12.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/terminal_interface.mdx index aeedd85fd..662608d6c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/terminal_interface.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/terminal_interface.mdx @@ -1,244 +1,244 @@ ---- -title: Command Line Interface -sidebar_label: Command Line Interface -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -By default, the OutdoorNav Software begins automatically when the system -is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), -the set of commands that can be used by developers who are debugging -the system or who want more precise control for managing the OutdoorNav -software. - -## 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 separate OutdoorNav Computer, -first `ssh` to the UGV using the details provided in the UGV user -manual. Then, if a separate OutdoorNav Computer exists, you can -connect to it by running: - -``` bash -ssh administrator@192.168.131.5 -``` - -## OutdoorNav CLI Installation - -The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not -been installed on your system, it can be installed by running the following -on the OutdoorNav Computer: - -```bash -sudo apt-get install python3-onav-cli -``` - -:::note - -The command above requires that the Clearpath Package Server has been -configured on your OutdoorNav Computer. This is pre-configured on -Clearpath robots. Refer to details on the -[Clearpath Package Server](http://packages.clearpathrobotics.com/) if -this is not configured on your computer. - -::: - -## Listing the OutdoorNav CLI Commands and Getting Help - -To list all of the CLI commands, run the following on the OutdoorNav Computer: - -```bash -onav help -``` - -The CLI commands are: - -- `install`: Download and configure OutdoorNav -- `key`: Get, set, or delete your OutdoorNav license key -- `download`: Download OutdoorNav, but do not configure it -- `configure`: (Re)configure OutdoorNav -- `upgrade`: Upgrade OutdoorNav to the latest vesion -- `uninstall`: Uninstall OutdoorNav -- `depends`: Verify and install dependencies -- `start`: Start OutdoorNav -- `stop`: Stop OutdoorNav -- `status`: Check the status of OutdoorNav -- `logs`: View OutdoorNav logs -- `versions`: Print versions available to install -- `help`: Show available commands - -To get help on an individual command, use the `-h` option. For example, to -get help on the `install` command, run `onav install -h`: - -``` -usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION - -positional arguments: - VERSION The OutdoorNav version to install (e.g. 0.11.0) - -optional arguments: - -h, --help show this help message and exit - -k KEY, --key KEY Your OutdoorNav installation key - -b, --backpack Configure in backpack/bridged mode - -c, --clean Clean any configurations from a prior installation -``` - -## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} - -On UGV startup, all the sensors, the user interface, as well as the -autonomy software are set to start automatically. When debugging or when -greater control is desired, the CLI can be used to start and stop -the OutdoorNav software, in whole or in part. - -To see the current status of OutdoorNav software, run: - -```bash -onav status -``` - -To start the OutdoorNav software if it is not running, use the following command, -which starts the latest version of the software by default: - -```bash -onav start -``` - -To stop the OutdoorNav software, run: - -```bash -onav stop -``` - -## Stopping and Restarting the Autonomy Software Only - -To use the UGV without the autonomy software, use the following -command to stop the nodes and prevent them from automatic startup: - -``` bash -onav stop -s autonomy -``` - -The autonomy software can be restarted by running: - -``` bash -onav start -s autonomy -``` - -## 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 -onav stop -s sensors -``` - -:::note - -This command will only disable the drivers for the sensors that are started -by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, -and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense -cameras, 2D Lidars). - -::: - -The sensors software can be restarted by running: - -``` -onav start -s sensors -``` - -## Accessing the OutdoorNav Software Logs - -To check the logs of the OutdoorNav software, use the `onav logs` command -with the appropriate service. For example, to view the logs for the sensors -service, run: - -```bash -onav logs sensors -``` - -## Installing the OutdoorNav Software - -OutdoorNav is typically pre-installed on Clearpath robots, so most users should -not need to do a first-time installation of the software, though the process -is outlined below as a reference. - -As a first step, confirm that the robot has internet access. For example, confirm -that the following command is successful: - -``` -ping 8.8.8.8 -``` - -Second, the required dependencies need to be installed by running: - -```bash -onav depends -``` - -Third, a key needs to be added onto the robot to enable the installation -process. Contact [Clearpath Support](../support) if you did not receive your key. -To add your key, run the following, replacing `` with the actual value: - -```bash -onav key -``` - -Fourth, list the versions available for installation by running: - -```bash -onav versions -``` - -Fifth, install the OutdoorNav software for the desired version (typically the -newest version), by running the following, replacing `` with -the version to be installed: - -```bash -onav install -``` - -When prompted, trigger the reboot. - -Finally, following the reboot, run the following command to start the OutdoorNav -software. This will only be required the first time after installation. - -```bash -onav start -``` - -## Upgrading the OutdoorNav Software - -After receiving a notice that a new version of the OutdoorNav Software is -available, use the `onav upgrade` command with the appropriate version. -For example, to upgrade to the newest avialbel version that you are eligible -to receive, run the following command: - -``` -onav upgrade -``` - -:::note - -The upgrade requires internet access to download the new software. -Confirm that the OutdoorNav Computer has internet access by running a command -such as: - -``` -ping 8.8.8.8 -``` - -::: - -## Uninstalling Old Versions of OutdoorNav Software - -If old versions of OutdoorNav software are no longer being used, they can -be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 -run: - -``` -onav uninstall 0.11.0 +--- +title: Command Line Interface +sidebar_label: Command Line Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +By default, the OutdoorNav Software begins automatically when the system +is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), +the set of commands that can be used by developers who are debugging +the system or who want more precise control for managing the OutdoorNav +software. + +## 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 separate OutdoorNav Computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. Then, if a separate OutdoorNav Computer exists, you can +connect to it by running: + +``` bash +ssh administrator@192.168.131.5 +``` + +## OutdoorNav CLI Installation + +The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not +been installed on your system, it can be installed by running the following +on the OutdoorNav Computer: + +```bash +sudo apt-get install python3-onav-cli +``` + +:::note + +The command above requires that the Clearpath Package Server has been +configured on your OutdoorNav Computer. This is pre-configured on +Clearpath robots. Refer to details on the +[Clearpath Package Server](http://packages.clearpathrobotics.com/) if +this is not configured on your computer. + +::: + +## Listing the OutdoorNav CLI Commands and Getting Help + +To list all of the CLI commands, run the following on the OutdoorNav Computer: + +```bash +onav help +``` + +The CLI commands are: + +- `install`: Download and configure OutdoorNav +- `key`: Get, set, or delete your OutdoorNav license key +- `download`: Download OutdoorNav, but do not configure it +- `configure`: (Re)configure OutdoorNav +- `upgrade`: Upgrade OutdoorNav to the latest vesion +- `uninstall`: Uninstall OutdoorNav +- `depends`: Verify and install dependencies +- `start`: Start OutdoorNav +- `stop`: Stop OutdoorNav +- `status`: Check the status of OutdoorNav +- `logs`: View OutdoorNav logs +- `versions`: Print versions available to install +- `help`: Show available commands + +To get help on an individual command, use the `-h` option. For example, to +get help on the `install` command, run `onav install -h`: + +``` +usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION + +positional arguments: + VERSION The OutdoorNav version to install (e.g. 0.11.0) + +optional arguments: + -h, --help show this help message and exit + -k KEY, --key KEY Your OutdoorNav installation key + -b, --backpack Configure in backpack/bridged mode + -c, --clean Clean any configurations from a prior installation +``` + +## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} + +On UGV startup, all the sensors, the user interface, as well as the +autonomy software are set to start automatically. When debugging or when +greater control is desired, the CLI can be used to start and stop +the OutdoorNav software, in whole or in part. + +To see the current status of OutdoorNav software, run: + +```bash +onav status +``` + +To start the OutdoorNav software if it is not running, use the following command, +which starts the latest version of the software by default: + +```bash +onav start +``` + +To stop the OutdoorNav software, run: + +```bash +onav stop +``` + +## Stopping and Restarting the Autonomy Software Only + +To use the UGV without the autonomy software, use the following +command to stop the nodes and prevent them from automatic startup: + +``` bash +onav stop -s autonomy +``` + +The autonomy software can be restarted by running: + +``` bash +onav start -s autonomy +``` + +## 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 +onav stop -s sensors +``` + +:::note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars). + +::: + +The sensors software can be restarted by running: + +``` +onav start -s sensors +``` + +## Accessing the OutdoorNav Software Logs + +To check the logs of the OutdoorNav software, use the `onav logs` command +with the appropriate service. For example, to view the logs for the sensors +service, run: + +```bash +onav logs sensors +``` + +## Installing the OutdoorNav Software + +OutdoorNav is typically pre-installed on Clearpath robots, so most users should +not need to do a first-time installation of the software, though the process +is outlined below as a reference. + +As a first step, confirm that the robot has internet access. For example, confirm +that the following command is successful: + +``` +ping 8.8.8.8 +``` + +Second, the required dependencies need to be installed by running: + +```bash +onav depends +``` + +Third, a key needs to be added onto the robot to enable the installation +process. Contact [Clearpath Support](../support) if you did not receive your key. +To add your key, run the following, replacing `` with the actual value: + +```bash +onav key +``` + +Fourth, list the versions available for installation by running: + +```bash +onav versions +``` + +Fifth, install the OutdoorNav software for the desired version (typically the +newest version), by running the following, replacing `` with +the version to be installed: + +```bash +onav install +``` + +When prompted, trigger the reboot. + +Finally, following the reboot, run the following command to start the OutdoorNav +software. This will only be required the first time after installation. + +```bash +onav start +``` + +## Upgrading the OutdoorNav Software + +After receiving a notice that a new version of the OutdoorNav Software is +available, use the `onav upgrade` command with the appropriate version. +For example, to upgrade to the newest avialbel version that you are eligible +to receive, run the following command: + +``` +onav upgrade +``` + +:::note + +The upgrade requires internet access to download the new software. +Confirm that the OutdoorNav Computer has internet access by running a command +such as: + +``` +ping 8.8.8.8 +``` + +::: + +## Uninstalling Old Versions of OutdoorNav Software + +If old versions of OutdoorNav software are no longer being used, they can +be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 +run: + +``` +onav uninstall 0.11.0 ``` \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx index 72327dbc3..ab05b15f1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx @@ -1,80 +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
-
-
- -::: +--- +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.12.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/index.mdx @@ -1,18 +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 +--- +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.12.0/integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/_category_.json index e9e0ff1dd..adbe22cba 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix A: UGV Integration Requirements", - "position": 12 +{ + "label": "Appendix A: UGV Integration Requirements", + "position": 12 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json index 75ebaf1b4..7950de6b7 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Hardware Kit Installation", - "position": 2 -} +{ + "label": "Hardware Kit Installation", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx index 00cf8a071..72d78ae31 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx @@ -1,34 +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. | +--- +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.12.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/interface_control_requirements.mdx index a603485bb..d9906ed65 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/interface_control_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/interface_control_requirements.mdx @@ -1,119 +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.mdx#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). +--- +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.mdx#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.12.0/integration_requirements/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/software_integration_instructions.mdx index 2184246fd..64f7fee68 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/software_integration_instructions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/software_integration_instructions.mdx @@ -1,132 +1,132 @@ ---- -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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: -- [Interface Control Checklist](interface_control_requirements.mdx) - -All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. - -### Install Command-line Interface Tool (CLI) {#install-cli} - - -{` -sudo apt update -sudo apt install python3-onav-cli -`} - - -### Install OutdoorNav - - -{` -onav install -k -`} - - -where `license_key` is the license key that you have been assigned and `VERSION` is the version -of the software to be installed (eg. 0.11.0). Only one license key can be used per UGV. - -:::note - -In some cases, including first-time installations, a reboot is required after installing -the required dependencies. In this case, it is necessary to re-run -the `onav install -k ` command again following the reboot to complete -the installation. - -::: - -### 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 /opt/onav//config -nano autonomy.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/Stop the OutdoorNav - -To start up the OutdoorNav software run: - - -{` -onav start -`} - - -If you wish to start individual profiles or services, run `onav start -h` to see available profiles/services. - -To stop the OutdoorNav software run: - - -{` -onav stop -`} - - -For more information and available ONAV CLI commands, see the [Terminal Interface](../getting_started/terminal_interface.mdx) section. - -### 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 - -rostopic echo -n 1 /localization/odom - -# GNSS units -rostopic echo /sensors/gps_/fix - -# IMU (if included) -rostopic echo -n 1 /sensors/imu_/data - -# 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 --noarr -rostopic echo -n 1 /sensors/stereo_0/image --noarr -rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw --noarr - -# Realsense D435 Rear (if included) -rostopic echo -n 1 /sensors/stereo_1/pointcloud --noarr -rostopic echo -n 1 /sensors/stereo_1/image --noarr -rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw --noarr -``` - -\ 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.mdx) to start using the software. +--- +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](interface_control_requirements.mdx) + +All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. + +### Install Command-line Interface Tool (CLI) {#install-cli} + + +{` +sudo apt update +sudo apt install python3-onav-cli +`} + + +### Install OutdoorNav + + +{` +onav install -k +`} + + +where `license_key` is the license key that you have been assigned and `VERSION` is the version +of the software to be installed (eg. 0.11.0). Only one license key can be used per UGV. + +:::note + +In some cases, including first-time installations, a reboot is required after installing +the required dependencies. In this case, it is necessary to re-run +the `onav install -k ` command again following the reboot to complete +the installation. + +::: + +### 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 /opt/onav//config +nano autonomy.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/Stop the OutdoorNav + +To start up the OutdoorNav software run: + + +{` +onav start +`} + + +If you wish to start individual profiles or services, run `onav start -h` to see available profiles/services. + +To stop the OutdoorNav software run: + + +{` +onav stop +`} + + +For more information and available ONAV CLI commands, see the [Terminal Interface](../getting_started/terminal_interface.mdx) section. + +### 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 + +rostopic echo -n 1 /localization/odom + +# GNSS units +rostopic echo /sensors/gps_/fix + +# IMU (if included) +rostopic echo -n 1 /sensors/imu_/data + +# 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 --noarr +rostopic echo -n 1 /sensors/stereo_0/image --noarr +rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw --noarr + +# Realsense D435 Rear (if included) +rostopic echo -n 1 /sensors/stereo_1/pointcloud --noarr +rostopic echo -n 1 /sensors/stereo_1/image --noarr +rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw --noarr +``` + +\ 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.mdx) to start using the software. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx index b6abe65eb..0883eba88 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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.12.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_introduction.mdx index 83bfa1d64..4f3f1bf7d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_introduction.mdx @@ -1,93 +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 +--- +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.12.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_operating_conditions.mdx index c02228aa5..6e0b17a54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_operating_conditions.mdx @@ -1,177 +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. - +--- +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.12.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_scope.mdx index ba0092f1c..f1a326070 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_scope.mdx @@ -1,15 +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). - - +--- +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.12.0/release_notes.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/release_notes.mdx index 009c126a7..2da17ffe0 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/release_notes.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/release_notes.mdx @@ -1,316 +1,316 @@ ---- -title: Release Notes -sidebar_label: Release Notes -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -import Style from '/assets/css/changelog.css'; - -
- -## 0.12.0 - -### New Features -- Modified mission planning modes. Now includes: - - Map mode (which allows the user to create maps of an environment - and send mission using said map) - - Waypoint mode (which allows the user to create more direct mission - by placing waypoints directly on the Aerial overlay) -- Added an Assisted teleoperation feature to prevent robot collisions with - obstacles when it is being teleoperated. -- Added the upgrade command to the CLI tool. Customers can now upgrade their - software as long as they are eligible to be upgraded to the newest version. - Please contact [Support](./support.mdx) for more information. -- New visualization of status command in CLI tool -- Added a filebrowser extension to access/view the robot filesystem for easier - media access - -### API Features - -- Added new message definitions and service calls for the storage/editing of Maps - -### Bug Fixes - -- 1973: Fixed python “machineid” error during installation -- 2089: Fixed the no serial number on /platform/id topic -- 2169: Fixed the mission manager/scheduler still requesting during Teleop only mode - -### Known Issues - -- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint -- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect -- 2332: upgrading from 0.11 to 0.12.0 in teleoperation only configuration and Q62 - installed causes duplication of axis driver. Please contact [Support](./support.mdx) - if you run into this issue. -- 2344: Autonomy not going down during low-power mode -- 2360: Waypoint/Map modes use different mouse click to open context menus - -## 0.11.0 - -### New Features - -- Command Line Tool used to install/update/manage OutdoorNav -- Added the End User License Agreement to the UI upon start up -- Light and PTZ Pan/Tilt controls can now be mapped to a controller -- OutdoorNav/IndoorNav switch over improvements -- Can now place waypoints at UGV location via shortcut key (Shift + X) - -### API Features - -- Can now delete multiple mission objects (missions, waypoints, tasks) in single call -- Stack Light can now be manually overridden/muted -- Added ability to import single missions to the robot - -### Bug Fixes - -- 1688: Move PTZ task only ever uses the first PTZ camera's positions -- 2011: Filter false "Move PTZ Failure" notifications when moving PTZ camera - -### Known Issues - -- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint -- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect - -## 0.10.0 - -### New Features - -- Added the ability to start mission from a specific Waypoint -- Added the ability to resume mission from current location -- Added the option to include on-start and on-stop tasks to a Mission -- Added the option to continue a Mission if a Task should fail -- Full release of the API examples repository to the public (link API examples top level page) - -### API Features - -- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx)) - - Mission.action added from_start and *start_waypoint_uuid* fields - - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields -- Message Definition changes - - Mission.msg: added an array of on_start and and array of on_stop tasks fields - - Task.msg: added a boolean allow_failure field -- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) -- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features - -### Bug Fixes - -- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location -- 1764: Importing missions with docking tasks fails to bring in docks - -### Known Issues - -- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint -- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect - -## 0.9.0 - -### New Features - -- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) -- 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.mdx)) -- 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.mdx)): - - /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.mdx)) - - 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.mdx#localizationstatus)). -- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#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_waypoint_mode.mdx#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.mdx) - 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. - +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Style from '/assets/css/changelog.css'; + +
+ +## 0.12.0 + +### New Features +- Modified mission planning modes. Now includes: + - Map mode (which allows the user to create maps of an environment + and send mission using said map) + - Waypoint mode (which allows the user to create more direct mission + by placing waypoints directly on the Aerial overlay) +- Added an Assisted teleoperation feature to prevent robot collisions with + obstacles when it is being teleoperated. +- Added the upgrade command to the CLI tool. Customers can now upgrade their + software as long as they are eligible to be upgraded to the newest version. + Please contact [Support](./support.mdx) for more information. +- New visualization of status command in CLI tool +- Added a filebrowser extension to access/view the robot filesystem for easier + media access + +### API Features + +- Added new message definitions and service calls for the storage/editing of Maps + +### Bug Fixes + +- 1973: Fixed python “machineid” error during installation +- 2089: Fixed the no serial number on /platform/id topic +- 2169: Fixed the mission manager/scheduler still requesting during Teleop only mode + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect +- 2332: upgrading from 0.11 to 0.12.0 in teleoperation only configuration and Q62 + installed causes duplication of axis driver. Please contact [Support](./support.mdx) + if you run into this issue. +- 2344: Autonomy not going down during low-power mode +- 2360: Waypoint/Map modes use different mouse click to open context menus + +## 0.11.0 + +### New Features + +- Command Line Tool used to install/update/manage OutdoorNav +- Added the End User License Agreement to the UI upon start up +- Light and PTZ Pan/Tilt controls can now be mapped to a controller +- OutdoorNav/IndoorNav switch over improvements +- Can now place waypoints at UGV location via shortcut key (Shift + X) + +### API Features + +- Can now delete multiple mission objects (missions, waypoints, tasks) in single call +- Stack Light can now be manually overridden/muted +- Added ability to import single missions to the robot + +### Bug Fixes + +- 1688: Move PTZ task only ever uses the first PTZ camera's positions +- 2011: Filter false "Move PTZ Failure" notifications when moving PTZ camera + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.10.0 + +### New Features + +- Added the ability to start mission from a specific Waypoint +- Added the ability to resume mission from current location +- Added the option to include on-start and on-stop tasks to a Mission +- Added the option to continue a Mission if a Task should fail +- Full release of the API examples repository to the public (link API examples top level page) + +### API Features + +- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx)) + - Mission.action added from_start and *start_waypoint_uuid* fields + - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields +- Message Definition changes + - Mission.msg: added an array of on_start and and array of on_stop tasks fields + - Task.msg: added a boolean allow_failure field +- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) +- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features + +### Bug Fixes + +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location +- 1764: Importing missions with docking tasks fails to bring in docks + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) +- 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.mdx)) +- 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.mdx)): + - /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.mdx)) + - 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.mdx#localizationstatus)). +- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#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_waypoint_mode.mdx#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.mdx) + 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. +
\ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx @@ -1,144 +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. +--- +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.12.0/simulation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/simulation.mdx index 44cff5f7a..86043ef71 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/simulation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/simulation.mdx @@ -1,20 +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 +--- +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.12.0/support.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/support.mdx index 9212d99f2..4da40f82f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/support.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/support.mdx @@ -1,11 +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"; - +--- +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.12.0/web_user_interface/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/_category_.json index a07ca158b..31b780353 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Web User Interface", - "position": 6 -} +{ + "label": "Web User Interface", + "position": 6 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx index 1447f480e..927755c44 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx @@ -1,55 +1,55 @@ ---- -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.mdx) 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. **Error/Warning Bar:** A bar along the top of the page reporting - the error or warning status of the Assisted Teleoperation feature. -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. Four fixed direction buttons are - now present to move the UGV in purely forward/reverse directions or - clockwise/counter-clockwise. Finally, we overlay an obstacle map - on top of the joystick, representing obstacle distances from the - UGV. -3. **Speedometer:** An indicator of the UGV's current linear speed. -4. **Sensitivity Scale:** A UGV-specific scale that controls the - maximum allowable UGV velocities at each level. The default maximum - linear velocity is 1.0 meters per second and the maximum angular - velocity is 0.5 radians per second. These can be changed in the - [General Settings](./ui_overview.mdx#config-general-settings) page. - The scale levels are 100%, 80%, 50% and 20%, with the default set - to 80%. -5. **Teleop Assist Toggle:** The "Teleop Assist" toggle can be used to - enable/disable the Assisted Teleoperation feature. - -## 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 +--- +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.mdx) 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. **Error/Warning Bar:** A bar along the top of the page reporting + the error or warning status of the Assisted Teleoperation feature. +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. Four fixed direction buttons are + now present to move the UGV in purely forward/reverse directions or + clockwise/counter-clockwise. Finally, we overlay an obstacle map + on top of the joystick, representing obstacle distances from the + UGV. +3. **Speedometer:** An indicator of the UGV's current linear speed. +4. **Sensitivity Scale:** A UGV-specific scale that controls the + maximum allowable UGV velocities at each level. The default maximum + linear velocity is 1.0 meters per second and the maximum angular + velocity is 0.5 radians per second. These can be changed in the + [General Settings](./ui_overview.mdx#config-general-settings) page. + The scale levels are 100%, 80%, 50% and 20%, with the default set + to 80%. +5. **Teleop Assist Toggle:** The "Teleop Assist" toggle can be used to + enable/disable the Assisted Teleoperation feature. + +## 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.12.0/web_user_interface/ui_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_overview.mdx index a1ddd5b61..4e1367b09 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_overview.mdx @@ -1,623 +1,623 @@ ---- -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, Help, and File pages. The User - 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. **Stack Light:** If a Stack Light is configured for the UGV its current status - will show here. - -11. **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. - -12. **Local Docking/Undocking:** The local docking/undocking buttons used - to dock/undock the UGV. The UGV must have it's charging adaptor facing the dock - when performing the local dock action. - -13. **Lights Control:** If the UGV is equipped with software controllable lights they can be - controlled through a simple drop down button as well as relevant hotkeys, - depending on the configuration. - -14. **Record Audio:** If the UGV is equipped with a microphone the user - can start/stop recording manually by clicking this icon. - -15. **Mission Execution Buttons:** These buttons allow users to Start, Pause and Stop an - autonomous 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) - -## 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 features have been - set on the map. -3. **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. -4. **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. -5. **Dock:** If a dock is configured for the UGV it will appear on the map in - this format. When in Waypoint mode the Docks pre-dock radius will appear as - a circle around the dock when in Edit Mission mode. -6. **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. - -## 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 {#config-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. - -#### Joystick Max Speeds - -The Operator can choose to set the Maximum Linear Speed and the Maximum Angular Speed that the teleoperation will use. These are limited to the -maximum speeds of the UGV itself. - -### Aerial Overlay Settings - -
-
- -
Aerial Overlay settings
-
-
- -To access the Aerial Overlay Settings: Menu → Settings → Aerial Overlay: - -1. **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. - -### 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 - http://localhost:8000/{z}/{x}/{-y}.png. 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. - -## Autonomous Features - -There are presently 2 autonomous modes that the UGV can be used in, [Waypoint Mode](ui_waypoint_mode.mdx) and [Map Mode](ui_map_mode.mdx). -While each mode leverages different features, some are shared and are elaborated on here. - -:::note - -Some objects that appear on the overlay have context menus associated with them. However there is a known issue related to opening this context menu -between Autonomy modes. At present to open a context menu in the Waypoint Mode, left click the object, and when in Map Mode right click the object. -This issue will be reconciled in a future release. - -::: - -### Tasks - -When running a mission autonomously the user can assign tasks to various events. These tasks, along with their decoration icons, are found below: - -- Dock Robot: - Will dock the UGV to begin charging the UGV's - battery. There are 3 kinds of docking that can be used; Network, Radius and Local. - 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.mdx#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 /opt/onav/saved_files/media/... directory and can be retrieved using a tool - such as FileZilla or by navigating to the Files section in the hamburger menu. - - 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 /opt/onav/saved_files/media/... folder and can be retrieved - using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. - - Settings: Select which camera the recording will come from. - -- Start/Stop Audio Recording: - Will start/stop recording audio using one of the - UGV microphone(s) to the /opt/onav/saved_files/media/... folder and can be retrieved - using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. - - Settings: Select which microphone 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 or as a start Mission Task; - that way, the UGV will automatically continue towards its next - Waypoint once undocked. - - :::note - - If the users places the Undock Task in the start Mission event for a Waypoint Mission the first Waypoint should be - approximately 2-3 meters behind the UGV's docked position. - - ::: - -- 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.mdx) section - for details on how to develop custom tasks for your application. - - -:::note - -If a Waypoint/Goalpoint has more than one task assigned to it, the icon will -be replaced with a sheet of paper icon like so: - -::: - -### Autonomous Docking - -
-
- -
Dock Icon
-
-
- -### Docking The UGV - -To dock the UGV autonomously the user can use the following methods: - -#### Dock (Local) - -If there is a valid dock within its driveable range the UGV will attempt to dock. -This docking method can be done by selecting the Dock button in the bottom bar or by adding a -"Dock Robot (Local)" task to either an event or a mission point. - -#### Dock (Radius) - -If the UGV is within the specified docks radius the UGV will first navigate to a predock location -and then attempt to dock. When in Waypoint Mode a user can dock via this method as follows: - -- Enable the "Edit Mission" toggle. -- Maneuver the UGV so that is somewhere within the dock's radius. -- Click the dock that the UGV will be docking at and select "Dock Robot Here". - -This docking method can also be accomplished by adding a "Dock Robot (Radius)" task to either -an event or a mission point. A dock will need to be provided for the task to function which can be done -through the task settings modal. - -#### Dock (Network) - -:::note - -This mode is only available in [Map mode](ui_map_mode.mdx). Please see the Map mode page for further -details on map generation. - -::: - -If the UGV and the dock are within a map's driveable area the UGV will first navigate to a -predock location based on the map paths available. A user can dock manually using this method as follows: - -- Enable the "Edit Map" toggle. -- Maneuver the UGV so that is within the driveable range of the map. -- Ensure the dock is within the driveable range of the map. -- Right click the dock that the UGV will be docking at and select "Dock Robot Here". - -This docking method can also be accomplished by adding a "Dock Robot (Network)" task to either an -event or a mission point. A dock will need to be provided for the task to function which can be done -through the task settings modal. - -### Undocking The UGV - -To undock the UGV autonomously, the user can apply a "Undock Robot" task to a mission event or -point. The user can also click the Undock button in the bottom bar's left hand corner. - -### 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-dock 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. - -## Switching to IndoorNav - -If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. -To switch between the modes in OutdoorNav select the 'Navigation Mode' option found -in the hamburger menu. This will navigate to a page that shows the current mode and -provides an option to switch. When in IndoorNav mode the user may navigate to -the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen -below. - -
-
- -
-
- -:::note - -When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will -disable OutdoorNav UI features related to Autonomy but will still allow users the -option to view camera streams. - +--- +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, Help, and File pages. The User + 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. **Stack Light:** If a Stack Light is configured for the UGV its current status + will show here. + +11. **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. + +12. **Local Docking/Undocking:** The local docking/undocking buttons used + to dock/undock the UGV. The UGV must have it's charging adaptor facing the dock + when performing the local dock action. + +13. **Lights Control:** If the UGV is equipped with software controllable lights they can be + controlled through a simple drop down button as well as relevant hotkeys, + depending on the configuration. + +14. **Record Audio:** If the UGV is equipped with a microphone the user + can start/stop recording manually by clicking this icon. + +15. **Mission Execution Buttons:** These buttons allow users to Start, Pause and Stop an + autonomous 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) + +## 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 features have been + set on the map. +3. **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. +4. **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. +5. **Dock:** If a dock is configured for the UGV it will appear on the map in + this format. When in Waypoint mode the Docks pre-dock radius will appear as + a circle around the dock when in Edit Mission mode. +6. **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. + +## 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 {#config-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. + +#### Joystick Max Speeds + +The Operator can choose to set the Maximum Linear Speed and the Maximum Angular Speed that the teleoperation will use. These are limited to the +maximum speeds of the UGV itself. + +### Aerial Overlay Settings + +
+
+ +
Aerial Overlay settings
+
+
+ +To access the Aerial Overlay Settings: Menu → Settings → Aerial Overlay: + +1. **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. + +### 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 + http://localhost:8000/{z}/{x}/{-y}.png. 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. + +## Autonomous Features + +There are presently 2 autonomous modes that the UGV can be used in, [Waypoint Mode](ui_waypoint_mode.mdx) and [Map Mode](ui_map_mode.mdx). +While each mode leverages different features, some are shared and are elaborated on here. + +:::note + +Some objects that appear on the overlay have context menus associated with them. However there is a known issue related to opening this context menu +between Autonomy modes. At present to open a context menu in the Waypoint Mode, left click the object, and when in Map Mode right click the object. +This issue will be reconciled in a future release. + +::: + +### Tasks + +When running a mission autonomously the user can assign tasks to various events. These tasks, along with their decoration icons, are found below: + +- Dock Robot: + Will dock the UGV to begin charging the UGV's + battery. There are 3 kinds of docking that can be used; Network, Radius and Local. + 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.mdx#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 /opt/onav/saved_files/media/... directory and can be retrieved using a tool + such as FileZilla or by navigating to the Files section in the hamburger menu. + + 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 /opt/onav/saved_files/media/... folder and can be retrieved + using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which camera the recording will come from. + +- Start/Stop Audio Recording: + Will start/stop recording audio using one of the + UGV microphone(s) to the /opt/onav/saved_files/media/... folder and can be retrieved + using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which microphone 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 or as a start Mission Task; + that way, the UGV will automatically continue towards its next + Waypoint once undocked. + + :::note + + If the users places the Undock Task in the start Mission event for a Waypoint Mission the first Waypoint should be + approximately 2-3 meters behind the UGV's docked position. + + ::: + +- 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.mdx) section + for details on how to develop custom tasks for your application. + + +:::note + +If a Waypoint/Goalpoint has more than one task assigned to it, the icon will +be replaced with a sheet of paper icon like so: + +::: + +### Autonomous Docking + +
+
+ +
Dock Icon
+
+
+ +### Docking The UGV + +To dock the UGV autonomously the user can use the following methods: + +#### Dock (Local) + +If there is a valid dock within its driveable range the UGV will attempt to dock. +This docking method can be done by selecting the Dock button in the bottom bar or by adding a +"Dock Robot (Local)" task to either an event or a mission point. + +#### Dock (Radius) + +If the UGV is within the specified docks radius the UGV will first navigate to a predock location +and then attempt to dock. When in Waypoint Mode a user can dock via this method as follows: + +- Enable the "Edit Mission" toggle. +- Maneuver the UGV so that is somewhere within the dock's radius. +- Click the dock that the UGV will be docking at and select "Dock Robot Here". + +This docking method can also be accomplished by adding a "Dock Robot (Radius)" task to either +an event or a mission point. A dock will need to be provided for the task to function which can be done +through the task settings modal. + +#### Dock (Network) + +:::note + +This mode is only available in [Map mode](ui_map_mode.mdx). Please see the Map mode page for further +details on map generation. + +::: + +If the UGV and the dock are within a map's driveable area the UGV will first navigate to a +predock location based on the map paths available. A user can dock manually using this method as follows: + +- Enable the "Edit Map" toggle. +- Maneuver the UGV so that is within the driveable range of the map. +- Ensure the dock is within the driveable range of the map. +- Right click the dock that the UGV will be docking at and select "Dock Robot Here". + +This docking method can also be accomplished by adding a "Dock Robot (Network)" task to either an +event or a mission point. A dock will need to be provided for the task to function which can be done +through the task settings modal. + +### Undocking The UGV + +To undock the UGV autonomously, the user can apply a "Undock Robot" task to a mission event or +point. The user can also click the Undock button in the bottom bar's left hand corner. + +### 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-dock 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. + +## Switching to IndoorNav + +If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. +To switch between the modes in OutdoorNav select the 'Navigation Mode' option found +in the hamburger menu. This will navigate to a page that shows the current mode and +provides an option to switch. When in IndoorNav mode the user may navigate to +the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen +below. + +
+
+ +
+
+ +:::note + +When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will +disable OutdoorNav UI features related to Autonomy but will still allow users the +option to view camera streams. + ::: \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx index daf67ed9e..e092a4e7f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx @@ -1,271 +1,271 @@ ---- -title: Web UI Waypoint Mode -sidebar_label: Web UI Waypoint 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.mdx) 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. - -## 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. The user can -also rename the mission and apply Tasks to when the Mission starts and stops. - -### Rename Mission - -To rename the Mission click the Mission name as it appears in the upper left -hand corner. This should change the text into an input box that can then be -modified. Press enter/click aside to save the change. - -### Mission Tasks - -A Mission can have Tasks assigned to when it starts and when it stops. These -Tasks will run in the order they are listed in and will always run whenever the Mission -starts or stops. - -### 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). Waypoints in the table will also have a small icon to indicate - if tasks are assigned to the Waypoint accordingly. - -4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is - checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. - If its not checked, the Mission will become cancelled upon the Task's failure. -5. 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. - -:::note - -Waypoints that have a heading or tolerance assigned to them will show a different colour -on their settings icon. - -::: - -
-
- -
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 - -There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently -selected Mission by clicking the "Play" button . -Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button -to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by -obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on -"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. - -
-
- -
Starting from a specific Waypoint
-
-
- -When the Mission has been started the Play button will turn green, regardless of how it has been started. - -### 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. - +--- +title: Web UI Waypoint Mode +sidebar_label: Web UI Waypoint 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.mdx) 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. + +## 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. The user can +also rename the mission and apply Tasks to when the Mission starts and stops. + +### Rename Mission + +To rename the Mission click the Mission name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Mission Tasks + +A Mission can have Tasks assigned to when it starts and when it stops. These +Tasks will run in the order they are listed in and will always run whenever the Mission +starts or stops. + +### 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). Waypoints in the table will also have a small icon to indicate + if tasks are assigned to the Waypoint accordingly. + +4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is + checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. + If its not checked, the Mission will become cancelled upon the Task's failure. +5. 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. + +:::note + +Waypoints that have a heading or tolerance assigned to them will show a different colour +on their settings icon. + +::: + +
+
+ +
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 + +There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently +selected Mission by clicking the "Play" button . +Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button +to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by +obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on +"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. + +
+
+ +
Starting from a specific Waypoint
+
+
+ +When the Mission has been started the Play button will turn green, regardless of how it has been started. + +### 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. + diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_endpoints/api_endpoints.mdx index c65c4150b..e1169e6e2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_endpoints/api_endpoints.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_endpoints/api_endpoints.mdx @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/api_examples.mdx index 333bd1355..eb556d30a 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/api_examples.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/api_examples.mdx @@ -1,21 +1,21 @@ ---- -title: API Examples -sidebar_label: API Examples -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -The OutdoorNav API examples are now available and accesible to everyone. A -[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along -with some example scripts are available to build and use for our application. - -A few examples scripts follow with detailed explanations: - -- [Execute Mission from File](./mission_from_file.mdx) -- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) -- [Status Monitoring](./monitor_status.mdx) -- [Network of Paths](./network_of_paths.mdx) - -The documentation for the Python API library can be built following the -instructions in the above linked GitHub repository. +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav API examples are now available and accesible to everyone. A +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +with some example scripts are available to build and use for our application. + +A few examples scripts follow with detailed explanations: + +- [Execute Mission from File](./mission_from_file.mdx) +- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) +- [Status Monitoring](./monitor_status.mdx) +- [Network of Paths](./network_of_paths.mdx) + +The documentation for the Python API library can be built following the +instructions in the above linked GitHub repository. diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_from_file.mdx index eff0f7686..0abb4ea90 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_from_file.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_from_file.mdx @@ -1,210 +1,210 @@ ---- -title: Mission from YAML File -sidebar_label: Mission from YAML File -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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" -``` +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.13.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_with_custom_tasks.mdx index 30ec477ea..af8335aa6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_with_custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/mission_with_custom_tasks.mdx @@ -1,233 +1,233 @@ ---- -title: Mission with Custom Tasks -sidebar_label: Mission with Custom Tasks -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -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.mdx) 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. - - +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +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.mdx) 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.13.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/monitor_status.mdx index 077a9fcf5..a6fb416c5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/monitor_status.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_examples/monitor_status.mdx @@ -1,152 +1,152 @@ ---- -title: Monitor Status -sidebar_label: Monitor Status -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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. +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.13.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_overview.mdx index d9c6d616e..1bcb0ad92 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/api/api_overview.mdx @@ -1,63 +1,63 @@ ---- -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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions -- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) - that are used for creating, deleting, and modifying OutdoorNav Mission Schedules -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions +- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) + that are used for creating, deleting, and modifying OutdoorNav Mission Schedules +- [Definitions](api_endpoints/definitions.mdx): 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.13.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/sensor_customization.mdx index 9d9f115aa..f2cce53a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/sensor_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/sensor_customization.mdx @@ -1,9 +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. +--- +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.13.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/_category_.json index d62e291a4..4b3e7b596 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index 516393373..0125d8ddc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -1,9 +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. +--- +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.13.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 4b90f6008..6b105ecb3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/footprint_tuning.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -1,9 +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. +--- +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.13.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_overview.mdx index 851df29b0..77fbabeb9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_overview.mdx @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/_category_.json index fb6592a90..0e2dc60a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/navigation_parameters.mdx index b88562a4b..d4a2b559d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/navigation_parameters.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -1,169 +1,169 @@ ---- -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 -/opt/onav//app/autonomy/params//navigation/controls_general.yaml -/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml -/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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. +--- +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 +/opt/onav//app/autonomy/params//navigation/controls_general.yaml +/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml +/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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.13.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/user_interface_customization.mdx index c67bca22a..1e7d39c97 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/user_interface_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/customized_tuning/user_interface_customization.mdx @@ -1,9 +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. +--- +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.13.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/features/_category_.json index 732c6cb78..3bf04f17d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/features/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/features/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav Features", - "position": 8 -} +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/features/custom_tasks.mdx index 5b1176997..056e3ff54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/features/custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/features/custom_tasks.mdx @@ -1,206 +1,206 @@ ---- -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 -**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* -is the currently running version of OutdoorNav. 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 -``` +--- +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 +**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* +is the currently running version of OutdoorNav. 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.13.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/features/navigation.mdx index d2e0284df..5b4dfa2df 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/features/navigation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/features/navigation.mdx @@ -1,38 +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 -`/opt/onav//config/autonomy.env` file, where *onav_version* -is the currently running version of OutdoorNav. 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 drive 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_waypoint_mode.mdx#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`).| +--- +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 +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. 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 drive 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_waypoint_mode.mdx#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.13.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/_category_.json index 8b4a486d9..9a9747ef6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/first_time_checklist.mdx index e7298e8ae..9044c8da1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/first_time_checklist.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/first_time_checklist.mdx @@ -1,114 +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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_waypoint_mode.mdx#mission-creation). - -### ☐ After creating a new mission, can you execute the mission? - -To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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_waypoint_mode.mdx#mission-creation). + +### ☐ After creating a new mission, can you execute the mission? + +To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#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.mdx#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.mdx#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.13.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/terminal_interface.mdx index aeedd85fd..662608d6c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/terminal_interface.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/terminal_interface.mdx @@ -1,244 +1,244 @@ ---- -title: Command Line Interface -sidebar_label: Command Line Interface -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -By default, the OutdoorNav Software begins automatically when the system -is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), -the set of commands that can be used by developers who are debugging -the system or who want more precise control for managing the OutdoorNav -software. - -## 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 separate OutdoorNav Computer, -first `ssh` to the UGV using the details provided in the UGV user -manual. Then, if a separate OutdoorNav Computer exists, you can -connect to it by running: - -``` bash -ssh administrator@192.168.131.5 -``` - -## OutdoorNav CLI Installation - -The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not -been installed on your system, it can be installed by running the following -on the OutdoorNav Computer: - -```bash -sudo apt-get install python3-onav-cli -``` - -:::note - -The command above requires that the Clearpath Package Server has been -configured on your OutdoorNav Computer. This is pre-configured on -Clearpath robots. Refer to details on the -[Clearpath Package Server](http://packages.clearpathrobotics.com/) if -this is not configured on your computer. - -::: - -## Listing the OutdoorNav CLI Commands and Getting Help - -To list all of the CLI commands, run the following on the OutdoorNav Computer: - -```bash -onav help -``` - -The CLI commands are: - -- `install`: Download and configure OutdoorNav -- `key`: Get, set, or delete your OutdoorNav license key -- `download`: Download OutdoorNav, but do not configure it -- `configure`: (Re)configure OutdoorNav -- `upgrade`: Upgrade OutdoorNav to the latest vesion -- `uninstall`: Uninstall OutdoorNav -- `depends`: Verify and install dependencies -- `start`: Start OutdoorNav -- `stop`: Stop OutdoorNav -- `status`: Check the status of OutdoorNav -- `logs`: View OutdoorNav logs -- `versions`: Print versions available to install -- `help`: Show available commands - -To get help on an individual command, use the `-h` option. For example, to -get help on the `install` command, run `onav install -h`: - -``` -usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION - -positional arguments: - VERSION The OutdoorNav version to install (e.g. 0.11.0) - -optional arguments: - -h, --help show this help message and exit - -k KEY, --key KEY Your OutdoorNav installation key - -b, --backpack Configure in backpack/bridged mode - -c, --clean Clean any configurations from a prior installation -``` - -## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} - -On UGV startup, all the sensors, the user interface, as well as the -autonomy software are set to start automatically. When debugging or when -greater control is desired, the CLI can be used to start and stop -the OutdoorNav software, in whole or in part. - -To see the current status of OutdoorNav software, run: - -```bash -onav status -``` - -To start the OutdoorNav software if it is not running, use the following command, -which starts the latest version of the software by default: - -```bash -onav start -``` - -To stop the OutdoorNav software, run: - -```bash -onav stop -``` - -## Stopping and Restarting the Autonomy Software Only - -To use the UGV without the autonomy software, use the following -command to stop the nodes and prevent them from automatic startup: - -``` bash -onav stop -s autonomy -``` - -The autonomy software can be restarted by running: - -``` bash -onav start -s autonomy -``` - -## 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 -onav stop -s sensors -``` - -:::note - -This command will only disable the drivers for the sensors that are started -by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, -and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense -cameras, 2D Lidars). - -::: - -The sensors software can be restarted by running: - -``` -onav start -s sensors -``` - -## Accessing the OutdoorNav Software Logs - -To check the logs of the OutdoorNav software, use the `onav logs` command -with the appropriate service. For example, to view the logs for the sensors -service, run: - -```bash -onav logs sensors -``` - -## Installing the OutdoorNav Software - -OutdoorNav is typically pre-installed on Clearpath robots, so most users should -not need to do a first-time installation of the software, though the process -is outlined below as a reference. - -As a first step, confirm that the robot has internet access. For example, confirm -that the following command is successful: - -``` -ping 8.8.8.8 -``` - -Second, the required dependencies need to be installed by running: - -```bash -onav depends -``` - -Third, a key needs to be added onto the robot to enable the installation -process. Contact [Clearpath Support](../support) if you did not receive your key. -To add your key, run the following, replacing `` with the actual value: - -```bash -onav key -``` - -Fourth, list the versions available for installation by running: - -```bash -onav versions -``` - -Fifth, install the OutdoorNav software for the desired version (typically the -newest version), by running the following, replacing `` with -the version to be installed: - -```bash -onav install -``` - -When prompted, trigger the reboot. - -Finally, following the reboot, run the following command to start the OutdoorNav -software. This will only be required the first time after installation. - -```bash -onav start -``` - -## Upgrading the OutdoorNav Software - -After receiving a notice that a new version of the OutdoorNav Software is -available, use the `onav upgrade` command with the appropriate version. -For example, to upgrade to the newest avialbel version that you are eligible -to receive, run the following command: - -``` -onav upgrade -``` - -:::note - -The upgrade requires internet access to download the new software. -Confirm that the OutdoorNav Computer has internet access by running a command -such as: - -``` -ping 8.8.8.8 -``` - -::: - -## Uninstalling Old Versions of OutdoorNav Software - -If old versions of OutdoorNav software are no longer being used, they can -be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 -run: - -``` -onav uninstall 0.11.0 +--- +title: Command Line Interface +sidebar_label: Command Line Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +By default, the OutdoorNav Software begins automatically when the system +is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), +the set of commands that can be used by developers who are debugging +the system or who want more precise control for managing the OutdoorNav +software. + +## 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 separate OutdoorNav Computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. Then, if a separate OutdoorNav Computer exists, you can +connect to it by running: + +``` bash +ssh administrator@192.168.131.5 +``` + +## OutdoorNav CLI Installation + +The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not +been installed on your system, it can be installed by running the following +on the OutdoorNav Computer: + +```bash +sudo apt-get install python3-onav-cli +``` + +:::note + +The command above requires that the Clearpath Package Server has been +configured on your OutdoorNav Computer. This is pre-configured on +Clearpath robots. Refer to details on the +[Clearpath Package Server](http://packages.clearpathrobotics.com/) if +this is not configured on your computer. + +::: + +## Listing the OutdoorNav CLI Commands and Getting Help + +To list all of the CLI commands, run the following on the OutdoorNav Computer: + +```bash +onav help +``` + +The CLI commands are: + +- `install`: Download and configure OutdoorNav +- `key`: Get, set, or delete your OutdoorNav license key +- `download`: Download OutdoorNav, but do not configure it +- `configure`: (Re)configure OutdoorNav +- `upgrade`: Upgrade OutdoorNav to the latest vesion +- `uninstall`: Uninstall OutdoorNav +- `depends`: Verify and install dependencies +- `start`: Start OutdoorNav +- `stop`: Stop OutdoorNav +- `status`: Check the status of OutdoorNav +- `logs`: View OutdoorNav logs +- `versions`: Print versions available to install +- `help`: Show available commands + +To get help on an individual command, use the `-h` option. For example, to +get help on the `install` command, run `onav install -h`: + +``` +usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION + +positional arguments: + VERSION The OutdoorNav version to install (e.g. 0.11.0) + +optional arguments: + -h, --help show this help message and exit + -k KEY, --key KEY Your OutdoorNav installation key + -b, --backpack Configure in backpack/bridged mode + -c, --clean Clean any configurations from a prior installation +``` + +## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} + +On UGV startup, all the sensors, the user interface, as well as the +autonomy software are set to start automatically. When debugging or when +greater control is desired, the CLI can be used to start and stop +the OutdoorNav software, in whole or in part. + +To see the current status of OutdoorNav software, run: + +```bash +onav status +``` + +To start the OutdoorNav software if it is not running, use the following command, +which starts the latest version of the software by default: + +```bash +onav start +``` + +To stop the OutdoorNav software, run: + +```bash +onav stop +``` + +## Stopping and Restarting the Autonomy Software Only + +To use the UGV without the autonomy software, use the following +command to stop the nodes and prevent them from automatic startup: + +``` bash +onav stop -s autonomy +``` + +The autonomy software can be restarted by running: + +``` bash +onav start -s autonomy +``` + +## 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 +onav stop -s sensors +``` + +:::note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars). + +::: + +The sensors software can be restarted by running: + +``` +onav start -s sensors +``` + +## Accessing the OutdoorNav Software Logs + +To check the logs of the OutdoorNav software, use the `onav logs` command +with the appropriate service. For example, to view the logs for the sensors +service, run: + +```bash +onav logs sensors +``` + +## Installing the OutdoorNav Software + +OutdoorNav is typically pre-installed on Clearpath robots, so most users should +not need to do a first-time installation of the software, though the process +is outlined below as a reference. + +As a first step, confirm that the robot has internet access. For example, confirm +that the following command is successful: + +``` +ping 8.8.8.8 +``` + +Second, the required dependencies need to be installed by running: + +```bash +onav depends +``` + +Third, a key needs to be added onto the robot to enable the installation +process. Contact [Clearpath Support](../support) if you did not receive your key. +To add your key, run the following, replacing `` with the actual value: + +```bash +onav key +``` + +Fourth, list the versions available for installation by running: + +```bash +onav versions +``` + +Fifth, install the OutdoorNav software for the desired version (typically the +newest version), by running the following, replacing `` with +the version to be installed: + +```bash +onav install +``` + +When prompted, trigger the reboot. + +Finally, following the reboot, run the following command to start the OutdoorNav +software. This will only be required the first time after installation. + +```bash +onav start +``` + +## Upgrading the OutdoorNav Software + +After receiving a notice that a new version of the OutdoorNav Software is +available, use the `onav upgrade` command with the appropriate version. +For example, to upgrade to the newest avialbel version that you are eligible +to receive, run the following command: + +``` +onav upgrade +``` + +:::note + +The upgrade requires internet access to download the new software. +Confirm that the OutdoorNav Computer has internet access by running a command +such as: + +``` +ping 8.8.8.8 +``` + +::: + +## Uninstalling Old Versions of OutdoorNav Software + +If old versions of OutdoorNav software are no longer being used, they can +be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 +run: + +``` +onav uninstall 0.11.0 ``` \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/tf_validation.mdx index 72327dbc3..ab05b15f1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/tf_validation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/getting_started/tf_validation.mdx @@ -1,80 +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
-
-
- -::: +--- +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.13.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/index.mdx @@ -1,18 +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 +--- +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.13.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/integration_requirements/integration_overview.mdx index 00cf8a071..72d78ae31 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/integration_requirements/integration_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/integration_requirements/integration_overview.mdx @@ -1,34 +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. | +--- +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.13.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/integration_requirements/interface_control_requirements.mdx index a603485bb..d9906ed65 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/integration_requirements/interface_control_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/integration_requirements/interface_control_requirements.mdx @@ -1,119 +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.mdx#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). +--- +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.mdx#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.13.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_hardware_requirements.mdx index b6abe65eb..0883eba88 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_hardware_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_hardware_requirements.mdx @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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.13.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_introduction.mdx index 83bfa1d64..4f3f1bf7d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_introduction.mdx @@ -1,93 +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 +--- +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.13.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_operating_conditions.mdx index c02228aa5..6e0b17a54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_operating_conditions.mdx @@ -1,177 +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. - +--- +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.13.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_scope.mdx index ba0092f1c..f1a326070 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/overview/overview_scope.mdx @@ -1,15 +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). - - +--- +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.13.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.13.0/safety.mdx index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.13.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.13.0/safety.mdx @@ -1,144 +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. +--- +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.14.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_endpoints/api_endpoints.mdx index c65c4150b..e1169e6e2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_endpoints/api_endpoints.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_endpoints/api_endpoints.mdx @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/api_examples.mdx index 333bd1355..eb556d30a 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/api_examples.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/api_examples.mdx @@ -1,21 +1,21 @@ ---- -title: API Examples -sidebar_label: API Examples -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -The OutdoorNav API examples are now available and accesible to everyone. A -[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along -with some example scripts are available to build and use for our application. - -A few examples scripts follow with detailed explanations: - -- [Execute Mission from File](./mission_from_file.mdx) -- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) -- [Status Monitoring](./monitor_status.mdx) -- [Network of Paths](./network_of_paths.mdx) - -The documentation for the Python API library can be built following the -instructions in the above linked GitHub repository. +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav API examples are now available and accesible to everyone. A +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +with some example scripts are available to build and use for our application. + +A few examples scripts follow with detailed explanations: + +- [Execute Mission from File](./mission_from_file.mdx) +- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) +- [Status Monitoring](./monitor_status.mdx) +- [Network of Paths](./network_of_paths.mdx) + +The documentation for the Python API library can be built following the +instructions in the above linked GitHub repository. diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_from_file.mdx index eff0f7686..0abb4ea90 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_from_file.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_from_file.mdx @@ -1,210 +1,210 @@ ---- -title: Mission from YAML File -sidebar_label: Mission from YAML File -sidebar_position: 1 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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" -``` +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.14.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_with_custom_tasks.mdx index 30ec477ea..af8335aa6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_with_custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/mission_with_custom_tasks.mdx @@ -1,233 +1,233 @@ ---- -title: Mission with Custom Tasks -sidebar_label: Mission with Custom Tasks -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -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.mdx) 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. - - +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +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.mdx) 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.14.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/monitor_status.mdx index 077a9fcf5..a6fb416c5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/monitor_status.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_examples/monitor_status.mdx @@ -1,152 +1,152 @@ ---- -title: Monitor Status -sidebar_label: Monitor Status -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## 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. +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 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.14.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_overview.mdx index d9c6d616e..1bcb0ad92 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/api/api_overview.mdx @@ -1,63 +1,63 @@ ---- -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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions -- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) - that are used for creating, deleting, and modifying OutdoorNav Mission Schedules -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions +- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) + that are used for creating, deleting, and modifying OutdoorNav Mission Schedules +- [Definitions](api_endpoints/definitions.mdx): 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.14.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/sensor_customization.mdx index c8b3305f1..75e2cc336 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/sensor_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/sensor_customization.mdx @@ -1,9 +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 support@clearpathrobotics.com to discuss any related issue. +--- +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 support@clearpathrobotics.com to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/_category_.json index d62e291a4..4b3e7b596 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index 516393373..0125d8ddc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -1,9 +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. +--- +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.14.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 5a608b28f..8f8ead901 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/footprint_tuning.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -1,9 +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 support@clearpathrobotics.com to discuss any related issue. +--- +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 support@clearpathrobotics.com to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_overview.mdx index 851df29b0..77fbabeb9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_overview.mdx @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/_category_.json index fb6592a90..0e2dc60a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/navigation_parameters.mdx index 17cadc677..e80c00c60 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/navigation_parameters.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -1,169 +1,169 @@ ---- -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 -/opt/onav//app/autonomy/params//navigation/controls_general.yaml -/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml -/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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 support@clearpathrobotics.com to discuss the issue. +--- +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 +/opt/onav//app/autonomy/params//navigation/controls_general.yaml +/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml +/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.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 support@clearpathrobotics.com to discuss the issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/user_interface_customization.mdx index 91636f138..69b11cea8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/user_interface_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/customized_tuning/user_interface_customization.mdx @@ -1,9 +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 support@clearpathrobotics.com to discuss any related issue. +--- +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 support@clearpathrobotics.com to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/features/_category_.json index 732c6cb78..3bf04f17d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/features/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/features/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav Features", - "position": 8 -} +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/features/custom_tasks.mdx index 5b1176997..056e3ff54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/features/custom_tasks.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/features/custom_tasks.mdx @@ -1,206 +1,206 @@ ---- -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 -**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* -is the currently running version of OutdoorNav. 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 -``` +--- +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 +**/opt/onav/\/app/custom_tasks/** directory, where *onav_version* +is the currently running version of OutdoorNav. 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.14.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/features/navigation.mdx index d2e0284df..5b4dfa2df 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/features/navigation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/features/navigation.mdx @@ -1,38 +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 -`/opt/onav//config/autonomy.env` file, where *onav_version* -is the currently running version of OutdoorNav. 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 drive 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_waypoint_mode.mdx#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`).| +--- +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 +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. 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 drive 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_waypoint_mode.mdx#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.14.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/_category_.json index 8b4a486d9..9a9747ef6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/first_time_checklist.mdx index e7298e8ae..9044c8da1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/first_time_checklist.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/first_time_checklist.mdx @@ -1,114 +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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_waypoint_mode.mdx#mission-creation). - -### ☐ After creating a new mission, can you execute the mission? - -To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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_waypoint_mode.mdx#mission-creation). + +### ☐ After creating a new mission, can you execute the mission? + +To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#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.mdx#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.mdx#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.14.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/terminal_interface.mdx index aeedd85fd..662608d6c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/terminal_interface.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/terminal_interface.mdx @@ -1,244 +1,244 @@ ---- -title: Command Line Interface -sidebar_label: Command Line Interface -sidebar_position: 3 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -By default, the OutdoorNav Software begins automatically when the system -is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), -the set of commands that can be used by developers who are debugging -the system or who want more precise control for managing the OutdoorNav -software. - -## 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 separate OutdoorNav Computer, -first `ssh` to the UGV using the details provided in the UGV user -manual. Then, if a separate OutdoorNav Computer exists, you can -connect to it by running: - -``` bash -ssh administrator@192.168.131.5 -``` - -## OutdoorNav CLI Installation - -The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not -been installed on your system, it can be installed by running the following -on the OutdoorNav Computer: - -```bash -sudo apt-get install python3-onav-cli -``` - -:::note - -The command above requires that the Clearpath Package Server has been -configured on your OutdoorNav Computer. This is pre-configured on -Clearpath robots. Refer to details on the -[Clearpath Package Server](http://packages.clearpathrobotics.com/) if -this is not configured on your computer. - -::: - -## Listing the OutdoorNav CLI Commands and Getting Help - -To list all of the CLI commands, run the following on the OutdoorNav Computer: - -```bash -onav help -``` - -The CLI commands are: - -- `install`: Download and configure OutdoorNav -- `key`: Get, set, or delete your OutdoorNav license key -- `download`: Download OutdoorNav, but do not configure it -- `configure`: (Re)configure OutdoorNav -- `upgrade`: Upgrade OutdoorNav to the latest vesion -- `uninstall`: Uninstall OutdoorNav -- `depends`: Verify and install dependencies -- `start`: Start OutdoorNav -- `stop`: Stop OutdoorNav -- `status`: Check the status of OutdoorNav -- `logs`: View OutdoorNav logs -- `versions`: Print versions available to install -- `help`: Show available commands - -To get help on an individual command, use the `-h` option. For example, to -get help on the `install` command, run `onav install -h`: - -``` -usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION - -positional arguments: - VERSION The OutdoorNav version to install (e.g. 0.11.0) - -optional arguments: - -h, --help show this help message and exit - -k KEY, --key KEY Your OutdoorNav installation key - -b, --backpack Configure in backpack/bridged mode - -c, --clean Clean any configurations from a prior installation -``` - -## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} - -On UGV startup, all the sensors, the user interface, as well as the -autonomy software are set to start automatically. When debugging or when -greater control is desired, the CLI can be used to start and stop -the OutdoorNav software, in whole or in part. - -To see the current status of OutdoorNav software, run: - -```bash -onav status -``` - -To start the OutdoorNav software if it is not running, use the following command, -which starts the latest version of the software by default: - -```bash -onav start -``` - -To stop the OutdoorNav software, run: - -```bash -onav stop -``` - -## Stopping and Restarting the Autonomy Software Only - -To use the UGV without the autonomy software, use the following -command to stop the nodes and prevent them from automatic startup: - -``` bash -onav stop -s autonomy -``` - -The autonomy software can be restarted by running: - -``` bash -onav start -s autonomy -``` - -## 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 -onav stop -s sensors -``` - -:::note - -This command will only disable the drivers for the sensors that are started -by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, -and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense -cameras, 2D Lidars). - -::: - -The sensors software can be restarted by running: - -``` -onav start -s sensors -``` - -## Accessing the OutdoorNav Software Logs - -To check the logs of the OutdoorNav software, use the `onav logs` command -with the appropriate service. For example, to view the logs for the sensors -service, run: - -```bash -onav logs sensors -``` - -## Installing the OutdoorNav Software - -OutdoorNav is typically pre-installed on Clearpath robots, so most users should -not need to do a first-time installation of the software, though the process -is outlined below as a reference. - -As a first step, confirm that the robot has internet access. For example, confirm -that the following command is successful: - -``` -ping 8.8.8.8 -``` - -Second, the required dependencies need to be installed by running: - -```bash -onav depends -``` - -Third, a key needs to be added onto the robot to enable the installation -process. Contact [Clearpath Support](../support) if you did not receive your key. -To add your key, run the following, replacing `` with the actual value: - -```bash -onav key -``` - -Fourth, list the versions available for installation by running: - -```bash -onav versions -``` - -Fifth, install the OutdoorNav software for the desired version (typically the -newest version), by running the following, replacing `` with -the version to be installed: - -```bash -onav install -``` - -When prompted, trigger the reboot. - -Finally, following the reboot, run the following command to start the OutdoorNav -software. This will only be required the first time after installation. - -```bash -onav start -``` - -## Upgrading the OutdoorNav Software - -After receiving a notice that a new version of the OutdoorNav Software is -available, use the `onav upgrade` command with the appropriate version. -For example, to upgrade to the newest avialbel version that you are eligible -to receive, run the following command: - -``` -onav upgrade -``` - -:::note - -The upgrade requires internet access to download the new software. -Confirm that the OutdoorNav Computer has internet access by running a command -such as: - -``` -ping 8.8.8.8 -``` - -::: - -## Uninstalling Old Versions of OutdoorNav Software - -If old versions of OutdoorNav software are no longer being used, they can -be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 -run: - -``` -onav uninstall 0.11.0 +--- +title: Command Line Interface +sidebar_label: Command Line Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +By default, the OutdoorNav Software begins automatically when the system +is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), +the set of commands that can be used by developers who are debugging +the system or who want more precise control for managing the OutdoorNav +software. + +## 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 separate OutdoorNav Computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. Then, if a separate OutdoorNav Computer exists, you can +connect to it by running: + +``` bash +ssh administrator@192.168.131.5 +``` + +## OutdoorNav CLI Installation + +The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not +been installed on your system, it can be installed by running the following +on the OutdoorNav Computer: + +```bash +sudo apt-get install python3-onav-cli +``` + +:::note + +The command above requires that the Clearpath Package Server has been +configured on your OutdoorNav Computer. This is pre-configured on +Clearpath robots. Refer to details on the +[Clearpath Package Server](http://packages.clearpathrobotics.com/) if +this is not configured on your computer. + +::: + +## Listing the OutdoorNav CLI Commands and Getting Help + +To list all of the CLI commands, run the following on the OutdoorNav Computer: + +```bash +onav help +``` + +The CLI commands are: + +- `install`: Download and configure OutdoorNav +- `key`: Get, set, or delete your OutdoorNav license key +- `download`: Download OutdoorNav, but do not configure it +- `configure`: (Re)configure OutdoorNav +- `upgrade`: Upgrade OutdoorNav to the latest vesion +- `uninstall`: Uninstall OutdoorNav +- `depends`: Verify and install dependencies +- `start`: Start OutdoorNav +- `stop`: Stop OutdoorNav +- `status`: Check the status of OutdoorNav +- `logs`: View OutdoorNav logs +- `versions`: Print versions available to install +- `help`: Show available commands + +To get help on an individual command, use the `-h` option. For example, to +get help on the `install` command, run `onav install -h`: + +``` +usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION + +positional arguments: + VERSION The OutdoorNav version to install (e.g. 0.11.0) + +optional arguments: + -h, --help show this help message and exit + -k KEY, --key KEY Your OutdoorNav installation key + -b, --backpack Configure in backpack/bridged mode + -c, --clean Clean any configurations from a prior installation +``` + +## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} + +On UGV startup, all the sensors, the user interface, as well as the +autonomy software are set to start automatically. When debugging or when +greater control is desired, the CLI can be used to start and stop +the OutdoorNav software, in whole or in part. + +To see the current status of OutdoorNav software, run: + +```bash +onav status +``` + +To start the OutdoorNav software if it is not running, use the following command, +which starts the latest version of the software by default: + +```bash +onav start +``` + +To stop the OutdoorNav software, run: + +```bash +onav stop +``` + +## Stopping and Restarting the Autonomy Software Only + +To use the UGV without the autonomy software, use the following +command to stop the nodes and prevent them from automatic startup: + +``` bash +onav stop -s autonomy +``` + +The autonomy software can be restarted by running: + +``` bash +onav start -s autonomy +``` + +## 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 +onav stop -s sensors +``` + +:::note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars). + +::: + +The sensors software can be restarted by running: + +``` +onav start -s sensors +``` + +## Accessing the OutdoorNav Software Logs + +To check the logs of the OutdoorNav software, use the `onav logs` command +with the appropriate service. For example, to view the logs for the sensors +service, run: + +```bash +onav logs sensors +``` + +## Installing the OutdoorNav Software + +OutdoorNav is typically pre-installed on Clearpath robots, so most users should +not need to do a first-time installation of the software, though the process +is outlined below as a reference. + +As a first step, confirm that the robot has internet access. For example, confirm +that the following command is successful: + +``` +ping 8.8.8.8 +``` + +Second, the required dependencies need to be installed by running: + +```bash +onav depends +``` + +Third, a key needs to be added onto the robot to enable the installation +process. Contact [Clearpath Support](../support) if you did not receive your key. +To add your key, run the following, replacing `` with the actual value: + +```bash +onav key +``` + +Fourth, list the versions available for installation by running: + +```bash +onav versions +``` + +Fifth, install the OutdoorNav software for the desired version (typically the +newest version), by running the following, replacing `` with +the version to be installed: + +```bash +onav install +``` + +When prompted, trigger the reboot. + +Finally, following the reboot, run the following command to start the OutdoorNav +software. This will only be required the first time after installation. + +```bash +onav start +``` + +## Upgrading the OutdoorNav Software + +After receiving a notice that a new version of the OutdoorNav Software is +available, use the `onav upgrade` command with the appropriate version. +For example, to upgrade to the newest avialbel version that you are eligible +to receive, run the following command: + +``` +onav upgrade +``` + +:::note + +The upgrade requires internet access to download the new software. +Confirm that the OutdoorNav Computer has internet access by running a command +such as: + +``` +ping 8.8.8.8 +``` + +::: + +## Uninstalling Old Versions of OutdoorNav Software + +If old versions of OutdoorNav software are no longer being used, they can +be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 +run: + +``` +onav uninstall 0.11.0 ``` \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/tf_validation.mdx index 72327dbc3..ab05b15f1 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/tf_validation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/getting_started/tf_validation.mdx @@ -1,80 +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
-
-
- -::: +--- +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.14.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/index.mdx @@ -1,18 +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 +--- +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.14.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/integration_requirements/integration_overview.mdx index 00cf8a071..72d78ae31 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/integration_requirements/integration_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/integration_requirements/integration_overview.mdx @@ -1,34 +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. | +--- +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.14.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/integration_requirements/interface_control_requirements.mdx index 45cdfb2c4..aa2134d6c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/integration_requirements/interface_control_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/integration_requirements/interface_control_requirements.mdx @@ -1,119 +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.mdx#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). +--- +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.mdx#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.14.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_hardware_requirements.mdx index b6abe65eb..0883eba88 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_hardware_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_hardware_requirements.mdx @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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.14.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_introduction.mdx index 83bfa1d64..4f3f1bf7d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_introduction.mdx @@ -1,93 +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 +--- +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.14.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_operating_conditions.mdx index c02228aa5..6e0b17a54 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_operating_conditions.mdx @@ -1,177 +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. - +--- +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.14.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_scope.mdx index ff5dc87c5..0791b53f5 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/overview/overview_scope.mdx @@ -1,15 +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 research-sales@clearpathrobotics.com or check -out our [YouTube channel](https://www.youtube.com/channel/UCNPP3C-ZK3mwpG2x89VE-2Q). - - +--- +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 research-sales@clearpathrobotics.com or check +out our [YouTube channel](https://www.youtube.com/channel/UCNPP3C-ZK3mwpG2x89VE-2Q). + + diff --git a/outdoornav_user_manual_versioned_docs/version-0.14.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.14.0/safety.mdx index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.14.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.14.0/safety.mdx @@ -1,144 +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. +--- +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.8.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_endpoints/api_endpoints.mdx index c65c4150b..e1169e6e2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_endpoints/api_endpoints.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_endpoints/api_endpoints.mdx @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_overview.mdx index 3b69afd02..503de14dc 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/api/api_overview.mdx @@ -1,61 +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions +- [Definitions](api_endpoints/definitions.mdx): 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.8.0/cpr_hardware.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/cpr_hardware.mdx index 2eede5246..04678bf9d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/cpr_hardware.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/cpr_hardware.mdx @@ -1,405 +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: -`/home/administrator/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](getting_started/system_setup.mdx#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. +--- +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: +`/home/administrator/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](getting_started/system_setup.mdx#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.8.0/customized_tuning/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/_category_.json index 4c27a4d91..d38b7f55c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix C: Tuning & Customization", - "position": 14 +{ + "label": "Appendix C: Tuning & Customization", + "position": 14 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/sensor_customization.mdx index 9d9f115aa..f2cce53a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/sensor_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/sensor_customization.mdx @@ -1,9 +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. +--- +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.8.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/_category_.json index d62e291a4..4b3e7b596 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx index c8f6f0c5a..d35186732 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -1,9 +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.9.0. Please contact Clearpath customer support at \ to discuss any related issue. +--- +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.9.0. Please contact Clearpath customer support at \ to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 4b90f6008..6b105ecb3 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/footprint_tuning.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -1,9 +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. +--- +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.8.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_overview.mdx index 851df29b0..77fbabeb9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_overview.mdx @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/_category_.json index fb6592a90..0e2dc60a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/navigation_parameters.mdx index 8c986090b..7cd7b1448 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/navigation_parameters.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -1,167 +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. +--- +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.8.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/user_interface_customization.mdx index c67bca22a..1e7d39c97 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/user_interface_customization.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/customized_tuning/user_interface_customization.mdx @@ -1,9 +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. +--- +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.8.0/faq.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/faq.mdx index c9e5650cc..fc1003e5e 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/faq.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/faq.mdx @@ -1,84 +1,84 @@ ---- -title: Frequently Asked Questions -sidebar_label: Frequently Asked Questions -sidebar_position: 10 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -## Autonomous Missions - -1. **How do I start, pause or stop a mission?** - - See [Mission Execution](web_user_interface/ui_autonomous_mode.mdx#mission-execution) for - information on how to start, pause or stop a mission. - -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. **How do I delete a waypoint?** - - 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**. - -4. **How do I add a Task to a Waypoint?** - - See [Add Task to Waypoint](web_user_interface/ui_autonomous_mode.mdx#add-task) for information on how - to add a Task to a Waypoint. - -5. **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 set. Set them and rerun the - mission. - -6. **The navigation gets stuck on the "Compute Path" feedback. - What should I do?** - - 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. - -7. **The UGV position and/or heading are behaving erratically while the - UGV is stationary. What should I do?** - - 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. - -## Autonomous Docking - -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?** - - It is likely that one of these 3 things occurred: - - 1. The Base Station was recently resurveyed, or - 2. The datum was recently changed, or - 3. The dock location was not set correctly. - - 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](getting_started/system_setup.mdx#set-dock-location). +--- +title: Frequently Asked Questions +sidebar_label: Frequently Asked Questions +sidebar_position: 10 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Autonomous Missions + +1. **How do I start, pause or stop a mission?** + + See [Mission Execution](web_user_interface/ui_autonomous_mode.mdx#mission-execution) for + information on how to start, pause or stop a mission. + +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. **How do I delete a waypoint?** + + 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**. + +4. **How do I add a Task to a Waypoint?** + + See [Add Task to Waypoint](web_user_interface/ui_autonomous_mode.mdx#add-task) for information on how + to add a Task to a Waypoint. + +5. **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 set. Set them and rerun the + mission. + +6. **The navigation gets stuck on the "Compute Path" feedback. + What should I do?** + + 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. + +7. **The UGV position and/or heading are behaving erratically while the + UGV is stationary. What should I do?** + + 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. + +## Autonomous Docking + +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?** + + It is likely that one of these 3 things occurred: + + 1. The Base Station was recently resurveyed, or + 2. The datum was recently changed, or + 3. The dock location was not set correctly. + + 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](getting_started/system_setup.mdx#set-dock-location). diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/_category_.json index 8b4a486d9..9a9747ef6 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/first_time_checklist.mdx index 2713f0044..24fbe18fb 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/first_time_checklist.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/first_time_checklist.mdx @@ -1,116 +1,116 @@ ---- -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.mdx) 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.mdx#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/api_endpoints.mdx). 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) - -### ☐ 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.) - -### ☐ 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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](system_setup.mdx#checking-gpt-rtk-fix) for further -troubleshooting information. - -### ☐ Is the map loading correctly? - -Currently the map requires internet access to load. Refer to -[Loading Map Tiles](system_setup.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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) + +### ☐ 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.) + +### ☐ 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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](system_setup.mdx#checking-gpt-rtk-fix) for further +troubleshooting information. + +### ☐ Is the map loading correctly? + +Currently the map requires internet access to load. Refer to +[Loading Map Tiles](system_setup.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#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.8.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/getting_started/system_setup.mdx index d5703b8ea..02ab18d57 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 @@ -1,307 +1,307 @@ ---- -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.mdx). - -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.100/** for - systems with a separate OutdoorNav computer. - - ::: - -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. 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 - 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.** - -7. 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 6. - -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. - -## Set the Magnetic Declination of the IMU - -Before using OutdoorNav Software, the `MAGNETIC_DECLINATION` variable -must be set. This parameter is in degrees and in ENU convention. Use the -online calculator on this website to find out the magnetic declination -at your location. - -https://www.magnetic-declination.com/countries.php - -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](../navigation.mdx#connecting-to-outdoornav-computer) for -details on connecting to the OutdoorNav Computer. Then execute the -following command to open the required file: - -``` -sudo nano /etc/ros/setup.bash -``` - -Once the file has been opened, find the line that exports the -`MAGNETIC_DECLINATION` variable and modify its value. Once done, use -`ctrl+x` to close and save your changes. Next reboot the robot using -`sudo reboot`. commands: - -To make sure that your changes have been applied, echo the value of -`MAGNETIC_DECLINATION` and make sure it has the correct value. - -``` bash -echo $MAGNETIC_DECLINATION -``` - -## 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 - -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. - -## 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, and **Wait**. - > - 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. **Navigation** Details on the software used for autonomous - navigation. -4. **Simulation:** Details on how to simulate autonomous operation of - the UGV. -5. **FAQs:** A list of frequently asked questions. +--- +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.mdx). + +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.100/** for + systems with a separate OutdoorNav computer. + + ::: + +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. 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 + 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.** + +7. 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 6. + +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. + +## Set the Magnetic Declination of the IMU + +Before using OutdoorNav Software, the `MAGNETIC_DECLINATION` variable +must be set. This parameter is in degrees and in ENU convention. Use the +online calculator on this website to find out the magnetic declination +at your location. + +https://www.magnetic-declination.com/countries.php + +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](../navigation.mdx#connecting-to-outdoornav-computer) for +details on connecting to the OutdoorNav Computer. Then execute the +following command to open the required file: + +``` +sudo nano /etc/ros/setup.bash +``` + +Once the file has been opened, find the line that exports the +`MAGNETIC_DECLINATION` variable and modify its value. Once done, use +`ctrl+x` to close and save your changes. Next reboot the robot using +`sudo reboot`. commands: + +To make sure that your changes have been applied, echo the value of +`MAGNETIC_DECLINATION` and make sure it has the correct value. + +``` bash +echo $MAGNETIC_DECLINATION +``` + +## 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 + +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. + +## 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, and **Wait**. + > - 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. **Navigation** Details on the software used for autonomous + navigation. +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.8.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/index.mdx @@ -1,18 +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 +--- +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.8.0/integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/_category_.json index e9e0ff1dd..adbe22cba 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Appendix A: UGV Integration Requirements", - "position": 12 +{ + "label": "Appendix A: UGV Integration Requirements", + "position": 12 } \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/hardware_integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/hardware_integration_requirements/_category_.json index 75ebaf1b4..7950de6b7 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/hardware_integration_requirements/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/hardware_integration_requirements/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Hardware Kit Installation", - "position": 2 -} +{ + "label": "Hardware Kit Installation", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/integration_overview.mdx index 00cf8a071..72d78ae31 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/integration_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/integration_overview.mdx @@ -1,34 +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. | +--- +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.8.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/interface_control_requirements.mdx index 396f6dcd0..c3d11a6fb 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/interface_control_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/interface_control_requirements.mdx @@ -1,119 +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.mdx) 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). +--- +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.mdx) 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.8.0/integration_requirements/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/software_integration_instructions.mdx index 186361f30..0154d4b91 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/software_integration_instructions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/integration_requirements/software_integration_instructions.mdx @@ -1,145 +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: -- [Interface Control Checklist](interface_control_requirements.mdx) - -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/hardware_integration_requirements.mdx). - -``` 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.mdx) -::: - -### 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 -``` - -### 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 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 - -# 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 -``` - -Once installation is complete, you can proceed to [Getting Started](../getting_started/system_setup.mdx) to start using the software. +--- +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](interface_control_requirements.mdx) + +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/hardware_integration_requirements.mdx). + +``` 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.mdx) +::: + +### 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 +``` + +### 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 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 + +# 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 +``` + +Once installation is complete, you can proceed to [Getting Started](../getting_started/system_setup.mdx) to start using the software. diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/navigation.mdx index 55abd1467..3653607bf 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/navigation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/navigation.mdx @@ -1,348 +1,348 @@ ---- -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](web_user_interface/ui_autonomous_mode.mdx#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: 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](web_user_interface/ui_autonomous_mode.mdx#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
+
+
+ +::: diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_hardware_requirements.mdx index 7c35a31c5..14c01e449 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_hardware_requirements.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_hardware_requirements.mdx @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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.8.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_introduction.mdx index 83bfa1d64..4f3f1bf7d 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_introduction.mdx @@ -1,93 +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 +--- +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.8.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_operating_conditions.mdx index 2911ec1e8..ceb1dc529 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_operating_conditions.mdx @@ -1,178 +1,178 @@ ---- -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 -for release 0.5.0. - +--- +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 +for release 0.5.0. + ::: \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_scope.mdx index ba0092f1c..f1a326070 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/overview/overview_scope.mdx @@ -1,15 +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). - - +--- +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.8.0/release_notes.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/release_notes.mdx index 9849b86f9..51dc16e13 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/release_notes.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/release_notes.mdx @@ -1,184 +1,184 @@ ---- -title: Release Notes -sidebar_label: Release Notes -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -import Style from '/assets/css/changelog.css'; - -
- -## 0.8.0 - -### New Features - -- Inertial Measurement Units (IMUs) integrated into localization. -- Added localization status topic (see see [API Endpoints](api/api_endpoints/autonomy_api.mdx)). -- Added re-localization service (see [API Endpoints](api/api_endpoints/autonomy_api.mdx)). -- 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). - -## 0.7.0 - -### New Features - -- Goal terminology has been removed from the mission generation nomenclature (see - [Definitions](web_user_interface/ui_autonomous_mode.mdx#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.mdx) - 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. - +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Style from '/assets/css/changelog.css'; + +
+ +## 0.8.0 + +### New Features + +- Inertial Measurement Units (IMUs) integrated into localization. +- Added localization status topic (see see [API Endpoints](api/api_endpoints/autonomy_api.mdx)). +- Added re-localization service (see [API Endpoints](api/api_endpoints/autonomy_api.mdx)). +- 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). + +## 0.7.0 + +### New Features + +- Goal terminology has been removed from the mission generation nomenclature (see + [Definitions](web_user_interface/ui_autonomous_mode.mdx#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.mdx) + 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. +
\ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/safety.mdx index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/safety.mdx @@ -1,144 +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. +--- +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.8.0/simulation.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/simulation.mdx index 44cff5f7a..86043ef71 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/simulation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/simulation.mdx @@ -1,20 +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 +--- +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.8.0/support.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/support.mdx index 9212d99f2..4da40f82f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/support.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/support.mdx @@ -1,11 +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"; - +--- +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.8.0/web_user_interface/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/_category_.json index a07ca158b..31b780353 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Web User Interface", - "position": 6 -} +{ + "label": "Web User Interface", + "position": 6 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_autonomous_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_autonomous_mode.mdx index c3919a07f..00a6a771e 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_autonomous_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_autonomous_mode.mdx @@ -1,344 +1,344 @@ ---- -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.mdx) 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 1.5 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. - -## 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 - -
-
- -
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 UGVs - 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.mdx#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 - 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 - 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. See Section - [Autonomous Docking](#autonomous-docking) for more - information on the autonomous docking feature. - - - **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. - -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. - -## 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. +--- +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.mdx) 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 1.5 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. + +## 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 + +
+
+ +
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 UGVs + 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.mdx#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 + 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 + 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. See Section + [Autonomous Docking](#autonomous-docking) for more + information on the autonomous docking feature. + + - **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. + +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. + +## 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.8.0/web_user_interface/ui_manual_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_manual_mode.mdx index 055882848..7c049a0a9 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_manual_mode.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_manual_mode.mdx @@ -1,49 +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.mdx) 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 +--- +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.mdx) 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.8.0/web_user_interface/ui_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_overview.mdx index f21f973de..25f17d379 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.8.0/web_user_interface/ui_overview.mdx @@ -1,383 +1,383 @@ ---- -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 or Help pages. - -2. **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 Heading:** The UGV's heading in the world frame. - -5. **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. - -6. **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. - -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 - - 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. - -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 - 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 - 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 - 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. - - ::: - -13. **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. **Start Button:** Start the current Mission. - -16. **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 - 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: - -- 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 - -### 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 - http://localhost:8000/{z}/{x}/{-y}.png. 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. +--- +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 or Help pages. + +2. **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 Heading:** The UGV's heading in the world frame. + +5. **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. + +6. **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. + +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 + + 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. + +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 + 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 + 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 + 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. + + ::: + +13. **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. **Start Button:** Start the current Mission. + +16. **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 + 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: + +- 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 + +### 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 + http://localhost:8000/{z}/{x}/{-y}.png. 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_docs/version-0.9.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.9.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.9.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "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 index a6e539204..79c716587 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} 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 index c65c4150b..e1169e6e2 100644 --- 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 @@ -1,16 +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.mdx) -- [Autonomy API](autonomy_api.mdx) -- [Mission Manager API](mission_manager_api.mdx) -- [Definitions](definitions.mdx) - +--- +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.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + 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 index e123509b6..86c5eb413 100644 --- 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 @@ -1,18 +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). - -::: - +--- +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 index 2c80b317e..9c2a0305d 100644 --- 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 @@ -1,220 +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" -``` +--- +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 index 9a4a4efd4..a73ebb7ec 100644 --- 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 @@ -1,243 +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.mdx) 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. - - +--- +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.mdx) 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 index 8aeb3ca86..6e9f280e7 100644 --- 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 @@ -1,162 +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. +--- +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 index 3b69afd02..503de14dc 100644 --- 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 @@ -1,61 +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): - The set of topics that are published by the hardware platform. - - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): - The set of topics that are subscribed to by the hardware - platform. -- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS - Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions -- [Definitions](api_endpoints/definitions.mdx): 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. +--- +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.mdx): 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](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): 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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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](api_endpoints/autonomy_api.mdx#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.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav missions +- [Definitions](api_endpoints/definitions.mdx): 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 index f60527ff9..2d1efdd01 100644 --- 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 @@ -1,405 +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](getting_started/system_setup.mdx#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. +--- +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](getting_started/system_setup.mdx#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 index 4c27a4d91..d38b7f55c 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Appendix C: Tuning & Customization", - "position": 14 +{ + "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 index 9d9f115aa..f2cce53a9 100644 --- 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 @@ -1,9 +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. +--- +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 index d62e291a4..4b3e7b596 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Tuning Instructions", - "position": 2 -} +{ + "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 index 516393373..0125d8ddc 100644 --- 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 @@ -1,9 +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. +--- +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/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/customized_tuning/tuning_instructions/footprint_tuning.mdx index 4b90f6008..6b105ecb3 100644 --- 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 @@ -1,9 +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. +--- +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 index 851df29b0..77fbabeb9 100644 --- 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 @@ -1,25 +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.mdx) -- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) - - -Lists of parameters related to each component of the autonomy can be found here: - -- [Localization Parameters](tuning_parameters/localization_parameters.mdx) -- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) -- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) - -In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +--- +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.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) as well as how to [Customize which Sensors](sensor_customization.mdx) 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 index fb6592a90..0e2dc60a9 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Tuning Parameters", - "position": 3 -} +{ + "label": "Tuning Parameters", + "position": 3 +} 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 index 8c986090b..7cd7b1448 100644 --- 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 @@ -1,167 +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. +--- +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 index c67bca22a..1e7d39c97 100644 --- 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 @@ -1,9 +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. +--- +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 index cc7d4c1a9..5d2065183 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.9.0/faq.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/faq.mdx @@ -1,194 +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.mdx#mission-execution)) or, - ii) through the ROS API (See [API Examples](api/api_examples/api_examples.mdx)). - -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.mdx) 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.mdx). - 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.mdx). - -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.mdx) and contact - [Support](support.mdx) 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.mdx#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.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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.mdx#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.mdx). - -5. **What to do if my custom task is not working?** - - Ensure that you have followed the [Custom Tasks](features/custom_tasks.mdx) 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.mdx#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) - +--- +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.mdx#mission-execution)) or, + ii) through the ROS API (See [API Examples](api/api_examples/api_examples.mdx)). + +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.mdx) 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.mdx). + 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.mdx). + +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.mdx) and contact + [Support](support.mdx) 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.mdx#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.mdx#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.mdx) 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.mdx). 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.mdx) 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/api_examples.mdx) 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.mdx#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.mdx). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](features/custom_tasks.mdx) 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.mdx#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 index 732c6cb78..3bf04f17d 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav Features", - "position": 8 -} +{ + "label": "OutdoorNav Features", + "position": 8 +} 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 index 32c3115ee..de2c855a0 100644 --- 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 @@ -1,203 +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 -``` +--- +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/mission_scheduler.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/features/mission_scheduler.mdx index 95c870612..0afdfcaf3 100644 --- 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 @@ -1,43 +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 +--- +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 index e4c0b8644..a55482503 100644 --- 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 @@ -1,38 +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.mdx#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`).| +--- +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.mdx#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 index 503d94ae7..f102726e5 100644 --- 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 @@ -1,34 +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. +--- +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 index 8b4a486d9..9a9747ef6 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Getting Started", - "position": 5 -} +{ + "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 index 124a76e44..92d068e87 100644 --- 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 @@ -1,114 +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). - -### ☐ Have you surveyed the Base Station? - -See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details -related to setting up the map. - -### ☐ Has the Datum been set? - -See [Set Datum](./system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#ptz-view) for more details related +--- +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.mdx) 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.mdx#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/api_endpoints.mdx). 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.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#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.mdx#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.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](./system_setup.mdx#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.mdx#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.mdx) 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.mdx#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.mdx#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.mdx#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.mdx#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 index e5062958f..79397185d 100644 --- 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 @@ -1,236 +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.mdx). - -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.mdx) 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. +--- +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.mdx). + +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.mdx) 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 index 43e9dedc1..76de4f412 100644 --- 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 @@ -1,141 +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 +--- +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 index 72327dbc3..ab05b15f1 100644 --- 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 @@ -1,80 +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
-
-
- -::: +--- +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 index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.9.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/index.mdx @@ -1,18 +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 +--- +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 index e9e0ff1dd..adbe22cba 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Appendix A: UGV Integration Requirements", - "position": 12 +{ + "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 index 75ebaf1b4..7950de6b7 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Hardware Kit Installation", - "position": 2 -} +{ + "label": "Hardware Kit Installation", + "position": 2 +} 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 index 00cf8a071..72d78ae31 100644 --- 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 @@ -1,34 +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. | +--- +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 index a603485bb..d9906ed65 100644 --- 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 @@ -1,119 +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.mdx#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). +--- +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.mdx#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/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.9.0/integration_requirements/software_integration_instructions.mdx index 41efff44f..454f93c94 100644 --- 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 @@ -1,145 +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: -- [Interface Control Checklist](interface_control_requirements.mdx) - -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/hardware_integration_requirements.mdx). - -``` 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.mdx) -::: - -### 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.mdx) to start using the software. +--- +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/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](interface_control_requirements.mdx) + +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/hardware_integration_requirements.mdx). + +``` 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.mdx) +::: + +### 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.mdx) 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 index 663e4088f..8414dc7f2 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 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 index b6abe65eb..0883eba88 100644 --- 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 @@ -1,44 +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.mdx). - -## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | - -## 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") +--- +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.mdx). + +## 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/api_endpoints.mdx); 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/api_endpoints.mdx) | + +## 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 index 83bfa1d64..4f3f1bf7d 100644 --- 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 @@ -1,93 +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 +--- +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 index c02228aa5..6e0b17a54 100644 --- 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 @@ -1,177 +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. - +--- +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 index ba0092f1c..f1a326070 100644 --- 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 @@ -1,15 +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). - - +--- +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 index b0dc295a4..877c6585a 100644 --- 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 @@ -1,222 +1,222 @@ ---- -title: Release Notes -sidebar_label: Release Notes -sidebar_position: 2 -toc_min_heading_level: 2 -toc_max_heading_level: 4 ---- - -import Style from '/assets/css/changelog.css'; - -
- -## 0.9.0 - -### New Features - -- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](features/mission_scheduler.mdx)) -- 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.mdx)) -- 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.mdx)): - - /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.mdx)) - - 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.mdx#localizationstatus)). -- Added re-localization service (see [API Endpoints](api/api_endpoints/definitions.mdx#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.mdx#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.mdx) - 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. - +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import Style from '/assets/css/changelog.css'; + +
+ +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](features/mission_scheduler.mdx)) +- 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.mdx)) +- 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.mdx)): + - /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.mdx)) + - 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.mdx#localizationstatus)). +- Added re-localization service (see [API Endpoints](api/api_endpoints/definitions.mdx#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.mdx#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.mdx) + 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. +
\ No newline at end of file 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 index ea70a51b2..ba0e8ddf8 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.9.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/safety.mdx @@ -1,144 +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. +--- +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 index 44cff5f7a..86043ef71 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.9.0/simulation.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/simulation.mdx @@ -1,20 +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 +--- +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 index 9212d99f2..4da40f82f 100644 --- a/outdoornav_user_manual_versioned_docs/version-0.9.0/support.mdx +++ b/outdoornav_user_manual_versioned_docs/version-0.9.0/support.mdx @@ -1,11 +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"; - +--- +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 index a07ca158b..31b780353 100644 --- 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 @@ -1,4 +1,4 @@ -{ - "label": "Web User Interface", - "position": 6 -} +{ + "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 index 4b169d54b..43cce7f28 100644 --- 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 @@ -1,369 +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.mdx) 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.mdx#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.mdx) 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. +--- +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.mdx) 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.mdx#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.mdx) 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 index 055882848..7c049a0a9 100644 --- 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 @@ -1,49 +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.mdx) 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 +--- +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.mdx) 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 index 17f6d8247..ed1b57dd1 100644 --- 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 @@ -1,422 +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: http://localhost:8000/. - - ``` - 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. +--- +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: http://localhost:8000/. + + ``` + 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_docs/version-2.0.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-2.0.0/_category_.json index c123e1bc5..f5966a95c 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "OutdoorNav User Manual", - "position": 1 -} +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-2.0.0/api/_category_.json index a6e539204..79c716587 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/api/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/api/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Application Programming Interface", - "position": 7 -} +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-2.0.0/api/api_overview.mdx index 4a56435b3..3c6055d67 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/api/api_overview.mdx +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/api/api_overview.mdx @@ -1,26 +1,26 @@ ---- -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 2 Jazzy](https://docs.ros.org/en/jazzy/index.html) API. -The message and services types for the API are defined at: -https://github.com/clearpathrobotics/clearpath_msgs/tree/onav-ros2/clearpath_outdoornav_msgs - +--- +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 2 Jazzy](https://docs.ros.org/en/jazzy/index.html) API. +The message and services types for the API are defined at: +https://github.com/clearpathrobotics/clearpath_msgs/tree/onav-ros2/clearpath_outdoornav_msgs + More details on the API will be provided in a future release of the documentation. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-2.0.0/index.mdx index 09a63a7f5..3d1655b95 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/index.mdx +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/index.mdx @@ -1,18 +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 +--- +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-2.0.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/_category_.json index 663e4088f..8414dc7f2 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Overview", - "position": 4 -} +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_introduction.mdx index 95c7e2f43..21a17e203 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_introduction.mdx +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_introduction.mdx @@ -1,79 +1,79 @@ ---- -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. - -## Key Features - -Key features of OutdoorNav Software include: - -- Mission Planning and Autonomous Navigation - - - Robust GPS-based localization with sensor fusion of camera, IMU, LiDAR - and platform odometry - - Autonomous path following through a network of paths - - 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 - -- 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 autonomy API - -- 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 +--- +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. + +## Key Features + +Key features of OutdoorNav Software include: + +- Mission Planning and Autonomous Navigation + + - Robust GPS-based localization with sensor fusion of camera, IMU, LiDAR + and platform odometry + - Autonomous path following through a network of paths + - 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 + +- 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 autonomy API + +- 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 diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_operating_conditions.mdx index 134fadcc5..072e31800 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_operating_conditions.mdx +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_operating_conditions.mdx @@ -1,113 +1,113 @@ ---- -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 - -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. With -standard sensors: - -- Location accuracy (position & heading): Less than 5 cm and less than 2° -- Path tracking accuracy (approximate): 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. | -| 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 3D LiDARs. Obstacle detection and avoidance may not function in all weather conditions and must be disabled to navigate in heavy snow or rain. | -| 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. | -| 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. | +--- +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 + +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. With +standard sensors: + +- Location accuracy (position & heading): Less than 5 cm and less than 2° +- Path tracking accuracy (approximate): 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. | +| 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 3D LiDARs. Obstacle detection and avoidance may not function in all weather conditions and must be disabled to navigate in heavy snow or rain. | +| 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. | +| 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. | diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_scope.mdx index baf0b9f2d..5b741ff5c 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_scope.mdx +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/overview/overview_scope.mdx @@ -1,13 +1,13 @@ ---- -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 +--- +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). \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/quick_start/_category_.json b/outdoornav_user_manual_versioned_docs/version-2.0.0/quick_start/_category_.json index f92c8e916..6a14af931 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/quick_start/_category_.json +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/quick_start/_category_.json @@ -1,4 +1,4 @@ -{ - "label": "Quick Start", - "position": 5 -} +{ + "label": "Quick Start", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-2.0.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-2.0.0/safety.mdx index 1de70c909..3f2d66458 100644 --- a/outdoornav_user_manual_versioned_docs/version-2.0.0/safety.mdx +++ b/outdoornav_user_manual_versioned_docs/version-2.0.0/safety.mdx @@ -1,139 +1,139 @@ ---- -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. - -- 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. +--- +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. + +- 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/static/assets/css/changelog.css b/static/assets/css/changelog.css index 19a859f5d..8b82f89bd 100644 --- a/static/assets/css/changelog.css +++ b/static/assets/css/changelog.css @@ -39,3 +39,8 @@ content: none; counter-increment: none; } + +.changelog table { + display: table; + margin: 0 auto; +} \ No newline at end of file diff --git a/static/img/robot_images/husky_a300_images/husky_a300_motor_5.jpg b/static/img/robot_images/husky_a300_images/husky_a300_motor_5.jpg new file mode 100644 index 000000000..0650c5af9 Binary files /dev/null and b/static/img/robot_images/husky_a300_images/husky_a300_motor_5.jpg differ diff --git a/static/img/robot_images/husky_a300_images/husky_a300_nameplate.png b/static/img/robot_images/husky_a300_images/husky_a300_nameplate.png index b86eb04e0..6b6e5170e 100644 Binary files a/static/img/robot_images/husky_a300_images/husky_a300_nameplate.png and b/static/img/robot_images/husky_a300_images/husky_a300_nameplate.png differ diff --git a/static/img/website_images/husky_a300_thumbnail.png b/static/img/website_images/husky_a300_thumbnail.png index 9d59d4a5c..c50147d75 100644 Binary files a/static/img/website_images/husky_a300_thumbnail.png and b/static/img/website_images/husky_a300_thumbnail.png differ diff --git a/static/reference_pages/reference_sensor.mdx b/static/reference_pages/reference_sensor.mdx index a0731947b..1d5319b25 100644 --- a/static/reference_pages/reference_sensor.mdx +++ b/static/reference_pages/reference_sensor.mdx @@ -1,82 +1,82 @@ ---- -title: TODO -sidebar_position: 1 ---- - -import SoftwareBringup from "/components/_software_sensor_iso_supported.mdx"; -import Support from "/components/support.mdx"; - -TODO: update with a path to the sensor's image - -
- -
- ---- - -## Item Numbers - -| Description | CPR item | -| :-------------------- | :----------------------------------------------------: | -| TODO sensor | [TODO](/assets/pdf/clearpath_robotics_011703-TDS2.pdf) | -| TODO sensor, PACS™ kit | TODO | - ---- - -## Specifications - -### Overview - -| Description | Value | -| :-------------------------- | :---- | -| Mass | | -| Voltage, Minimum | | -| Voltage, Maximum | | -| Voltage, Sensor | | -| Power, Average | | -| Data | | -| Range, Minimum | | -| Range, Maximum | | -| Range, Accuracy | | -| View, Horizontal | | -| View, Vertical | | -| Resolution, Horizontal | | -| Resolution, Vertical | | -| Ingress Protection, Solids | | -| Ingress Protection, Liquids | | -| Operating Temperature, Min | | -| Operating Temperature, Max | | - ---- - -## Software Bringup - - - ---- - -## Troubleshooting - -**Sensor is not turning on** - -1. Turn the robot off -2. Check that connectors are fully seated -3. Turn on the robot and see if the sensor is turning on -4. If it does not turn on, unplug the rectangular power connector -5. With a multimeter, measure the voltage across positions 2 and 6 on the robot's connector -6. If the measurement is 12 V, then there is likely an issue with the sensor, and you should contact Clearpath Robotics -7. If the measurement is 0 V, then the 12 V fuse on your robot has likely failed. Shut off the robot, replace the fuse, and then replace the sensor's rectangular connector. - -### If the issue persists - - - ---- - -## Further Reading - -1. [Clearpath Robotics Store](https://store.clearpathrobotics.com) -2. [ROS webpage](http://wiki.ros.org) +--- +title: TODO +sidebar_position: 1 +--- + +import SoftwareBringup from "/components/_software_sensor_iso_supported.mdx"; +import Support from "/components/support.mdx"; + +TODO: update with a path to the sensor's image + +
+ +
+ +--- + +## Item Numbers + +| Description | CPR item | +| :-------------------- | :----------------------------------------------------: | +| TODO sensor | [TODO](/assets/pdf/clearpath_robotics_011703-TDS2.pdf) | +| TODO sensor, PACS™ kit | TODO | + +--- + +## Specifications + +### Overview + +| Description | Value | +| :-------------------------- | :---- | +| Mass | | +| Voltage, Minimum | | +| Voltage, Maximum | | +| Voltage, Sensor | | +| Power, Average | | +| Data | | +| Range, Minimum | | +| Range, Maximum | | +| Range, Accuracy | | +| View, Horizontal | | +| View, Vertical | | +| Resolution, Horizontal | | +| Resolution, Vertical | | +| Ingress Protection, Solids | | +| Ingress Protection, Liquids | | +| Operating Temperature, Min | | +| Operating Temperature, Max | | + +--- + +## Software Bringup + + + +--- + +## Troubleshooting + +**Sensor is not turning on** + +1. Turn the robot off +2. Check that connectors are fully seated +3. Turn on the robot and see if the sensor is turning on +4. If it does not turn on, unplug the rectangular power connector +5. With a multimeter, measure the voltage across positions 2 and 6 on the robot's connector +6. If the measurement is 12 V, then there is likely an issue with the sensor, and you should contact Clearpath Robotics +7. If the measurement is 0 V, then the 12 V fuse on your robot has likely failed. Shut off the robot, replace the fuse, and then replace the sensor's rectangular connector. + +### If the issue persists + + + +--- + +## Further Reading + +1. [Clearpath Robotics Store](https://store.clearpathrobotics.com) +2. [ROS webpage](http://wiki.ros.org)