diff --git a/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx b/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx index 43e9dedc..8afafb7c 100644 --- a/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx +++ b/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx @@ -1,141 +1,249 @@ --- -title: Terminal Interface -sidebar_label: Terminal Interface +title: Command Line Interface +sidebar_label: Command Line Interface sidebar_position: 3 toc_min_heading_level: 2 toc_max_heading_level: 4 --- -## Command Line Operation +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. -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} +## 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, +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. 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. +manual. Then, if a separate OutdoorNav Computer exists, you can +connect to it by running: ``` bash -ssh administrator@192.168.131.1 +ssh administrator@192.168.131.5 ``` -Then, connect to the OutdoorNav Computer: +## OutdoorNav CLI Installation -``` bash -ssh administrator@192.168.131.5 +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 ``` -### Starting the Navigation Software {#starting-outdoornav} +:::note -Begin by connecting to the OutdoorNav Computer as outlined above. +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. -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 +## 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 ``` -### Stopping/Restarting all of OutdoorNav +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 -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. +positional arguments: + VERSION The OutdoorNav version to install (e.g. 0.11.0) -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav down +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 ``` -If the OutdoorNav software has been brought down, it can be restarted by running: +## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} -``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile outdoornav up -d +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 ``` -### Stopping/Restarting the Autonomy +To start the OutdoorNav software if it is not running, use the following command, +which starts the latest version of the software by default: -To use the UGV without the autonomy core of OutdoorNav, use these -commands to stop the nodes and prevent them from automatic startup: +```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 -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile autonomy down +onav stop -s autonomy ``` -The autonomy core can be restarted by running: +The autonomy software can be restarted by running: ``` bash -cd ~/cpr_outdoornav_launch/ # directory with docker-compose.yaml -docker compose --profile autonomy up -d +onav start -s autonomy ``` -### Stopping/Restarting the Sensors +## 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 +onav stop -s sensors ``` -::: note +:::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, +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) +cameras, 2D Lidars). ::: -### Accessing the Navigation Software Logs +The sensors software can be restarted by running: -To check the logs of the Navigation software: +``` +onav start -s sensors +``` -``` bash -cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml -docker compose logs -f +## 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 ``` -Optionally, specify the specific container you would like to view logs for: +## Installing the OutdoorNav Software -``` bash -cd ~/cpr_outdoornav_launch/ # The directory with docker-compose.yaml -docker compose logs -f onav-autonomy +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/docs_versioned_docs/version-ros2humble/components/yaml/links/mesh.mdx b/docs_versioned_docs/version-ros2humble/components/yaml/links/mesh.mdx index 47a5274d..15f974b6 100644 --- a/docs_versioned_docs/version-ros2humble/components/yaml/links/mesh.mdx +++ b/docs_versioned_docs/version-ros2humble/components/yaml/links/mesh.mdx @@ -15,7 +15,9 @@ mesh: parent: base_link xyz: [0.0, 0.0, 0.0] rpy: [0.0, 0.0, 0.0] - visual: /absolute/path/to/mesh.stl + visual: + package: package_name # optional + path: relative/path/to/mesh/in/package.stl # or /absolute/path/to/mesh.stl ``` diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/battery_fault.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/battery_fault.gif new file mode 100644 index 00000000..a37c51cd Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/battery_fault.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/charged.png b/docs_versioned_docs/version-ros2humble/ros/api/img/charged.png new file mode 100644 index 00000000..c0913485 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/charged.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/charging.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/charging.gif new file mode 100644 index 00000000..3a355ad4 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/charging.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/driving.png b/docs_versioned_docs/version-ros2humble/ros/api/img/driving.png new file mode 100644 index 00000000..449c8ed7 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/driving.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/idle.png b/docs_versioned_docs/version-ros2humble/ros/api/img/idle.png new file mode 100644 index 00000000..1ba715dc Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/idle.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/low_battery.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/low_battery.gif new file mode 100644 index 00000000..7073fca7 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/low_battery.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/needs_reset.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/needs_reset.gif new file mode 100644 index 00000000..ee4d0821 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/needs_reset.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/shore_and_charged.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_and_charged.gif new file mode 100644 index 00000000..dea4ef4a Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_and_charged.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/shore_and_charging.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_and_charging.gif new file mode 100644 index 00000000..5fe80988 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_and_charging.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/shore_fault.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_fault.gif new file mode 100644 index 00000000..6188f3e6 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_fault.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/shore_power.png b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_power.png new file mode 100644 index 00000000..c9f30544 Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/shore_power.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/img/stopped.gif b/docs_versioned_docs/version-ros2humble/ros/api/img/stopped.gif new file mode 100644 index 00000000..9c32bcee Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/api/img/stopped.gif differ diff --git a/docs_versioned_docs/version-ros2humble/ros/api/lighting.mdx b/docs_versioned_docs/version-ros2humble/ros/api/lighting.mdx new file mode 100644 index 00000000..397aa1d5 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/api/lighting.mdx @@ -0,0 +1,197 @@ +--- +title: Lighting +sidebar_label: Lighting +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- + +Corner lighting is unified for platforms that support it (D100, D150, R100, W200). Lighting is controlled by the [lighting node](https://github.com/clearpathrobotics/clearpath_common/tree/humble/clearpath_platform/src/lighting) which defines multiple lighting states. +The platforms lighting state is determined based on data from multiple platform status topics. Lighting states are given a priority, such that the most important state (lowest priority value) is displayed first. + +The lighting node will publish the current lighting command directly to the MCU. It also subscribes to user lighting commands, and will instead publish those user commands if appropriate. + + +## Lighting States + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Lighting StateLighting PatternPriorityUser commands allowedPlatform
Battery Fault +
+ +
+ 		0NoD100, D150, R100, W200
Shore Power Fault +
+ +
+ 		1NoD100, D150
Shore Power and Charged +
+ +
+ 		2YesD100, D150
Shore Power and Charging +
+ +
+ 		3YesD150
Shore Power +
+ +
+ 		4YesD100, D150
Charged +
+ +
+ 		5YesD100, D150, R100, W200
Charging +
+ +
+ 		6YesD150, R100
Stopped +
+ +
+ 		7NoD100, D150, R100, W200
Needs Reset +
+ +
+ 		8NoR100
Low Battery +
+ +
+ 		9NoD100, D150, R100, W200
Driving +
+ +
+ 		10YesD100, D150, R100, W200
Idle +
+ +
+ 		11YesD100, D150, R100, W200
diff --git a/docs_versioned_docs/version-ros2humble/ros/api/mcu_api.mdx b/docs_versioned_docs/version-ros2humble/ros/api/mcu_api.mdx index 4494095e..849e0ac3 100644 --- a/docs_versioned_docs/version-ros2humble/ros/api/mcu_api.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/api/mcu_api.mdx @@ -8,16 +8,17 @@ toc_max_heading_level: 4 ## MCU topics -| Topic | Message type | Publisher | Description | QoS | -| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- | :-------------------------------------- | :---------------------------------------------- | -| platform/emergency_stop | [std_msgs/Bool](https://github.com/ros2/common_interfaces/blob/humble/std_msgs/msg/Bool.msg) | MCU node | State of platform emergency stop | [Sensor Data](overview.mdx#sensor-data) | -| platform/mcu/status | [clearpath_platform_msgs/Status](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Status.msg) | MCU node | MCU status | [Sensor Data](overview.mdx#sensor-data) | -| platform/mcu/status/power | [clearpath_platform_msgs/Power](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Power.msg) | MCU node | Robot Power status | [Sensor Data](overview.mdx#sensor-data) | -| platform/mcu/status/stop | [clearpath_platform_msgs/StopStatus](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/StopStatus.msg) | MCU node | Stop loop status | [Sensor Data](overview.mdx#sensor-data) | -| platform/motors/cmd_drive | [clearpath_platform_msgs/Drive](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Drive.msg) | Control node | Command velocities to individual wheels | [Sensor Data](overview.mdx#sensor-data) | -| platform/motors/feedback | [clearpath_platform_msgs/DriveFeedback](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/DriveFeedback.msg) | MCU node | Feedback from motor drive unit | [Sensor Data](overview.mdx#sensor-data) | -| platform/wifi_connected | [std_msgs/Bool](https://github.com/ros2/common_interfaces/blob/humble/std_msgs/msg/Bool.msg) | Wireless Watcher node | Wi-Fi connected status | [Sensor Data](overview.mdx#sensor-data) | -| /rosout | [rcl_interfaces/Log](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/Log.msg) | MCU node | System Logs | [Transient Local](overview.mdx#transient-local) | +| Topic | Message type | Publisher | Description | QoS | +| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- | :----------------------------------------------------- | :---------------------------------------------- | +| platform/emergency_stop | [std_msgs/Bool](https://github.com/ros2/common_interfaces/blob/humble/std_msgs/msg/Bool.msg) | MCU node | State of platform emergency stop | [Sensor Data](overview.mdx#sensor-data) | +| platform/mcu/_cmd_lights | [clearpath_platform_msgs/Lights](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Lights.msg) | Lighting command | Hidden topic used to send lighting commands to the MCU | [Sensor Data](overview.mdx#sensor-data) | +| platform/mcu/status | [clearpath_platform_msgs/Status](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Status.msg) | MCU node | MCU status | [Sensor Data](overview.mdx#sensor-data) | +| platform/mcu/status/power | [clearpath_platform_msgs/Power](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Power.msg) | MCU node | Robot Power status | [Sensor Data](overview.mdx#sensor-data) | +| platform/mcu/status/stop | [clearpath_platform_msgs/StopStatus](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/StopStatus.msg) | MCU node | Stop loop status | [Sensor Data](overview.mdx#sensor-data) | +| platform/motors/cmd_drive | [clearpath_platform_msgs/Drive](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Drive.msg) | Control node | Command velocities to individual wheels | [Sensor Data](overview.mdx#sensor-data) | +| platform/motors/feedback | [clearpath_platform_msgs/DriveFeedback](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/DriveFeedback.msg) | MCU node | Feedback from motor drive unit | [Sensor Data](overview.mdx#sensor-data) | +| platform/wifi_connected | [std_msgs/Bool](https://github.com/ros2/common_interfaces/blob/humble/std_msgs/msg/Bool.msg) | Wireless Watcher node | Wi-Fi connected status | [Sensor Data](overview.mdx#sensor-data) | +| /rosout | [rcl_interfaces/Log](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/Log.msg) | MCU node | System Logs | [Transient Local](overview.mdx#transient-local) | ## MCU services diff --git a/docs_versioned_docs/version-ros2humble/ros/api/platform_api.mdx b/docs_versioned_docs/version-ros2humble/ros/api/platform_api.mdx index a720e73a..bf539dd4 100644 --- a/docs_versioned_docs/version-ros2humble/ros/api/platform_api.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/api/platform_api.mdx @@ -14,6 +14,8 @@ toc_max_heading_level: 4 | diagnostics | [diagnostics_msgs/DiagnosticArray](https://github.com/ros2/common_interfaces/blob/humble/diagnostic_msgs/msg/DiagnosticArray.msg) | Various nodes | Diagnostic messages reported by various nodes | [System Default](overview.mdx#system-default) | | joy_teleop/cmd_vel | [geometry_msgs/Twist](https://github.com/ros2/common_interfaces/blob/humble/geometry_msgs/msg/Twist.msg) | Joy node | Velocity commands from joystick inputs | [System Default](overview.mdx#system-default) | | joy_teleop/joy | [sensor_msgs/Joy](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Joy.msg) | Joy node | Joystick input states | [System Default](overview.mdx#system-default) | +| platform/bms/state | [sensor_msgs/BatteryState](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/BatteryState.msg) | Battery node | System battery state | [Sensor Data](overview.mdx#sensor-data) | +| platform/cmd_lights | [clearpath_platform_msgs/Lights](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/msg/Lights.msg) | User | User lighting command request | [System Default](overview.mdx#system-default) | | platform/cmd_vel_unstamped | [geometry_msgs/Twist](https://github.com/ros2/common_interfaces/blob/humble/geometry_msgs/msg/Twist.msg) | Twist Mux node | Resulting velocity commands from twist mux | [System Default](overview.mdx#system-default) | | platform/dynamic_joint_states | [control_msgs/DynamicJointState](https://github.com/ros-controls/control_msgs/blob/humble/control_msgs/msg/DynamicJointState.msg) | Control node | Platform dynamic joint state | [System Default](overview.mdx#system-default) | | platform/emergency_stop | [std_msgs/Bool](https://github.com/ros2/common_interfaces/blob/humble/std_msgs/msg/Bool.msg) | MCU node | State of platform emergency stop | [Sensor Data](overview.mdx#sensor-data) | diff --git a/docs_versioned_docs/version-ros2humble/ros/config/yaml/links.mdx b/docs_versioned_docs/version-ros2humble/ros/config/yaml/links.mdx index 83a9dd42..4064df16 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/yaml/links.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/yaml/links.mdx @@ -33,9 +33,11 @@ A sphere of defined radius. ## Mesh -Include your custom mesh without creating a URDF of your own. +Include your custom mesh without creating a URDF of your own. You can either provide an absolute link +to the mesh file or if it is included in a ROS 2 package, then you can provide both the package name +and relative link to the install location within the package. -If you prefer to add a URDF instead, then you can link it directly through the `platform.extras` entry. +If you prefer to add a URDF instead, then you can link it directly through the [`platform.extras`](platform.mdx#extras) entry. ## Sample diff --git a/docs_versioned_docs/version-ros2humble/ros/config/yaml/overview.mdx b/docs_versioned_docs/version-ros2humble/ros/config/yaml/overview.mdx index 95a3b87c..33fcfe75 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/yaml/overview.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/yaml/overview.mdx @@ -102,7 +102,7 @@ platform: rpy: [0.0, 0.0, 0.0] enabled: true extras: - urdf: null + urdf: {} links: box: - name: user_bay_cover diff --git a/docs_versioned_docs/version-ros2humble/ros/config/yaml/platform.mdx b/docs_versioned_docs/version-ros2humble/ros/config/yaml/platform.mdx index 1431088f..8be6d66d 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/yaml/platform.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/yaml/platform.mdx @@ -20,6 +20,7 @@ import W200BulkheadDefault from "/docs_versioned_docs/version-ros2humble/compone import W200Generator from "/docs_versioned_docs/version-ros2humble/components/yaml/attachments/w200/generator.mdx"; Every robot platform has unique structures such as versatile sensor mounting solutions, wireless charging receivers, and waterproofing enclosures; we refer to these as **attachments**. +Each robot also supports specific batteries and battery configurations. ## Joystick Controller We support two types of controllers: @@ -30,7 +31,302 @@ We support two types of controllers: controller: ps4 # or logitech ``` +## Batteries + +Each robot platform can support different types of batteries, and in different configurations. The configuration is how +many batteries the robot has in series and parallel.A configuration of S2P1 indicates that there is one row of two batteries in series. S4P3 +indicates that there are 3 parallel rows of 4 batteries in series, for a total of 12 batteries. + +Some robots support "smart" batteries which have built in battery management system (BMS). If these batteries are specified, a corresponding driver node will +be launched as part of the platform service. For batteries without a BMS, the [battery state estimator](https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_diagnostics/clearpath_diagnostics/battery_state/battery_state_estimator) +node will be launched. This node will interpolate the state of charge of the robot from measured battery voltages. + +The battery state of the platform is available on the `platform/bms/state` topic. + +:::note + +For systems without a BMS, the state of charge should be treated as a rough estimate. This is especially true with Lead Acid batteries. + +::: + + +
A200 +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
BatteryChemistryNominal Voltage (V)Capacity (Ah)Configurations
ES20_12CLead Acid12.020.0S2P1
HE2613Lithium Ion25.912.8S1P3
S1P4
+ +

