diff --git a/docs/ros/api/mcu_api.mdx b/docs/ros/api/mcu_api.mdx index 972f55028..39962e84c 100644 --- a/docs/ros/api/mcu_api.mdx +++ b/docs/ros/api/mcu_api.mdx @@ -6,7 +6,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- - ## MCU topics | Topic | Message type | Publisher | Description | QoS | @@ -25,5 +24,3 @@ toc_max_heading_level: 4 | Service | Service type | Server | Description | QoS | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------ | :------------- | | platform/mcu/configure | [clearpath_platform_msgs/ConfigureMcu](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/srv/ConfigureMcu.srv) | MCU node | Configure MCU domain ID and namespace | System default | - - diff --git a/docs/ros/api/overview.mdx b/docs/ros/api/overview.mdx index f46bcbdf6..6bd30a5ed 100644 --- a/docs/ros/api/overview.mdx +++ b/docs/ros/api/overview.mdx @@ -6,31 +6,29 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- - The ROS 2 API is a standard naming scheme for ROS 2 topics and services. Every supported Clearpath robot uses this API, making it easy to use the robots interchangeably. - ## QoS Profiles {#qos-profiles} Topics and services in ROS 2 use Quality of Service (QoS) profiles to change communication policies. The QoS profile -of a topic or service has several policies such as history, depth, reliability, durability, and more. For more details on +of a topic or service has several policies such as history, depth, reliability, durability, and more. For more details on QoS settings, visit the [ROS 2 documentation](https://docs.ros.org/en/humble/Concepts/About-Quality-of-Service-Settings.html). For Clearpath platforms, the main policies that may change between different topics and services are reliability and durability. For reliability -there are two options: *Best Effort*, and *Reliable*. A *Best Effort* reliability suggests that an attempt will be made to publish -the data, but if the network is not robust then the data may be lost. On the other hand, *Reliable* guarantees that the data will be received. +there are two options: _Best Effort_, and _Reliable_. A _Best Effort_ reliability suggests that an attempt will be made to publish +the data, but if the network is not robust then the data may be lost. On the other hand, _Reliable_ guarantees that the data will be received. This may require that the data be sent multiple times. -The durability of a QoS profile can be either *Transient Local* or *Volatile*. *Transient Local* means that data for published messages will +The durability of a QoS profile can be either _Transient Local_ or _Volatile_. _Transient Local_ means that data for published messages will be stored by the publisher even after it has been published. A new subscriber will receive the data even if a lot of time has passed since it was originally published. -This durability is typically used for data that only needs to be published once, such as the robot description. The other durability policy is *Volatile* which does not -stored old messages. The messages are published and only active subscribers will receive the data. New subscribers will have to wait for the next message to be published. -Most topics will use a *Volatile* durability policy. +This durability is typically used for data that only needs to be published once, such as the robot description. The other durability policy is _Volatile_ which does not +store old messages. The messages are published and only active subscribers will receive the data. New subscribers will have to wait for the next message to be published. +Most topics will use a _Volatile_ durability policy. It is important to check for [QoS compatibility](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-compatibilities) when interacting with ROS 2. Mixing of QoS policies when publishing or subscribing to topics can lead to incompatibility. For example, subscribing to a Best Effort publisher with a Reliable subscriber -is not compatible and will result in no data being received on the subscriber. The easiest way to check the QoS profile of a topic is to use the ROS 2 command line interface (CLI). +is not compatible and will result in no data being received on the subscriber. The easiest way to check the QoS profile of a topic is to use the ROS 2 command line interface. ``` ros2 topic info /topic_name -v @@ -42,29 +40,29 @@ The following are some common QoS profiles used by Clearpath platforms. #### System Default -* **History**: *Keep Last* -* **Depth**: *10* -* **Reliability**: *Reliable* -* **Durability**: *Volatile* -* **Deadline**: *System Default* -* **Lifespan**: *System Default* -* **Liveliness**: *Automatic* -* **Lease Duration**: *System Default* +- **History**: _Keep Last_ +- **Depth**: _10_ +- **Reliability**: _Reliable_ +- **Durability**: _Volatile_ +- **Deadline**: _System Default_ +- **Lifespan**: _System Default_ +- **Liveliness**: _Automatic_ +- **Lease Duration**: _System Default_ -The *System Default* QoS profile is the most common profile used by most topics. +The _System Default_ QoS profile is the most common profile used by most topics. #### Sensor Data -* **History**: *Keep Last* -* **Depth**: *5* -* **Reliability**: *Best Effort* -* **Durability**: *Volatile* -* **Deadline**: *System Default* -* **Lifespan**: *System Default* -* **Liveliness**: *Automatic* -* **Lease Duration**: *System Default* +- **History**: _Keep Last_ +- **Depth**: _5_ +- **Reliability**: _Best Effort_ +- **Durability**: _Volatile_ +- **Deadline**: _System Default_ +- **Lifespan**: _System Default_ +- **Liveliness**: _Automatic_ +- **Lease Duration**: _System Default_ -The *Sensor Data* QoS Profile uses a *Best Effort* reliability to send the latest data +The _Sensor Data_ QoS Profile uses a _Best Effort_ reliability to send the latest data as soon as possible, without bothering to resend data that was not received. This is mostly used by the MCU and sensor drivers. @@ -74,25 +72,25 @@ Not all sensor drivers use this QoS profile. Always check the QoS profile before #### Transient Local -* **History**: *Keep Last* -* **Depth**: *10* -* **Reliability**: *Reliable* -* **Durability**: *Transient Local* -* **Deadline**: *System Default* -* **Lifespan**: *System Default* -* **Liveliness**: *Automatic* -* **Lease Duration**: *System Default* +- **History**: _Keep Last_ +- **Depth**: _10_ +- **Reliability**: _Reliable_ +- **Durability**: _Transient Local_ +- **Deadline**: _System Default_ +- **Lifespan**: _System Default_ +- **Liveliness**: _Automatic_ +- **Lease Duration**: _System Default_ -The *Transient Local* QoS Profile offers a *Transient Local* durability, and is typically used by topics that only +The _Transient Local_ QoS Profile offers a _Transient Local_ durability, and is typically used by topics that only want to send messages once. For Clearpath platforms, this includes the robot description topic and the `/rosout` topic which offers system logs. ## Namespacing -Namespacing is the method of adding a prefix to a robot's nodes and topics, to differentiate them from another robot that +Namespacing is the method of adding a prefix to a robot's nodes and topics; this helps differentiate them from another robot that may be on the same network. For example, every robot will have a `cmd_vel` topic for commanding velocity. If both robots used the same topic, then they would both drive when a message is published to that topic. By namespacing, we can remap the topic -to `robot1/cmd_vel` and `robot2/cmd_vel` for each respective robot. +to `robot1/cmd_vel` and `robot2/cmd_vel` for each respective robot. By default, the namespace of the robot will be obtained from the serial number of the robot. If your serial number is `cpr-a200-0001`, then your namespace -will be `a200_0001`. This can be overwritten in the [robot.yaml](../config/yaml) file. \ No newline at end of file +will be `a200_0001`. This can be overwritten in the [robot.yaml](../config/yaml) file. diff --git a/docs/ros/api/platform_api.mdx b/docs/ros/api/platform_api.mdx index fad5f0dbd..8c2349778 100644 --- a/docs/ros/api/platform_api.mdx +++ b/docs/ros/api/platform_api.mdx @@ -29,5 +29,3 @@ toc_max_heading_level: 4 | tf_static | [tf2_msgs/TFMessage](https://github.com/ros2/geometry2/blob/humble/tf2_msgs/msg/TFMessage.msg) | Various nodes | Static link transforms | [Transient Local](overview#transient-local) | | twist_marker_server/cmd_vel | [geometry_msgs/Twist](https://github.com/ros2/common_interfaces/blob/humble/geometry_msgs/msg/Twist.msg) | Twist Marker Server | Velocity commands from twist marker | [System Default](overview#system-default) | | /rosout | [rcl_interfaces/Log](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/Log.msg) | Various nodes | System Logs | [Transient Local](overview#transient-local) | - - diff --git a/docs/ros/api/sensors_api.mdx b/docs/ros/api/sensors_api.mdx index 82f9c17aa..f1d53ef6b 100644 --- a/docs/ros/api/sensors_api.mdx +++ b/docs/ros/api/sensors_api.mdx @@ -6,47 +6,45 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- - ## 2D Lidar topics -| Topic | Message type | Description | QoS | -| :------------------------------ | :----------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------- | -| platform/sensors/lidar2d_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) | +| Topic | Message type | Description | QoS | +| :------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------- | +| platform/sensors/lidar2d\_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) | ## 3D Lidar topics -| Topic | Message type | Description | QoS | -| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------------- | :---------------------------------------- | -| platform/sensors/lidar3d_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Lidar pointcloud data | [System Default](overview#system-default) | -| platform/sensors/lidar3d_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) | +| Topic | Message type | Description | QoS | +| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------------- | :---------------------------------------- | +| platform/sensors/lidar3d\_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Lidar pointcloud data | [System Default](overview#system-default) | +| platform/sensors/lidar3d\_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) | ## Camera topics | Topic | Message type | Description | QoS | | :------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------- | -| platform/sensors/camera_#/color/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw RGB image | [System Default](overview#system-default) | -| platform/sensors/camera_#/color/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) | -| platform/sensors/camera_#/depth/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw depth image | [System Default](overview#system-default) | -| platform/sensors/camera_#/depth/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) | -| platform/sensors/camera_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Pointcloud data | [System Default](overview#system-default) | -| platform/sensors/camera_#/imu | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | IMU data | [System Default](overview#system-default) | +| platform/sensors/camera\_#/color/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw RGB image | [System Default](overview#system-default) | +| platform/sensors/camera\_#/color/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) | +| platform/sensors/camera\_#/depth/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw depth image | [System Default](overview#system-default) | +| platform/sensors/camera\_#/depth/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) | +| platform/sensors/camera\_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Pointcloud data | [System Default](overview#system-default) | +| platform/sensors/camera\_#/imu | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | IMU data | [System Default](overview#system-default) | ## IMU topics -| Topic | Message type | Description | QoS | -| :------------------------------ | :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------- | -| platform/sensors/imu_#/data_raw | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Raw IMU orientation, angular velocity, and linear acceleration data | [Sensor Data](overview#sensor-data) | -| platform/sensors/imu_#/data | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Filtered IMU orientation, angular velocity, and linear acceleration data | [System Default](overview#system-default) | -| platform/sensors/imu_#/mag | [sensor_msgs/MagneticField](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/MagneticField.msg) | IMU magnetic field data | [System Default](overview#system-default) | +| Topic | Message type | Description | QoS | +| :------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------- | +| platform/sensors/imu\_#/data_raw | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Raw IMU orientation, angular velocity, and linear acceleration data | [Sensor Data](overview#sensor-data) | +| platform/sensors/imu\_#/data | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Filtered IMU orientation, angular velocity, and linear acceleration data | [System Default](overview#system-default) | +| platform/sensors/imu\_#/mag | [sensor_msgs/MagneticField](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/MagneticField.msg) | IMU magnetic field data | [System Default](overview#system-default) | ## GPS topics -| Topic | Message type | Description | QoS | -| :------------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------- | :---------------------------------------- | -| platform/sensors/gps_#/fix | [sensor_msgs/NavSatFix](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/NavSatFix.msg) | Navsat Fix information | [System Default](overview#system-default) | - +| Topic | Message type | Description | QoS | +| :-------------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------- | :---------------------------------------- | +| platform/sensors/gps\_#/fix | [sensor_msgs/NavSatFix](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/NavSatFix.msg) | Navsat Fix information | [System Default](overview#system-default) | :::note The '#' in the topic represents the index of the sensor. Indexing begins at 0 and will increment for each new sensor of that type that is added. Internal sensors such as IMU's will be indexed first. -::: \ No newline at end of file +::: diff --git a/docs/ros/config/generators.mdx b/docs/ros/config/generators.mdx index 6f8cc2e72..e0c6f4198 100644 --- a/docs/ros/config/generators.mdx +++ b/docs/ros/config/generators.mdx @@ -34,34 +34,33 @@ The launch generator creates ROS 2 [python launch files](https://docs.ros.org/en ### Parameter -The parameter generator creates `.yaml` ROS parameter files that are used by the corresponding launch file. The parameter file will use the default defined -parameter file for the specific node, and allows for users to overwrite any parameters using the robot YAML file. +The parameter generator creates `.yaml` ROS parameter files that are used by the corresponding launch file. Each node has default parameters set that the user can overwrite by setting them in the robot configuration YAML. -### Setup folder structure -Once all files are generated, the resulting setup folder structure under `/etc/clearpath/` will look like this: +### Setup folder structure -* **platform** - * **launch** - * *platform-service.launch.py* - * **config** - * *control.yaml* - * *imu_filter.yaml* - * *localization.yaml* - * *teleop_interactive_markers.yaml* - * *teleop_joy.yaml* - * *twist_mux.yaml* -* **sensors** - * **launch** - * *sensors-service.launch.py* - * *camera_0.launch.py* - * *camera_1.launch.py* - * ... - * **config** - * *camera_0.yaml* - * *camera_1.yaml* - * ... -* *robot.urdf.xacro* -* *robot.yaml* -* *setup.bash* +Once all files are generated, the resulting setup folder structure under `/etc/clearpath/` will look like this: +- **platform** + - **launch** + - _platform-service.launch.py_ + - **config** + - _control.yaml_ + - _imu_filter.yaml_ + - _localization.yaml_ + - _teleop_interactive_markers.yaml_ + - _teleop_joy.yaml_ + - _twist_mux.yaml_ +- **sensors** + - **launch** + - _sensors-service.launch.py_ + - _camera_0.launch.py_ + - _camera_1.launch.py_ + - ... + - **config** + - _camera_0.yaml_ + - _camera_1.yaml_ + - ... +- _robot.urdf.xacro_ +- _robot.yaml_ +- _setup.bash_ diff --git a/docs/ros/config/services.mdx b/docs/ros/config/services.mdx index bbc39387b..d2d0a8140 100644 --- a/docs/ros/config/services.mdx +++ b/docs/ros/config/services.mdx @@ -13,7 +13,6 @@ ran everything. For ROS 2 Humble, we have split this into three separate service [Sensors](https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_robot/services/clearpath-sensors.service), and [Robot](https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_robot/services/clearpath-robot.service). - ### Clearpath Platform The `clearpath-platform` service launches the `clearpath-platform.launch.py` file found under `/etc/clearpath/platform/launch/`. This will launch the nodes diff --git a/docs/ros/installation/controller.mdx b/docs/ros/installation/controller.mdx index 7c6414b01..58d0d0800 100644 --- a/docs/ros/installation/controller.mdx +++ b/docs/ros/installation/controller.mdx @@ -1,7 +1,7 @@ --- title: Joystick Controller Pairing sidebar_label: Joystick Controller -sidebar_position: 3 +sidebar_position: 4 toc_min_heading_level: 2 toc_max_heading_level: 4 --- @@ -10,7 +10,6 @@ Joystick controllers are used for teleoperation; they allow you to remotely driv or a simulated robot. The following instructions below detail how to pair different controllers to the robot's computer; however, these instructions can also be used to pair these controllers to your own computer. - ### PS4 Controller :::note @@ -24,12 +23,14 @@ To re-pair the PS4 controller or pair a new PS4 controller: ``` sudo apt-get install python-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. 3. Run the `ds4drv-pair` script to pair the controller to the computer. In terminal, run: ``` sudo ds4drv-pair ``` + This script will scan for nearby Bluetooth devices, and pair automatically to the controller. Alternatively, if ds4drv-pair fails to detect the controller, you can pair the controller using `bluetoothctl`: @@ -39,17 +40,20 @@ Alternatively, if ds4drv-pair fails to detect the controller, you can pair the c ``` sudo apt-get install bluez ``` + 2. Run the `bluetoothctl` command. In terminal, run: ``` sudo bluetoothctl ``` + 3. Use `bluetoothctl` to scan for nearby devices. In the bluetooth control application, run: ``` 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: diff --git a/docs/ros/installation/img/wifi_interface.jpg b/docs/ros/installation/img/wifi_interface.jpg new file mode 100644 index 000000000..c65f83974 Binary files /dev/null and b/docs/ros/installation/img/wifi_interface.jpg differ diff --git a/docs/ros/installation/remote_pc.mdx b/docs/ros/installation/remote_pc.mdx index 5ed88958f..2ce79e035 100644 --- a/docs/ros/installation/remote_pc.mdx +++ b/docs/ros/installation/remote_pc.mdx @@ -1,7 +1,7 @@ --- title: Remote Computer setup sidebar_label: Remote Computer -sidebar_position: 2 +sidebar_position: 3 toc_min_heading_level: 2 toc_max_heading_level: 4 --- @@ -43,6 +43,7 @@ For the remote computer we can create the `clearpath` folder in the home directo ``` mkdir ~/clearpath/ ``` + 2. **Copy the `robot.yaml` file into the setup folder** ``` @@ -65,4 +66,3 @@ Add the following line to your `~/.bashrc` file to automatically source the gene ``` source /etc/clearpath/setup.bash ``` - diff --git a/docs/ros/installation/robot.mdx b/docs/ros/installation/robot.mdx index 7a0e8fdce..45f72adfd 100644 --- a/docs/ros/installation/robot.mdx +++ b/docs/ros/installation/robot.mdx @@ -1,7 +1,7 @@ --- -title: Robot installation +title: Robot Installation sidebar_label: Robot -sidebar_position: 1 +sidebar_position: 2 toc_min_heading_level: 2 toc_max_heading_level: 4 --- @@ -12,9 +12,74 @@ ROS 2 Humble uses [Ubuntu 22.04](https://releases.ubuntu.com/jammy/) as its Tier it is highly recommended to use Ubuntu 22.04. For the robot computer, Ubuntu 22.04 Server should be installed. The server version of the OS will not install a graphical user interface (GUI). -### Networking +### First login -Once the operating system is installed, the robot computer needs to be connected to the internet. TODO. +Connect the robot's computer to a monitor using an HDMI or DisplayPort cable. Then, connect a USB keyboard. Power the robot on and wait for the Ubuntu login prompt to show up. On a fresh install, the default username and password are both `ubuntu`. You will be prompted to change your password. + +Once logged in, create the `administrator` user: + +``` +sudo adduser --ingroup administrator administrator +``` + +Follow the prompts, then add `administrator` to the `sudo` group: + +``` +sudo usermod -aG sudo administrator +``` + +### Internet Connection + +#### Wi-Fi + +To configure Wi-Fi, first log in to the robot's computer. This can be done by connecting the computer to a monitor using an HDMI or DisplayPort cable, and connecting a USB keyboard. Power the robot on and wait for the Ubuntu login prompt to show up. On a fresh install, the default username and password are both `ubuntu`. You will be prompted to change your password. + +Once logged in, find the name of your Wi-Fi interface by calling `ip a`. Wi-Fi interface names begin with `wl`. + +
+
+ +
+
+ +Next, create the file `/etc/netplan/60-wireless.yaml`, and paste the following contents: + +``` +network: + wifis: + # Replace WIRELESS_INTERFACE with the name of the wireless network device, e.g. wlan0 or wlp3s0 + # Fill in the SSID and PASSWORD fields as appropriate. The password may be included as plain-text + # or as a password hash. To generate the hashed password, run + # echo -n 'WIFI_PASSWORD' | iconv -t UTF-16LE | openssl md4 -binary | xxd -p + # If you have multiple wireless cards you may include a block for each device. + # For more options, see https://netplan.io/reference/ + WIRELESS_INTERFACE: + optional: true + access-points: + SSID_GOES_HERE: + password: PASSWORD_GOES_HERE + dhcp4: true + dhcp4-overrides: + send-hostname: true +``` + +Replace `WIRELESS_INTERFACE` with the name of your Wi-Fi interface, `SSID_GOES_HERE` with your Wi-Fi SSID, and `PASSWORD_GOES_HERE` with your Wi-Fi password. + +Save the file and call `sudo netplan apply` to apply the changes. Check `ip a` again to make sure that an IP address has been assigned to your Wi-Fi interface. + +#### Ethernet + +The robot's computer can also be connected to a dhcp network over ethernet. Connect an ethernet cable to the built-in ethernet port on the robot's computer and check that an IP has been assigned with `ip a`. + + +:::note + +You should now be able to SSH into the robot by calling `ssh administrator@` from a remote computer. + +::: ### ROS 2 Humble @@ -32,8 +97,7 @@ Configure Ubuntu's APT package manager to add the package server: wget https://packages.clearpathrobotics.com/public.key -O - | sudo apt-key add - ``` -**2. Add the debian sources for the repository** - +**2. Add the debian sources for the repository** ``` sudo sh -c 'echo "deb https://packages.clearpathrobotics.com/stable/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/clearpath-latest.list' @@ -41,11 +105,14 @@ sudo sh -c 'echo "deb https://packages.clearpathrobotics.com/stable/ubuntu $(lsb **3. Update your computer’s package cache** - ``` sudo apt-get update ``` +### Network Configuration + +Once the Clearpath package server is set up, follow the [Clearpath Computer Setup](../networking/computer_setup) instructions to configure the network interfaces. + ### Clearpath Robot metapackage Once the Clearpath package server has been added, the [Clearpath Robot](https://github.com/clearpathrobotics/clearpath_robot) metapackage can be installed. @@ -102,7 +169,7 @@ sudo apt-get install ros-humble-jackal-firmware **2. Place the Jackal MCU into bootloader mode** -Switch the *PWR_MODE* switch from *NORM* to *ALT*. If the robot is on, press the *M_RST* button. Otherwise, turn the +Switch the _PWR_MODE_ switch from _NORM_ to _ALT_. If the robot is on, press the _M_RST_ button. Otherwise, turn the robot on with the power button. **3. Flash the firmware** @@ -110,6 +177,7 @@ robot on with the power button. ``` jackal_firmware_flash.sh ``` + Flashing progress will be indicated by the flash script. Wait for the firmware to finish flashing. :::caution @@ -154,4 +222,4 @@ Add the following line to your `~/.bashrc` file to automatically source the gene ``` source /etc/clearpath/setup.bash -``` \ No newline at end of file +``` diff --git a/docs/ros/installation/upgrading.mdx b/docs/ros/installation/upgrading.mdx new file mode 100644 index 000000000..ba57b771c --- /dev/null +++ b/docs/ros/installation/upgrading.mdx @@ -0,0 +1,111 @@ +--- +title: Upgrading to Humble +sidebar_label: Upgrading to Humble +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Users who are installing ROS 2 Humble onto a new robot computer can skip to [Robot Installation](./robot). + +::: + +:::note + +Check the [list of supported platforms](../#supported-platforms) to make sure that your robot is currently supported on ROS 2 Humble. + +::: + +ROS 2 Humble is the first ROS distribution that runs on Ubuntu 22.04. As a result, any robots running ROS 1 or +ROS 2 Foxy will have upgrade their operating system. It is highly recommended to back up any important files on the robot +before proceeding, especially for highly customized robots. + +:::caution + +It is the user’s responsibility to ensure that any essential files are properly backed-up before upgrading their robot. + +::: + +### Saving a hard drive image + +As a fail-safe, please make an image of your robot's hard drive. You should always be able to restore this image if you need to revert back to your previous configuration. The easiest approach may be to either connect a removable (USB or similar) hard drive to the robot's computer, or to unplug the robot's hard drive and insert it into a computer or workstation. You can then use a tool such as [CloneZilla](https://clonezilla.org/) or `dd` to write a backup image of your robot's hard drive onto another hard drive. Alternatively, you can simply replace the robot computer's hard drive, reserving the drive and installing a new one to use with Humble. + +### Saving important files + +There are several places in the filesystem you should specifically look for customizations for your robot: + +| **Location** | **Description** | +| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/etc/network/interfaces` or `/etc/netplan/*` | Your robot may have a custom network configuration in this file. | +| `/etc/ros/*/*-core.d/*.launch` | Will contain `base.launch` and `description.launch`, may contain custom launch files for your robot configuration. Replaced by `ros.d` in newer versions. | +| `/etc/ros/*/ros.d/*.launch ` | Will contain `base.launch` and `description.launch`, may contain custom launch files for your robot configuration. Replaces `*-core.d` in newer versions. | +| `/etc/ros/setup.bash` | May contain environment variables for your configuration. | +| `~/catkin_ws/` or `~/colcon_ws/` | ROS workspace that may contain custom ROS packages. | + +Please save the files listed above and use them as a reference during Humble configuration. + +### Backup Software (ROS 1 only) + +Clearpath Robotics provides a package containing several shell scripts to help you back up, upgrade, and/or restore your ROS 1 robot’s important data. You can use these scripts by downloading the `robot-backup` repository by running the following command on your computer: + +``` +git clone https://github.com/clearpathrobotics/robot-backup +``` + +You will need to install dependencies to be able to use these scripts. The instructions for installing dependencies can be found in the `README.md` file of the repository, or run the following command on your computer: + +``` +sudo apt-get install sshpass sudo apt-get install rsync +``` + +#### Running the backup script + +Ensure that the robot is turned on and that you can SSH into it from your computer. Then run the following from your computer: + +``` +cd robot-backup +bash backup.sh +``` + +For example, if your robot’s IP address is 192.168.1.103, you would run something like: + +``` +bash backup.sh melodic-final-backup 192.168.1.103 +``` + +This will produce a backup file called `melodic-final-backup.tar.gz`. Keep this file for when you need to access your backed-up data. + +By default all Clearpath robots use the username `administrator` and the password `clearpath`. The backup.sh script will use these credentials by default, but you can override them easily. + +For example, if your robot’s username and password have been set to `my_robot_username` and `my_robot_password` you should run: + +``` +bash backup.sh melodic-final-backup my_robot_username@192.168.1.103 my_robot_password +``` + +#### Backed up contents + +The backup script will copy the following data: + +- Home Folder: `~/` +- `udev` Rules: `/etc/udev/rules.d` +- Network Setup: - `/etc/network/interfaces` - `/etc/netplan` - `/etc/hostname` - `/etc/hosts` +- IP Tables: `/etc/iptables` +- Bringup Files: - `/etc/ros/setup.bash` - `/etc/ros/$ROSDISTRO/ros.d` - `/usr/sbin/*start` - `/usr/sbin/*stop` +- `rosdep` sources: `/etc/ros/rosdep` +- `rc.local` File: `/etc/rc.local` +- `pip` packages +- `systemd` configuration: `/etc/systemd/system` +- `apt` sources: `/etc/apt/sources.list.d` +- `apt` packages +- User Permission Groups + +#### Backing up non-standard data + +The `backup.sh` script assumes that your robot is in a roughly-standard configuration; it uses a single user account and no files within `/opt/ros/melodic`have been modified. + +If this is not the case, it is the responsibility of the user to ensure that any modified files and files in other users’ home folders is backed up correctly. + +A common example of this might be if you have created customized URDF files to be loaded via environment variables (e.g. `JACKAL_URDF_EXTRAS`) and have stored them outside any of the folders specified above, you must back these up yourself; `backup.sh` will not do this for you. diff --git a/docs/ros/networking/computer_setup.mdx b/docs/ros/networking/computer_setup.mdx new file mode 100644 index 000000000..e6c0c630d --- /dev/null +++ b/docs/ros/networking/computer_setup.mdx @@ -0,0 +1,39 @@ +--- +title: Clearpath Computer Setup +sidebar_position: 2 +--- + +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](../installation/robot.mdx#clearpath-package-server). + +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 +``` + +### Standard Clearpath Bridge + +The default networking configuration for a robot's computer is to bridge all ethernet interfaces and assign the computer the IP address `192.168.131.1`. See [Network IP Addresses](./network_ip_addresses.mdx) for a detailed list of IP ranges. + +To configure the default bridge, run `clearpath-computer-setup` and navigate to **Netplan Setup** -> **Pre-set Configurations**. Select **Standard Clearpath Bridge** and generate the configuration by following the instructions. Then, return to the **Netplan Setup** menu and select **Apply Configuration Changes**. +This will create a `/etc/netplan/50-clearpath-standard.yaml` file and apply the changes to `netplan`. + +Once the network settings have been applied, call `ip a` to check that the network bridge has been created, and that the computer has been assigned the `192.168.131.1` IP address. + +### Custom Networking + +The `clearpath-computer-setup` tool can also be used to set up custom network interfaces. Navigate to the **Netplan Setup** menu and use the bridge, ethernet, or Wi-Fi setup menus to add configurations. Once you are done configuring, return to the **Netplan Setup** menu and select **Write Configuration YAML**. You will be prompted for a file name. The file should be placed under `/etc/netplan/` to take effect, and the naming convention is a two digit number followed by a unique name. For example, `/etc/netplan/50-home-wifi.yaml`. + +:::note + +Netplan will read files under `/etc/netplan/` in alphanumeric order. Files beginning in `01` will be read first, and `99` will be read last. +If two files define the same configuration, the configuration read last will be used. Otherwise, netplan will amalgamate all files under `/etc/netplan/` to create the netplan configuration. + +::: diff --git a/docs/ros/networking/ntp.mdx b/docs/ros/networking/ntp.mdx index 3fcf1f55d..16ecb3033 100644 --- a/docs/ros/networking/ntp.mdx +++ b/docs/ros/networking/ntp.mdx @@ -119,57 +119,3 @@ rtcsync # one second, but only in the first three clock updates. makestep 1 3 ``` - -### Work-around for no RTC - -Most computers have a realtme clock (RTC) that keeps time while the computer is otherwise powered-off. This clock has -a replaceable battery, referred to either as the RTC backup battery or CMOS battery. If you are using a computer that -does not have an RTC backup battery, or does not have a RTC at all, you may see unusual behaviour. Typically the -clock will reset to a default date (often January 1, 1970) when the computer loses power. The clock will then jump -ahead to the present as soon as a connection with an NTP server is established. - -Under most circumstances this is fine, but some ROS nodes will behave incorrectly if the clock suddenly jumps ahead by -50+ years. To mitigate this, if you are configuring a computer that does not have a reliable RTC, modify the file -`/lib/systemd/system/ros.service` to add an `ExecStartPre` command to the service: - -``` -[Service] -ExecStart=/usr/sbin/ros-start -ExecStartPre=/usr/sbin/ros-wait-clock -``` - -Then create the file `/usr/sbin/ros-wait-clock` by running - -``` -sudo nano /usr/sbin/ros-wait-clock -``` - -and entering the following: - -```bash -#!/bin/bash - -hw_time="$(hwclock -r -f /dev/rtc1)" - -# wait at most 15s -for i in {1..15}; -do - if [[ "$hw_time" == 19* ]]; - then - echo "HW clock says it's ${hw_time}. Waiting for clock-sync..." - sleep 1 - hw_time="$(hwclock -r -f /dev/rtc1)" - else - echo "HW clock says it's now ${hw_time}. Clock appears synchronized with reality" - exit 0 - fi -done - -echo "Wait for clock sync timed out. Moving ahead with possibly bad clock." -``` - -Save the file, close the editor, and make the file executable by running - -``` -sudo chmod +x /usr/sbin/ros-wait-clock -``` diff --git a/docs/ros/networking/networking.mdx b/docs/ros/networking/overview.mdx similarity index 76% rename from docs/ros/networking/networking.mdx rename to docs/ros/networking/overview.mdx index adc6ca62e..1efe52e10 100644 --- a/docs/ros/networking/networking.mdx +++ b/docs/ros/networking/overview.mdx @@ -1,19 +1,10 @@ --- -title: Networking -sidebar_position: 3 +title: Overview +sidebar_position: 1 --- :::note -For details on setting up wired and wireless networking connections to your Clearpath -robot, refer to the robot-specific tutorials, such as the -[Husky ROS1 tutorial](../../robots/outdoor_robots/husky/tutorials_husky/tutorials_husky_ros1#husky-networking) or the -[Husky ROS2 tutorial](../../robots/outdoor_robots/husky/tutorials_husky/tutorials_husky_ros2#husky-networking). - -::: - -:::note - Contact our Support team at support@clearpathrobotics.com if you have any questions. ::: diff --git a/docs/ros/ros.mdx b/docs/ros/ros.mdx index c417395d5..203ccdfb2 100644 --- a/docs/ros/ros.mdx +++ b/docs/ros/ros.mdx @@ -9,20 +9,18 @@ robot, we have opted to create common `clearpath` packages which are used by all 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, our platforms are now more customizable, more modular, and more unified. - ## Terminology {#terminology} -***Clearpath Platform***: The *platform* refers to the vehicle that makes up the base of the robot. The platform may be referred to by +**_Clearpath Platform_**: The _platform_ refers to the vehicle that makes up the base of the robot. The platform may be referred to by the platform code to indicate the revision. -***Clearpath Robot***: The *robot* refers to the entire robotic system, including the platform, sensors, and additional accessories. +**_Clearpath Robot_**: The _robot_ refers to the entire robotic system, including the platform, sensors, and additional accessories. -***Clearpath Config***: The *config* refers to the `robot.yaml` configuration file that defines the Clearpath robot. +**_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). 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} @@ -85,6 +83,13 @@ by Clearpath which are used by all supported Clearpath platforms. ## 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. + +::: +
@@ -94,45 +99,70 @@ by Clearpath which are used by all supported Clearpath platforms. - + - + - + - + - + - + - + - + - + - + - + +
Sensor
Hokuyo UST10 + Hokuyo UST10-LX + 2D Lidar Source or Debianurg_node + urg_node +
Intel Realsense D435(i) + Intel Realsense D435 + Depth Camera Source or Debianrealsense-ros + realsense-ros +
MicroStrain GX5 + MicroStrain 3DM-GX5 + IMU Source or Debianmicrostrain_intertial + microstrain_intertial +
Sick LMS1xx + SICK LMS-111 + 2D Lidar Source or DebianLMS1xx + LMS1xx +
SwiftNav Duro + Swift Navigation Duro + GPS Sourceduro_gps_driver + duro_gps_driver +
Velodyne VLP16Velodyne Puck 3D Lidar Source or Debian velodyne
+ +:::note + +Debian drivers are automatically installed on robots as part of the [Clearpath Robot Metapackage](../ros/installation/robot.mdx#clearpath-robot-metapackage). - \ No newline at end of file +::: diff --git a/docs/ros/tutorials/driving.mdx b/docs/ros/tutorials/driving.mdx index 8ea358248..8c73d2ea7 100644 --- a/docs/ros/tutorials/driving.mdx +++ b/docs/ros/tutorials/driving.mdx @@ -19,7 +19,6 @@ Make sure your controller is paired to the robot PC. Visit the [controller pairi With the [robot services](../installation/robot#robot-services) running, turn on your controller. Press and hold either **L1** or **R1**, and use the left joystick to publish a linear velocity and yaw command. The **L1** button will drive the robot at slow speeds, while **R1** will drive the robot at fast speeds. -
Localization in simulation
-
\ No newline at end of file + diff --git a/docs/ros/tutorials/navigation_demos/nav2.mdx b/docs/ros/tutorials/navigation_demos/nav2.mdx index 23024110f..b3360475e 100644 --- a/docs/ros/tutorials/navigation_demos/nav2.mdx +++ b/docs/ros/tutorials/navigation_demos/nav2.mdx @@ -31,6 +31,7 @@ Click on the orange play button in the bottom left corner to start the simulatio ``` ros2 launch clearpath_viz view_navigation.launch.py namespace:=j100_0001 ``` + **4. In another terminal, launch localization** ``` @@ -50,7 +51,6 @@ ros2 launch clearpath_nav2_demos localization.launch.py setup_path:=$HOME/clearp ros2 launch clearpath_nav2_demos nav2.launch.py setup_path:=$HOME/clearpath/ use_sim_time:=true ``` - **6. Set the initial pose of the robot** Use the **2D Pose Estimate** tool in RViz to set the initial pose of the robot. @@ -62,7 +62,7 @@ Use the **Nav2 Goal** tool in RViz to set a navigation goal pose.
Navigation in simulation
diff --git a/docs/ros/tutorials/navigation_demos/overview.mdx b/docs/ros/tutorials/navigation_demos/overview.mdx index 9d61ba99c..530f8cd62 100644 --- a/docs/ros/tutorials/navigation_demos/overview.mdx +++ b/docs/ros/tutorials/navigation_demos/overview.mdx @@ -19,4 +19,4 @@ sudo apt-get install ros-humble-clearpath-nav2-demos :::tip The navigation demos can be run on either the robot computer, or a remote computer. -::: \ No newline at end of file +::: diff --git a/docs/ros/tutorials/navigation_demos/slam.mdx b/docs/ros/tutorials/navigation_demos/slam.mdx index 537b2b735..8cb3aed29 100644 --- a/docs/ros/tutorials/navigation_demos/slam.mdx +++ b/docs/ros/tutorials/navigation_demos/slam.mdx @@ -30,6 +30,7 @@ Click on the orange play button in the bottom left corner to start the simulatio ``` ros2 launch clearpath_viz view_navigation.launch.py namespace:=j100_0001 ``` + **4. In another terminal, launch SLAM** ``` @@ -41,7 +42,7 @@ ros2 launch clearpath_nav2_demos slam.launch.py setup_path:=$HOME/clearpath/ use
SLAM in simulation
@@ -53,4 +54,4 @@ ros2 launch clearpath_nav2_demos slam.launch.py setup_path:=$HOME/clearpath/ use ``` ros2 run nav2_map_server map_saver_cli -f "map_name" \ --ros-args -p map_subscribe_transient_local:=true -r __ns:=/j100_0001 -``` \ No newline at end of file +``` diff --git a/docs/ros/tutorials/simulator/install.mdx b/docs/ros/tutorials/simulator/install.mdx index 6919af5b2..55742f023 100644 --- a/docs/ros/tutorials/simulator/install.mdx +++ b/docs/ros/tutorials/simulator/install.mdx @@ -62,4 +62,3 @@ colcon build --symlink-install :::note Make sure to add the workspace to your `robot.yaml` file. TODO: Add link to robot yaml documentation ::: - diff --git a/docs/ros/tutorials/simulator/overview.mdx b/docs/ros/tutorials/simulator/overview.mdx index ba142d610..6ddf72480 100644 --- a/docs/ros/tutorials/simulator/overview.mdx +++ b/docs/ros/tutorials/simulator/overview.mdx @@ -13,7 +13,7 @@ The Clearpath simulator can be used to iterate on robot configurations, test con
Clearpath Simulator
@@ -22,4 +22,4 @@ The Clearpath simulator can be used to iterate on robot configurations, test con ### Bridging Gazebo to ROS 2 -Gazebo uses its own transport layer consisting of nodes and messages similar to ROS 2. A [ROS 2 bridge node](https://github.com/gazebosim/ros_gz/tree/humble/ros_gz_bridge) is required to bridge Gazebo data to ROS 2, and vice versa. By leveraging the [generators](../config/generators), we can generate the required bridges when the simulator is launched. As a result, the simulator can support all of the same configurations that a physical robot supports. \ No newline at end of file +Gazebo uses its own transport layer consisting of nodes and messages similar to ROS 2. A [ROS 2 bridge node](https://github.com/gazebosim/ros_gz/tree/humble/ros_gz_bridge) is required to bridge Gazebo data to ROS 2, and vice versa. By leveraging the [generators](../config/generators), we can generate the required bridges when the simulator is launched. As a result, the simulator can support all of the same configurations that a physical robot supports. diff --git a/docs/ros/tutorials/simulator/simulate.mdx b/docs/ros/tutorials/simulator/simulate.mdx index 3f3cf389b..ae6ae3629 100644 --- a/docs/ros/tutorials/simulator/simulate.mdx +++ b/docs/ros/tutorials/simulator/simulate.mdx @@ -20,7 +20,6 @@ ros2 launch clearpath_gz simulation.launch.py The launch file will run all of the necessary [generators](../config/generators) to generate launch and parameter files for the simulation before launching Gazebo and spawning the robot. These will be placed under the setup path (defaults to `$HOME/clearpath/`). - ### Launch arguments If you are using a different setup path, use the `setup_path` launch argument to change it: @@ -58,7 +57,7 @@ The simulated robot can be driven in the same ways as the physical robot. Take a
Driving Jackal in simulation
diff --git a/docusaurus.config.js b/docusaurus.config.js index 5917d1721..3ad4496cb 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -11,7 +11,7 @@ const config = { title: "Clearpath Robotics Documentation", url: "https://docs.clearpathrobotics.com", baseUrl: "/", - onBrokenLinks: "warn", + onBrokenLinks: "throw", onBrokenMarkdownLinks: "warn", favicon: "img/website_images/favicon.ico",