Skip to content

GitLab

Home · Changes

Page history
Update home authored by Wouter Jansen's avatar Wouter Jansen
Show whitespace changes
Inline Side-by-side
home.md
View page @ 69e96954
# Husky Usage Guide
user guide of the Clearpath Husky robot platform available to Cosys-Lab members.
Please ask a lab member to use the Husky to make sure it is available and in good condition.
User guide of the Clearpath Husky robot platform available to Cosys-Lab members.
First, please ask a lab member for permission to use the Husky to make sure it is available and in good condition.
This guide was updated last on 2023-02-23.
![husky.jpg](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/husky.jpg)
## Table of content
- [The basics](#the-basics)
- [Layout](#layout)
- [Status panel](#status-panel)
......@@ -47,7 +45,6 @@ This guide was updated last on 2023-02-23.
## The basics
### Layout
![layout.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/layout.png)
![layout_back.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/layout_back.png)
......@@ -91,24 +88,22 @@ The silver button at the top of the Status Panel is used to power the Husky on a
![panel.jpg](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/panel.jpg)
status panel lights will show a brief test pattern. The `COMM` status light will turn red, as the PC is not yet communicating with Husky.
When booting, status panel lights will show a brief test pattern. The `COMM` status light will turn red, as the PC is not yet communicating with Husky.
The `STOP` status light will be red if the Stop button is pressed. If the Stop button is not pressed, press it and verify that the `STOP` light illuminates. Leave the platform in stop mode until it is successfully receiving commands, indicated by the `COMM` status light turning green or yellow. If a computer was purchased with Husky, it will be setup to interface automatically upon startup; 60-90 seconds after booting up, `COMM` status light will change from red to green (or yellow, depending on the stop mode status). This indicates that ROS is up on the computer and has established communications with the Husky base.
The `STOP` status light will be red if the Stop button is pressed. If the Stop button is not pressed, press it and verify that the `STOP` light illuminates. Leave the platform in stop mode until it is successfully receiving commands, indicated by the `COMM` status light turning green or yellow. A minute after booting up, the `COMM` status light will change from red to green (or yellow, depending on the stop mode status). This indicates that ROS is up on the computer and has established communications with the Husky base.
### Using the controller
To teleoperate Husky, first release the motion stop. Then, referring to the following image of the Logitech Controller, press one of the buttons (either slow or fast mode) and use the left thumbstick to drive Husky.
To teleoperate Husky, first release the motion stop. Then, referring to the following image of the Logitech Controller, press one of the buttons (either slow or fast mode) and use the left thumbstick to drive the Husky.
![controller.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/controller.png)
### Orientation reference
The reference frame used by all Clearpath Robotics ground robots is based on ISO 8855, and is shown in the figure below. Husky's front is shown. When commanded with a positive translational velocity (forward), wheels travel in the positive X-direction. The direction of the axes differs from those used for roll, pitch, and yaw in aircraft, and care should be taken to ensure that data is interpreted correctly.
### Orientation reference
The reference frame used by the Husky and all base sensor frames is based on ISO 8855, and is shown in the figure below. Husky's front is shown. When commanded with a positive translational velocity (forward), wheels travel in the positive X-direction. The direction of the axes differs from those used for roll, pitch, and yaw in aircraft, and care should be taken to ensure that data is interpreted correctly.
![orientation.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/orientation.png)
### Specifications
| Specification | Measurement |
|--------------------------------|--------------------------------------------------------------------------|
| Dimension, Length | 990 mm |
......@@ -137,7 +132,6 @@ The reference frame used by all Clearpath Robotics ground robots is based on ISO
| Environmental | note waterproof |
### Safety emergency-stop and lockout
![safety.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/safety.png)
The motion-stop function allows a person in the physical vicinity of the robot to halt its motion and prevent re-initiation of motion. Power supply to Husky's motor drivers is enabled by a normally-open relay, which is closed in series with the stop switch. This motion-stop system is intended for use in emergency situations. The motion stop system should not be used as the means of controlling robot motion during regular operation.
......@@ -147,19 +141,18 @@ When in stop mode, the status panel stop light will illuminate red and Husky wil
This "Stop" function can be asserted by pressing the red stop actuator present at the rear of the Husky, opposite the status panel, as shown in the following figure. The motion-stop function can be reset by twisting the depressed actuator until it returns to an extended position. There is no second "start" action required to reset the stop function. The robot may begin moving again immediately after the stop actuator has returned to its extended position.
### Battery charging
The battery shipped with Husky A200 may be charged outside the robot or while still inside of Husky. If charging while installed, you will need to open the access door to the battery area, and disconnect the battery from the MCU board. From there:
**Be careful with the blue cable!! It is very fragile and can be easily damaged. Pull and push on it from the blue plastic connector, not from the cable!**
The battery shipped with Husky may be charged outside the robot or while still inside of Husky. If charging while installed, you will need to open the access door to the battery area, and disconnect the battery from the MCU board. From there:
1. Connect the DC output cable from the charger to the battery terminal connector. Does not matter which side, just connect black to black and red to red.
2. Plug the charger power cord into the charger and then into a wall receptacle.
3. The LED light on the charger will illuminate red.
4. When battery is fully charged, the LED light will turn green.
5. Unplug the charger from the wall and then disconnect it from the battery.
6. Connect battery terminal connector back to the MCU board. Black to black, red to red.
The connections to the charger or the MCU board respectively should look as followed when done correctly:
![charging_connection.jpg](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/charging_connection.jpg)
![battery_connection.jpg](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/battery_connection.jpg)
......@@ -172,21 +165,19 @@ The battery charger shipped with Clearpath Robotics's lead-acid battery-powered
## Network Setup
### Network basics
The Husky A200 is shipped with a pre-configured network interface. It is hosting a DHCP server(Which will assign IP addresses to any devices that connect to the network) and has a Wi-Fi access point.
The Husky is shipped with a pre-configured network interface. It is hosting a DHCP server (which will assign IP addresses to any devices that connect to the network) and has a Wi-Fi access point.
It uses the `192.168.131.x/24` subnet and the Husky itself is available on `192.168.131.1`. The username is `administrator` and the password is `clearpath`.
The Wi-Fi SSID is `HuskyLAN` and has password `Husky123`.
To connect to the Husky's network you can either connect to the Wi-Fi access point or connect an Ethernet cable to the available ethernet switch in the hatch.
To connect to the Husky's network you can either connect to the Wi-Fi access point or connect an ethernet cable to the available ethernet switch in the hatch.
![ethernet_switch.jpg](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/ethernet_switch.jpg)
### Internet access
By default, the Husky has no internet access. On the USB-hub a secondary Wi-Fi adapter is plugged in. You can connect this one to an internet-able network.
You can use the command `sudo nmtui` from the terminal to connect. If it does not work, try rebooting as this often helps.
By default, the Husky has no internet access. On the USB-hub a secondary Wi-Fi adapter is plugged in. You can connect this one to an internet network with the command `sudo nmtui` from the terminal. If it does not work, try rebooting as this often helps.
If using the University network (`uawifi`) with your personal account,
you must first update the file `/etc/NetworkManager/system-connections/uawifi`
If using the University network (`uawifi`) to get internet, you need to log in with your personal account.
You must first update the file `/etc/NetworkManager/system-connections/uawifi`
to add your credentials in the following lines:
```bash
anonymous-identity=username@ad.ua.ac.be
......@@ -194,6 +185,7 @@ eap=peap;
identity=username@ad.ua.ac.be
password=password
```
Then you can connect with the command `sudo nmtui` and select the `uawifi` network. Don't forget to remove your credentials after you are done!
To share the internet access to any connected devices on the internal Husky network (to for example any connected RTIS sensor or other device) you must add a few rules to the firewall with the following commands:
```bash
......@@ -202,7 +194,7 @@ sudo iptables -A FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
sudo iptables -t nat -F POSTROUTING
sudo iptables -t nat -A POSTROUTING -o wlx74da38c9a498 -j MASQUERADE
```
Here `wlx74da38c9a498` is the name of the USB Wi-Fi adapter that is connected to the internet and `enp3s0` is the name of the ethernet interface that is connected to the internal network.
In these commands `wlx74da38c9a498` is the name of the USB Wi-Fi adapter that is connected to the internet and `enp3s0` is the name of the ethernet interface that is connected to the internal network.
On the client side you will need to do the following command to correctly enable the passthrough internet:
```bash
sudo ip route add default via 192.168.131.1
......@@ -213,52 +205,51 @@ By default, a USB drive is mounted on the Husky to the USB-hub. This drive can b
To automatically mount this drive, you can use the bash command `mountUsb` from a terminal connected to the Husky. This will mount the drive to `/media/huskyusb`.
## Sensors
There are under normal circumstances several sensors available on the Husky by default:
1. 3 eRTIS sensors
There are under normal circumstances several sensors available on the Husky:
1. Three eRTIS sensors
2. Ouster OS0-128 LiDAR (with IMU)
3. Intel Realsense d435i camera
Each subsection will go more in depth into using them. Custom sensors can be added but need to be configured manually.
### eRTIS
The RTIS sensors are connected to the Husky via a custom device called the SYNC-box. This powers the devices and provides them with synchronized pulse to execute measurements.
The devices are also connected to the internal network of the Husky and can be accessed via SSH. The default static IP addresses of the devices are:
The RTIS sensors are connected to the Husky via a custom device called the Sync-box. This powers the devices and provides them with synchronized trigger to execute measurements.
The eRTIS sensors are also connected to the internal network of the Husky and can be accessed via SSH. The default static IP addresses of the devices are:
1. eRTIS-TX2NX-0004 : `192.168.131.154`
2. eRTIS-TX2NX-0005 : `192.168.131.155`
3. eRTIS-TX2NX-0006 : `192.168.131.156`
These are configured in `/etc/dhcp/dhcpd.conf` on the Husky.
These are rather default configured RTIS devices so for more information, see the [eRTIS guide](https://cosysgit.uantwerpen.be/rtis-software/ertissoftwareusageguide).
These IPs are configured in `/etc/dhcp/dhcpd.conf` on the Husky.
These eRTIS sensors are no different from any other eRTIS sensor, so for more information see the [eRTIS guide](https://cosysgit.uantwerpen.be/rtis-software/ertissoftwareusageguide/-/wikis/home).
![rtis_sync.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/rtis_sync.png)
The RTIS devices can be used individually with libraries such as [RTIS Dev](https://cosysgit.uantwerpen.be/rtis-software/rtisdev/-/wikis/home).
But ideally they are used together using the [RTIS Network](https://cosysgit.uantwerpen.be/rtis-software/rtisnetwork/-/wikis/home) software, which is already configured completely on the Husky.
The RTIS Server can be automatically started using the bash command `startServer` on a terminal connected to the Husky. This will start it in the opened terminal.
At that point the web application of RTIS Network is available on `192.168.131.1:5000` on the entire Husky network. For more information on the usage of RTIS Network, read the [wiki page]((https://cosysgit.uantwerpen.be/rtis-software/rtisnetwork/-/wikis/home)).
However, when combining multiple sensors they should be used with the [RTIS Network](https://cosysgit.uantwerpen.be/rtis-software/rtisnetwork/-/wikis/home) software, which is already configured on the Husky.
The RTIS Server can be automatically started using the bash command `startServer` on a terminal connected to the Husky. This will start the script it in the opened terminal.
At that point the web interface of RTIS Network is available on `192.168.131.1:5000` on the entire Husky network and is the best way to access the configuration and start measurements.
For more information on the usage of RTIS Network, read the [wiki page](https://cosysgit.uantwerpen.be/rtis-software/rtisnetwork/-/wikis/home)).
To start RTIS Control (the CLI interface to the RTIS Network) you can use the command `startControl` on a terminal connected to the Husky. This will start it in the opened terminal.
### Ouster OS0-128 LiDAR
Lastly, to start RTIS Control (the CLI interface to the RTIS Network) you can use the command `startControl` on a terminal connected to the Husky. This will start it in the opened terminal.
### Ouster OS0-128 LiDAR
The LiDAR is connected with its custom connector to the power/network box. It starts up automatically on boot up.
The LIDAR is most easy to use with ROS so see that chapter on how to operate it. For more information on this sensor, please see the official Ouster documentation.
The serial number of the OS0-128 LiDAR is `os-992037000184`.
### Intel Realsense d435i camera
The Realsense camera is connected with a USB-C cable to the USB-hub inside the Husky bay. It startsup automatically on boot up.
The camera is most easy to use with ROS so see that chapter on how to operate it. For more information on this sensor, please see the official Intel documentation.
The serial number of the Realsense camera is `912112070257`.
## Using ROS
Robot Operating System (ROS) is an extensible framework for controlling and working with robotic systems. We recommend using ROS with the Husky. If this is your first time using ROS, look up some basic ROS tutorials first to get used to how it works.
It is also recommended to install ROS on your own computer so that you can easily access the ROS network on the Husky and see the data visually in for example RVIZ.
It is also recommended to install ROS on your own computer so that you can easily access the ROS network on the Husky and see the data visually in for example RViz.
The ROS network is automatically started on boot up. The ROS Master is hosted on `192.168.131.1:13111`.
### Default nodes
You can use `rosnode list` to see all the nodes running by default on a Husky computer. The most important nodes are summarized in the following table.
You can use `rosnode list` to see all the nodes running by default on the Husky. The most important nodes are summarized in the following table.
| Node | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `/husky_node` | Provides control and communication between the Husky platform and ROS. Accepts velocity commands and provides system feedback on `/status` |
......@@ -282,8 +273,8 @@ You can view all topics that are active using `rostopic list`. The most importan
The `/twist_mux` node is responsible for taking in velocity commands from multiple sources and prioritizing them.
it will publish these to the `//husky_velocity_controller/cmd_vel` which is the final value send to the Husky motor controller through the ROS node `/husky_node`.
See the table below for the default motion topics used by twist mux and their priority.
You can add custom motion topics and configure the priorities in the `/opt/ros/kinetic/share/husky_control/config/twist_mux.yaml` file on the Husky.
it also takes into account the `/estop` topic listed in the table above as absolute priority.
Do note that it also takes into account the `/estop` topic listed in the table above as absolute priority.
See the section [Navigation with ROS](#navigation-with-ros) for more information on how to use `twist_mux`.
| Motion Topics | twist_mux Priority | Description |
|--------------------------------|--------------------|--------------------------------------------------------------|
......@@ -303,64 +294,66 @@ Husky publishes odometry information on the `odometry/filtered` topic, as `nav_m
| `odometry/filtered` | `ekf_localization_node` |
### Diagnostics topics
Husky provides hardware and software system diagnostics on the ROS standard `/diagnostics` topic.
The best way to view these messages is using the [rqt_runtime_monitor](http://wiki.ros.org/rqt_runtime_monitor) plugin. Run the `rqt` command, and select `Plugins→Robot Tools→Runtime Monitor` from the top menu.
The same information is also published as a `husky_msgs\HuskyStatus` message on the `status` topic.
### Custom workspace
All the custom ROS packages that are installed on the Husky are located in the `/home/husky/catkin_ws/src` folder. This is the default workspace for ROS.
You can extend with your own packages here but please always build the packages in release with :
All the custom ROS packages that are installed on the Husky are located in the `/home/administator/catkin_ws/src` folder. This is the default workspace for ROS on the Husky.
You can extend it with your own packages but please always build the packages in release mode (to avoid issues with current packages) with:
```bash
catkin_make --cmake-args -DCMAKE_BUILD_TYPE=Release
```
### ROS Husky packages
If you want to use ROS on your own computer and have the Husky packages available, so you can interact better with the husky,
If you want to use ROS on your own computer and have the Husky packages available to interact better with the Husky remotely,
you can install them with:
```bash
sudo apt-get install ros-kinetic-husky-desktop
sudo apt-get install ros-$ROS-DISTRO-husky-desktop
```
You can then use the following command to see the robot in RVIZ:
With these packages installed, you can then use the following command to see the robot in RVIZ:
```bash
roslaunch husky_viz view_robot.launch
```
### Navigation with ROS
There are two ways to navigate the Husky with ROS outside using the controller.
There are two ways to navigate the Husky with ROS:
- Using an RViz instance (like started with `roslaunch husky_viz view_robot.launch`). If you select the Interact option in the top toolbar, an interactive marker will appear around the Husky and can be used to control speed.
- The [`rqt_robot_steering`](http://wiki.ros.org/rqt_robot_steering) plugin. Run the `rqt` command, and select `Plugins→Robot Tools→Robot Steering` from the top menu.
Husky uses `twist_mux` to mix four separate `geometry_msgs\Twist` control channels into the `husky_velocity_controller/cmd_vel` topic. See [Motion Topics](#motion-topics) for the priority levels for the different inputs.
Additional velocity channels can be defined in `husky_control/config/twist_mux.yaml`, or can be piped into the lowest-priority `cmd_vel` topic.
The Husky uses `twist_mux` to mix four separate `geometry_msgs\Twist` control channels into the `husky_velocity_controller/cmd_vel` topic. See [Motion Topics](#motion-topics) for the priority levels for the different inputs.
Additional velocity channels can be defined in `/opt/ros/kinetic/share/husky_control/config/twist_mux.yaml`. But to keep it simple you can pipe your velocity commands into the lowest-priority `cmd_vel` topic.
### Publishing eRTIS data
Once the [RTIS Server](#eRTIS) is running and the clients are good to go, you can start the installed [RTIS ROS](https://cosysgit.uantwerpen.be/rtis-software/rtisros/-/wikis/home) node to start publishing the sensor data to ROS.
Make sure to correctly configure the launch file so that it matches the configuration of the RTIS Network. See the [wiki page](https://cosysgit.uantwerpen.be/rtis-software/rtisros/-/wikis/home) for more information.
Once the [RTIS Server](#ertis) is running and the clients are good to go, you can start the installed [RTIS ROS](https://cosysgit.uantwerpen.be/rtis-software/rtisros/-/wikis/home) node to start publishing the sensor data to ROS.
Make sure to correctly configure the launch file so that it matches the configuration of the RTIS Network (3D or 2D processing!). See the [wiki page](https://cosysgit.uantwerpen.be/rtis-software/rtisros/-/wikis/home) for more information.
You can automatically start the `rtis_publisher.launch` launch file of the `rtisros` node with the bash command `startRtisros` in a terminal connected to the Husky.
The `rtisros` package is installed in `/home/administator/catkin_ws/src`.
### Publishing Ouster OS0-128 LiDAR data
To start publishing the LiDAR data to ROS, you can use the installed `ouster_ros` package. See the official documentation [here](https://github.com/ouster-lidar/ouster-ros) for more information on the configuration.
You can automatically start the `sensor.launch` launch file of the `ouster_ros` node with the bash command `startOuster` in a terminal connected to the Husky.
The `ouster_ros` package is installed in `/home/administator/catkin_ws/src`.\
### Publishing Intel Realsense d435i camera data
To start publishing the data of the Realsense camera to Ros, you can use the installed `realsense2_camera` package. See the official documentation [here](https://github.com/IntelRealSense/realsense-ros/tree/ros1-legacy) for more information.
You can automatically start the `rs_camera.launch` launch file of the `realsense2_camera` node with the bash command `startRealsense` in a terminal connected to the Husky.
The `ouster_ros` package is installed in `/opt/ros/kinetic/share`.
### Transformation tree
By default, the entire Husky robot and all default sensors have a static transformation tree. The sensors are linked to the `top_plate_link` frame of the Husky. You can see it in the [frames.png](frames.png) file in this repository.
Do note that this needs to be updated if the sensors are moved in any way. The static transformations of the default sensors are configured as follows:
- RTIS: Configured through RTIS Network with RTIS ROS automatically. See their guides to see how to set the sensor positions in for example the web interface.
By default, the entire Husky robot and all default sensors have a static transformation tree. The sensors are linked to the `top_plate_link` frame of the Husky. You can see this default layout in the [frames.png](https://cosysgit.uantwerpen.be/wjansen/husky-usage-guide/-/raw/main/frames.png) image in this repository.
Do note that this needs to be changed if the sensors are moved in any way. The static transformations of the default sensors are configured as follows:
- RTIS: Configured through RTIS Network with RTIS ROS automatically. See their [guide](#ertis) to see how to set the sensor positions in for example the web interface.
- Ouster OS0-128 LiDAR: Configured through `sensor.launch` launch file of the `ouster_ros` package found in the `/home/husky/catkin_ws/src/ouster_ros/launch` folder.
- Intel Realsense d435i camera: Configured through `rs_camera.launch` launch file of the `realsense2_camera` package found in the `/opt/ros/kinetic/share/realsense2_camera/launch` folder.
## Configuration
### Software versions
The internal computer of the Husky is running the old Ubuntu 16.04.7, take this into account when installing custom software. Some versions you SHOULD NOT change:
The internal computer of the Husky is running Ubuntu 16.04.7. Take this into account when installing custom software. Some software you SHOULD NOT change or update without asking a lab member:
- Ubuntu: 16.04.7
- Python: 2.7.12
- Python3: 3.6.13
......@@ -373,20 +366,20 @@ The `br0` bridge connects the ethernet and Wi-Fi networks on respectively `enp3s
The DHCP leases can be found in `/var/lib/dhcp/dhcpd.leases`
To assign a static IP:
1. get hardware address (MAC of ethernet port) of the device
2. add to `/etc/dhcp/dhcpd.conf` a host:
1. get hardware address (MAC of ethernet port) of the device.
2. add the new host to `/etc/dhcp/dhcpd.conf`:
```bash
host yourhostname {
hardware ethernet 48:b0:2d:3b:30:08;
fixed-address 192.168.131.160;
}
```
3. restart DHCP server: `sudo systemctl restart isc-dhcp-server.service`
4. check DHCP server for errors: `sudo systemctl status isc-dhcp-server.service`
5. reboot to be sure
3. restart the DHCP server: `sudo systemctl restart isc-dhcp-server.service`.
4. check the DHCP server for errors: `sudo systemctl status isc-dhcp-server.service`.
5. reboot to be sure.
### Bash alias commands
the commands like `startServer` and `startOuster` are defined and can be configured in `~/.bash_aliases`.
the commands like `startServer` and `startOuster` are defined in `~/.bash_aliases`.
## Other resources
- Official Husky guide: https://docs.clearpathrobotics.com/docs/robots/outdoor_robots/husky/user_manual_husky
......