+
+ +
J100 +

+ + + + + + + + + + + + + + + + + + + + +
BatteryChemistryNominal Voltage (V)Capacity (Ah)Configurations
ES20_12CLithium Ion25.912.8S1P1
+ +

+
+ +
W200 +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BatteryChemistryNominal Voltage (V)Capacity (Ah)Configurations
U1_35Lead Acid12.035.0S4P3
NEC_ALM12V35Lithium Ion13.235.0S4P3
VALENCE_U24_12XPLithium Ion12.8118.0S4P1
VALENCE_U27_12XPLithium Ion12.8144.0S4P1
+ +

+
+ + + + + + ## Attachments + Each robot platform has its own unique set of attachments. To facilitate customization, any attachment from any robot platform can be added on any other robot platform. There is a default `parent` links at which these attachments are added; however, the `parent` link can be change to wherever you'd want the attachment to be placed. @@ -41,7 +337,7 @@ Each attachment requires two parameters. The `name` parameter that will define t Some attachment types will have the same `type` parameter across different platforms. In that case, if you'd like to use the attachment that belongs to a specific platform, you will need to prefix the `type` parameter with the platform that it belongs to. For example, `top_plate` would become `a200.top_plate`. If no prefix is set, then the platform defined in the `serial_number` will be used. -### Husky A200 +### Husky A200 {#attachments-a200} #### Bumper The A200 can have bumpers of a variable length. By setting the `extension` parameter, the bumper can be extended if required. @@ -80,46 +376,46 @@ The A200 has two types of sensor archs which are used to mount sensors from a va
-## Jackal J100 {#attachments-j100} +### Jackal J100 {#attachments-j100} -### Fenders +#### Fenders There are two types of fenders that can be equipped on the **J100** platform. -#### Default Fenders +##### Default Fenders The **default** fenders are the standard fenders that come with every **J100**. The front and rear fender entries are indepenent from each other such that they can be modified independently.
-#### Sensor Fenders +##### Sensor Fenders The **default** fenders are the standard fenders that come with every **J100**. The front and rear fender entries are indepenent from each other such that they can be modified independently.
-### Top Plate +#### Top Plate The Jackal only has one type of top plate. The ark enclosure. -#### Ark Enclosure +##### Ark Enclosure
-## Warthog W200 {#attachments-w200} +### Warthog W200 {#attachments-w200} -### Bulkhead +#### Bulkhead The Warthog bulkhead is used to cover payloads and to add a second surface to which to attach more payloads. -#### Default {#default-bulkhead} +##### Default {#default-bulkhead}
-#### Arm Mount {#arm-mount-bulkhead} +##### Arm Mount {#arm-mount-bulkhead}
-### Arm Mount +#### Arm Mount If instead of using the **bulkhead** to add an arm mount. We can add the arm mount independently using the following entry. @@ -131,15 +427,23 @@ If instead of using the **bulkhead** to add an arm mount. We can add the arm mou Despite all current customization options, we still would like our users to be able to add-in their existing custom URDF to the robot platform URDF and pass in and overwrite parameters to all platform nodes. Extras have the following entries: -- **urdf:** absolute path to URDF to add to robot platform URDF. +- **urdf:** + - **package:** name of the ROS 2 package that contains the extras URDF (optional). + - **path:** relative path within the package or absolute path to robot extras URDF - **ros_parameters:** in YAML to pass in parameters to platform nodes. This is useful to change parameters such as the robot's velocity and acceleration. ```yaml extras: - urdf: null # /absolute/path/to/urdf - ros_parameters: {} # node parameter + urdf: + package: package_name + path: relative/path/to/urdf/in/package.urdf.xacro # or can contain /absolute/path/to/urdf.urdf.xacro + ros_parameters: {} # node parameters, see below ``` +:::note +Remember, absolute paths start with `/` and relative paths do not. +::: + ### ROS Parameters A common use case is to set and update the parameters to the `platform_velocity_controller` node. These can be used to modify the linear and angular velocity and acceleratation. @@ -293,7 +597,7 @@ platform: rpy: [0.0, 0.0, 0.0] enabled: true extras: - urdf: null + urdf: {} ros_parameters: {} ```