Merge pull request #188 from clearpathrobotics/development

Merging development to production

README.md

@@ -333,12 +333,11 @@ The list below are not strict rules, but are considered good practice to keep im
 
 ## Links and Imports
 
-All links to, or imports of versioned elements (images, markdown files etc.) must be referred to using relative links (`./img/image-name.png`). These versioned pages will be moved together and ensures that the correct version is used.
+All links to, or imports of versioned elements (images, markdown files etc.) must be referred to using relative links (`img/image-name.png` or `../../robots/add-ons/pacs.mdx`), including the file extension. These versioned pages will be moved together and ensures that the correct version is used. Including the file extension ensures that the next page will be located based on the file location not the generated links. This method is much more robust and should be followed whenever possible.
 
-All links to, or imports of unversioned static elements must be referred to using absolute paths (`/static/img/image-name.png`). This allows these assets to be found irrelevant of the location of the particular page.
+All links to, or imports of unversioned static elements must be referred to using absolute paths (`/static/img/image-name.png`). This allows these assets to be found irrelevant of the location of the particular page. This link should be the path to the file including the file extension, even when it is an md or mdx file.
 
-Links to headings must not include an extra slash between the name of the page and the name of the heading. Doing this will result in broken links. For example: `../ros/#supported-platforms` is incorrect. It will initially work but any subsequent relative link that the user clicks
-will appear to be broken. Instead, it must be `../ros#supported-platforms`.
+Links to headings must not include an extra slash between the name of the page and the name of the heading. Doing this can result in broken links. For example: `../ros/#supported-platforms` is incorrect. It will initially work but any relative links that rely on the url (instead of file path) that the user clicks will appear to be broken. Instead, it must be `../ros#supported-platforms`. This is irrelevant when the relative links are based on file path.
 
 ## SolidWorks image exports
 

docs/components/_tutorials_link.mdx

@@ -9,22 +9,22 @@ These tutorials assume that you are comfortable working with [ROS](https://docs.
 
 You can view all topics that are active using `ros2 topic list`.
 
-For a general list of topics and descriptions see the [Clearpath API](../../../ros/api/platform_api)
+For a general list of topics and descriptions see the [Clearpath API](../../../ros/api/platform_api.mdx)
 
 ## Software Setup
 
-- [Robot Software](../../../ros/installation/robot)
-- [Remote Computer](../../../ros/installation/remote_pc)
-- [PS4 Joystick Controller (if applicable)](../../../ros/installation/controller)
+- [Robot Software](../../../ros/installation/robot.mdx)
+- [Remote Computer](../../../ros/installation/remote_pc.mdx)
+- [PS4 Joystick Controller (if applicable)](../../../ros/installation/controller.mdx)
 
 ## Using your Robot
 
 The following tutorials are recommended to get to know your robot:
 
-- [Driving your Robot](../../../ros/tutorials/driving)
-- [Simulating your Robot](../../../ros/tutorials/simulator/overview)
-- [Navigating](../../../ros/tutorials/navigation_demos/overview)
+- [Driving your Robot](../../../ros/tutorials/driving.mdx)
+- [Simulating your Robot](../../../ros/tutorials/simulator/overview.mdx)
+- [Navigating](../../../ros/tutorials/navigation_demos/overview.mdx)
 
 ## Advanced Topics
 
-- [Configuring Network Bridge](../../../ros/networking/computer_setup)
+- [Configuring Network Bridge](../../../ros/networking/computer_setup.mdx)

docs/robots/accessories/add-ons/outdoornav_starter_kit.mdx

@@ -47,7 +47,7 @@ On Jackal, mount the kit using the standard 120 X 120 hole pattern at the front
 On Husky, mount the kit on the leading edge of the top plate. Where a PACS-compatible top plate exists, the kit can be mounted directly.
 When using an older Husky without a PACS-compatible top plate, it will be necessary to drill your own holes.
 
-Refer also to the [OutdoorNav Starter Kit Hardware Checklist](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist).
+Refer also to the [OutdoorNav Starter Kit Hardware Checklist](/docs_outdoornav_user_manual/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx).
 
 ---
 
@@ -82,12 +82,12 @@ Adapter cables can be used for robot-specific integrations.
 ### Data Integration
 
 The OutdoorNav Starter Kit includes a 1 m IP67 Ethernet cable for data connectivity between the base platform to the Starter Kit.
-Refer to [OutdoorNav Platform Computer Checklist](/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist)
+Refer to [OutdoorNav Platform Computer Checklist](/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist.mdx)
 for addititional details on data connectivity.
 
 ---
 
 ## Software Integration
 
 The required software for the OutdoorNav Starter Kit is pre-installed. However, the base platform computer must be configured as outlined
-in the [OutdoorNav Platform Computer Checklist](/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist).
+in the [OutdoorNav Platform Computer Checklist](/docs_outdoornav_user_manual/integration_requirements/platform_computer_checklist.mdx).

docs/ros/config/live.mdx

@@ -8,7 +8,7 @@ toc_max_heading_level: 4
 
 Users familiar with Clearpath's robots, know we provide desktop packages that facilitate the viewing of robot models in RViz without needing to have a real robot. In ROS 2, the `view_model.launch.py` node will check and update the model and display the new changes in RViz.
 
-This functionality requires a desktop manager to be installed; in other words, these commands will not work on robot computers since these run Ubuntu 22.04 server rather than desktop.
+This functionality requires a desktop manager to be installed; in other words, these commands will not work on standard robot computers since these run Ubuntu 22.04 server rather than desktop.
 
 # Installation
 
@@ -21,21 +21,33 @@ sudo apt install ros-humble-clearpath-desktop ros-humble-clearpath-config-live
 # Setup
 
 Before running the node, we will need to setup the working directory.
-First, create the directory `/etc/clearpath`.
-Then, copy your `robot.yaml` to `/etc/clearpath/robot.yaml`.
+
+Our standard working directory is: `/etc/clearpath`. However, you can choose whatever directory you'd like. We will refer to this directory as the **setup_path**.
+
+Make sure to put your robot configuration file, `robot.yaml`, into the **setup_path**.
+
+> The configuration file must be named `robot.yaml`.
+
+You can get a sample `robot.yaml` file from the [Clearpath Configuration repository](https://github.com/clearpathrobotics/clearpath_config/).
 
 # Run the Node
 
-Running `view_model.launch.py` will generate the URDF of the robot from the `/etc/clearpath/robot.yaml` and then start RViz.
+Running `view_model.launch.py` will generate the URDF of the robot from the `robot.yaml` and then start RViz.
 
-It will then monitor the `/etc/clearpath/robot.yaml` for changes. Whenever changes are detected, the URDF will be regenerated and the RViz model will be updated.
+It will then monitor the `robot.yaml` for changes. Whenever changes are detected, the URDF will be regenerated and the RViz model will be updated.
 
 To run the node:
 
 ```bash
-ros2 launch clearpath_viz view_model.launch.py
+ros2 launch clearpath_viz view_model.launch.py setup_path:=SETUP_PATH
 ```
 
+> Replace `SETUP_PATH` with the path to the directory where the `robot.yaml` is located.
+
+> Do not include `~` in the `SETUP_PATH`, use `$HOME` instead.
+
+> Make sure that `SETUP_PATH` ends with `/`.
+
 # Example
 
 Starting off with the default A200 Husky YAML, we switch the top plate, add the sensor arch, a fath pivot mount, and finally a RealSense. Every time we want changes to take effect, we save the file. If after saving no changes take place, then it's an indication that these were invalid.

docs/ros/config/services.mdx

@@ -27,6 +27,6 @@ sensors defined in the robot YAML. This service can be stopped or started withou
 ### Clearpath Robot
 
 The `clearpath-robot` service is the "parent" service of `clearpath-platform` and `clearpath-sensors`. If it is restarted, then both the platform and sensors services
-will restart. This service will run all of the [generators](generators) in the `PreExec` step, before allowing the two dependent services to start. While
+will restart. This service will run all of the [generators](generators.mdx) in the `PreExec` step, before allowing the two dependent services to start. While
 the platform and sensors services are running, the robot service will periodically check for changes in the `robot.yaml` file. If a change is detected
 the service restarts, re-generating all files and restarting the platform and sensors services.

docs/ros/config/yaml.mdx

@@ -39,6 +39,8 @@ Additionally, there are two other, required parameters:
 
 Below is the sample **Husky A200** robot YAML of the robot displayed above. In the following sections, we will reference each and every component of this sample file, and show how to robot looks as we build it up.
 
+Find more samples `robot.yaml` configuration files in the [Clearpath Configuration repository](https://github.com/clearpathrobotics/clearpath_config/).
+
 You can also skip to each section to get an explanation of each part of the sample configuration:
 
 1. [**Serial Number Sample**](#serial-sample)
@@ -66,6 +68,7 @@ system:
     namespace: a200_0000
     domain_id: 0
     rmw_implementation: rmw_fastrtps_cpp
+    workspaces: []
 platform:
   controller: ps4
   attachments:
@@ -140,7 +143,7 @@ sensors:
   gps: []
   imu: []
   lidar2d:
-    - model: hokuyo_ust10
+    - model: hokuyo_ust
       urdf_enabled: true
       launch_enabled: true
       parent: bracket_0_mount
@@ -215,6 +218,7 @@ The **ros2** sections is necessary to setup the ROS 2 middleware.
 - **namespace** specified will be appended as a prefix to all sensor topics to prevent topic cloberring when multiple robots are on the same network and domain ID.
 - **domain_id** specifies the ROS 2 domain ID to use.
 - **rmw_implementation** specifies the ROS 2 middleware to use. **Currently, it only supports `rmw_fastrtps_cpp`.**
+- **workspaces** indicates a list of workspaces that need to be sourced by specifying the path to the setup.py
 
 ### Sample {#system-sample}
 
@@ -240,6 +244,7 @@ system:
     namespace: a200_0000
     domain_id: 0
     rmw_implementation: rmw_fastrtps_cpp
+    workspaces: []
 ```
 
 At this point, with just the **serial_number** and **system** defined: our robot is just the standard **Husky A200** platform, and looks like this:
@@ -261,9 +266,20 @@ At this point, with just the **serial_number** and **system** defined: our robot
 
 Every robot platform has unique structures such as versatile sensor mounting solutions, wireless charging receivers, and waterproofing enclosures; we refer to these as attachments.
 
+#### Joystick Controller
+
+We support two types of controllers:
+
+- **ps4**: standard Playstation4 controller.
+- **logitech**: Logitech F710
+
+```yaml
+controller: ps4 # or logitech
+```
+
 #### Attachments
 
-There are three types of attachments:
+There are four types of attachments:
 
 1. **bumpers** modify the front face and rear face of the robot platform.
 2. **fenders** modify the area above the wheels on the front and rear of the platform.
@@ -364,15 +380,15 @@ platform:
   extras:
     ros_parameters:
       platform_velocity_controller:
-        platform_velocity_controller.wheel_radius": 0.1651
-        platform_velocity_controller.linear.x.max_velocity": 1.0
-        platform_velocity_controller.linear.x.min_velocity": -1.0
-        platform_velocity_controller.linear.x.max_acceleration": 3.0
-        platform_velocity_controller.linear.x.min_acceleration": -3.0
-        platform_velocity_controller.angular.z.max_velocity": 2.0
-        platform_velocity_controller.angular.z.min_velocity": -2.0
-        platform_velocity_controller.angular.z.max_acceleration": 6.0
-        platform_velocity_controller.angular.z.min_acceleration": -6.0
+        wheel_radius": 0.1651
+        linear.x.max_velocity": 1.0
+        linear.x.min_velocity": -1.0
+        linear.x.max_acceleration": 3.0
+        linear.x.min_acceleration": -3.0
+        angular.z.max_velocity": 2.0
+        angular.z.min_velocity": -2.0
+        angular.z.max_acceleration": 6.0
+        angular.z.min_acceleration": -6.0
 ```
 
 **J100 Jackal Controller Defaults:**
@@ -382,15 +398,15 @@ platform:
   extras:
     ros_parameters:
       platform_velocity_controller:
-        platform_velocity_controller.wheel_radius": 0.098
-        platform_velocity_controller.linear.x.max_velocity": 2.0
-        platform_velocity_controller.linear.x.min_velocity": -2.0
-        platform_velocity_controller.linear.x.max_acceleration": 20.0
-        platform_velocity_controller.linear.x.min_acceleration": -20.0
-        platform_velocity_controller.angular.z.max_velocity": 4.0
-        platform_velocity_controller.angular.z.min_velocity": -4.0
-        platform_velocity_controller.angular.z.max_acceleration": 25.0
-        platform_velocity_controller.angular.z.min_acceleration": -25.0
+        wheel_radius": 0.098
+        linear.x.max_velocity": 2.0
+        linear.x.min_velocity": -2.0
+        linear.x.max_acceleration": 20.0
+        linear.x.min_acceleration": -20.0
+        angular.z.max_velocity": 4.0
+        angular.z.min_velocity": -4.0
+        angular.z.max_acceleration": 25.0
+        angular.z.min_acceleration": -25.0
 ```
 
 #### Sample {#platform-sample}
@@ -923,11 +939,11 @@ imu:
 
 ### LiDAR 2D
 
-- **_hokuyo_ust10:_**
+- **_hokuyo_ust:_**
 
 ```yaml
 lidar2d:
-  - model: hokuyo_ust10
+  - model: hokuyo_ust
     urdf_enabled: true
     launch_enabled: true
     parent: base_link
@@ -1030,11 +1046,11 @@ lidar3d:
   </figure>
 </center>
 
-Next, we will add a `hokuyo_ust10` to the **bracket** we added earlier. Since that is the first **bracket**, then it's mounting location will be: `bracket_0_mount`; setting the parent link of the sensor, we get:
+Next, we will add a `hokuyo_ust` to the **bracket** we added earlier. Since that is the first **bracket**, then it's mounting location will be: `bracket_0_mount`; setting the parent link of the sensor, we get:
 
 ```yaml
 lidar2d:
-  - model: hokuyo_ust10
+  - model: hokuyo_ust
     urdf_enabled: true
     launch_enabled: true
     parent: bracket_0_mount
@@ -1115,7 +1131,7 @@ sensors:
   gps: []
   imu: []
   lidar2d:
-    - model: hokuyo_ust10
+    - model: hokuyo_ust
       urdf_enabled: true
       launch_enabled: true
       parent: bracket_0_mount

docs/ros/installation/controller.mdx

@@ -13,18 +13,21 @@ these instructions can also be used to pair these controllers to your own comput
 ### PS4 Controller
 
 :::note
+
 If your robot comes with a PS4 controller, it will be paired already. Simply turn on the robot and turn on the controller.
+
 :::
 
 To re-pair the PS4 controller or pair a new PS4 controller:
 
-1. Install the python-ds4drv package if it is not installed already. In terminal, run:
+1. Install the python3-ds4drv package if it is not installed already. In terminal, run:
 
 ```
-sudo apt-get install python-ds4drv
+sudo apt-get install python3-ds4drv
 ```
 
-2. Put the controller in pairing mode. Press and hold the PS and Share buttons on your controller until the LED begins rapidly flashing white.
+2. Put the controller in pairing mode. Press and hold the PS and Share buttons on your controller until
+   the LED begins rapidly flashing white.
 3. Run the `ds4drv-pair` script to pair the controller to the computer. In terminal, run:
 
 ```
@@ -54,8 +57,10 @@ agent on
 scan on
 ```
 
-4. Put the controller in pairing mode. Press and hold the PS and Share buttons on your controller until the LED begins rapidly flashing white.
-5. The bluetooth scan will display the MAC addresses of nearby devices. Determine which MAC address corresponds to the controller and copy it. In the bluetooth control application, run:
+4. Put the controller in pairing mode. Press and hold the PS and Share buttons on your controller until
+   the LED begins rapidly flashing white.
+5. The bluetooth scan will display the MAC addresses of nearby devices. Determine which MAC address
+   corresponds to the controller and copy it. In the bluetooth control application, run:
 
 ```
 scan off
@@ -67,5 +72,7 @@ connect <MAC Address>
 The controller should now be paired.
 
 :::note
-Make sure to set the correct controller type in your [robot.yaml](../config/yaml) file
+
+Make sure to set the correct controller type in your [robot.yaml](../config/yaml) file. See, [Joystick Controller](../config/yaml.mdx#joystick-controller) setup in the Clearpath Configuration.
+
 :::

docs/ros/ros.mdx

@@ -6,7 +6,7 @@ sidebar_position: 1
 
 For [ROS 2 Humble](https://docs.ros.org/en/humble/index.html) and beyond, the software structure of Clearpath robots has changed significantly. Rather than having individual sets of packages for each
 robot, we have opted to create common `clearpath` packages which are used by all supported platforms. Additionally, we are moving away from using environment variables
-to customize the robot, and instead using a YAML configuration file to describe the robot. We have also defined a [ROS 2 API](api/overview) common to all of our supported platforms. As a result,
+to customize the robot, and instead using a YAML configuration file to describe the robot. We have also defined a [ROS 2 API](api/overview.mdx) common to all of our supported platforms. As a result,
 our platforms are now more customizable, more modular, and more unified.
 
 ## Terminology {#terminology}
@@ -18,7 +18,7 @@ the platform code to indicate the revision.
 
 **_Clearpath Config_**: The _config_ refers to the `robot.yaml` configuration file that defines the Clearpath robot.
 
-**_Clearpath API_**: The _API_ refers to the [ROS 2 application programming interface](api/overview). This is a set of ROS 2 topics and services defined
+**_Clearpath API_**: The _API_ refers to the [ROS 2 application programming interface](api/overview.mdx). This is a set of ROS 2 topics and services defined
 by Clearpath which are used by all supported Clearpath platforms.
 
 ## Supported Platforms {#supported-platforms}
@@ -115,7 +115,7 @@ sensors that have been validated by Clearpath.
     <a href="../robots/accessories/sensors/lidar_2d/hokuyo_ust10_lx">Hokuyo UST10-LX</a>
   </td>
   <td>2D Lidar</td>
-  <td>Source or Debian</td>
+  <td>Debian</td>
   <td>
     <a href="https://github.com/ros-drivers/urg_node">urg_node</a>
   </td>
@@ -128,7 +128,7 @@ sensors that have been validated by Clearpath.
     <a href="../robots/accessories/sensors/cameras/realsense_d435">Intel Realsense D435</a>
   </td>
   <td>Depth Camera</td>
-  <td>Source or Debian</td>
+  <td>Debian</td>
   <td>
     <a href="https://github.com/IntelRealSense/realsense-ros/tree/ros2-development">realsense-ros</a>
   </td>
@@ -141,7 +141,7 @@ sensors that have been validated by Clearpath.
     <a href="../robots/accessories/sensors/imu/microstrain_3dm_gx5">MicroStrain 3DM-GX5</a>
   </td>
   <td>IMU</td>
-  <td>Source or Debian</td>
+  <td>Debian</td>
   <td>
     <a href="https://github.com/LORD-MicroStrain/microstrain_inertial/tree/ros2">microstrain_intertial</a>
   </td>
@@ -154,7 +154,7 @@ sensors that have been validated by Clearpath.
     <a href="../robots/accessories/sensors/lidar_2d/sick_lms111">SICK LMS-111</a>
   </td>
   <td>2D Lidar</td>
-  <td>Source or Debian</td>
+  <td>Debian</td>
   <td>
     <a href="https://github.com/clearpathrobotics/LMS1xx">LMS1xx</a>
   </td>
@@ -176,7 +176,7 @@ sensors that have been validated by Clearpath.
   <tr>
     <td><a href="../robots/accessories/sensors/lidar_3d/velodyne_puck">Velodyne Puck</a></td>
     <td>3D Lidar</td>
-    <td>Source or Debian</td>
+    <td>Debian</td>
     <td><a href="https://github.com/ros-drivers/velodyne/tree/ros2">velodyne</a></td>
   </tr>
 </table>