Skip to content

GitLab

Home · Changes

Page history
Create home authored by Wouter Jansen's avatar Wouter Jansen
Show whitespace changes
Inline Side-by-side
home.md 0 → 100644
View page @ 8d4baf5a
# 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.
This guide was updated last on 2023-02-23.
![husky.jpg](husky.jpg)
## Table of content
- [The basics](#the-basics)
- [Layout](#layout)
- [Status panel](#status-panel)
- [Starting up](#starting-up)
- [Using the controller](#using-the-controller)
- [Orientation reference](#orientation-reference)
- [Specifications](#specifications)
- [Safety: Emergency-stop and lockout](#safety-emergency-stop-and-lockout)
- [Network Setup](#network-setup)
- [Network basics](#network-basics)
- [Internet access](#internet-access)
- [Sensors](#sensors)
- [eRTIS](#ertis)
- [Ouster OS0-128 LiDAR](#ouster-os0-128-lidar)
- [Intel Realsense d435i camera](#intel-realsense-d435i-camera)
- [Using ROS](#using-ros)
- [Default nodes](#default-nodes)
- [Default topics](#default-topics)
- [Motion topics](#motion-topics)
- [Odometry topics](#odometry-topics)
- [Diagnostic topics](#diagnostic-topics)
- [Custom workspace](#custom-workspace)
- [ROS Husky packages](#ros-husky-packages)
- [Navigation with ROS](#navigation-with-ros)
- [Publishing eRTIS data](#publishing-ertis-data)
- [Publishing Ouster OS0-128 LiDAR data](#publishing-ouster-os0-128-lidar-data)
- [Publishing Intel Realsense d435i camera data](#publishing-intel-realsense-d435i-camera-data)
- [Transformation tree](#transformation-tree)
- [Configuration](#configuration)
- [Software versions](#software-versions)
- [Network](#network)
- [Bash alias commands](#bash-alias-commands)
- [Other resources](#other-resources)
## The basics
### Layout
![layout.png](layout.png)
![layout_back.png](layout_back.png)
### Status panel
The status panel is a display of LED indicators located on the rear of the chassis which provide information about the current status of Husky. The indicators are described in the table below.
<table>
<thead>
<tr>
<th >Icon</th>
<th >Description</th>
</tr>
</thead>
<tbody>
<tr>
<td ><img src="status_battery.png"/></td>
<td >Battery Status The four LED segments provide an approximate indication of the relative lifetime remaining in the battery.</td>
</tr>
<tr>
<td ><img src="status_communication.png"/></td>
<td >Communication Status When green, Husky is receiving a stream of correctly-formatted motion commands, and is ready to drive. When yellow, Husky is receiving commands, but will not drive due to emergency stop or another error. When red, serial communications are currently timed-out.</td>
</tr>
<tr>
<td ><img src="status_general_error.png"/></td>
<td >General Error Status Illuminates red when Husky will not drive due to an error state. Such states include emergency stop, insufficient battery power, or an unspecified software error.</td>
</tr>
<tr>
<td ><img src="status_emergency.png"/></td>
<td >Emergency Stop Status Illuminates red when Husky will not drive due to the emergency stop being activated, either onboard or wireless (if available).</td>
</tr>
<tr>
<td ><img src="status_charge.png"/></td>
<td >Charge Indicator Illuminates red when Husky user power is being supplied externally.</td>
</tr>
</tbody>
</table>
### Starting up
The silver button at the top of the Status Panel is used to power the Husky on and off. From the "off" state, pressing the button will cause the Husky to power on and a blue ring at the edge of the button will be illuminated. From the "on" state, pressing the button will cause the Husky to power off and the blue ring will no longer be illuminated.
![panel.jpg](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.
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.
### Using the controller
To teleoperate Husky, first release the motion stop. Then, referring to the following image of the Logitech Controller, press the enable button (either slow or fast mode) and use the left thumbstick to drive Husky.
![controller.png](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.png](orientation.png)
### Specifications
| Specification | Measurement |
|--------------------------------|--------------------------------------------------------------------------|
| Dimension, Length | 990 mm |
| Dimension, Width | 670 mm |
| Dimension, Height | 390 mm |
| Track Width | 550 mm |
| Wheelbase Length | 512 mm |
| Ground Clearance | 130 mm |
| Mass | 50 kg |
| Maximum Payload¹ | 75 kg |
| All-terrain Payload² | 20 kg |
| Speed, Maximum | 1 m/s |
| Climb Grade | 45 ° |
| Traversal Grade / Sideslope | 30 ° |
| Operating Temperature, Minimum | -10 °C |
| Operating Temperature, Maximum | 40 °C (not in direct sunlight) |
| Operating Time, Average | 3 hours |
| Operating Time, Standby | 8 hours |
| Battery | 20 Ah @ 24 V, sealed lead-acid |
| Battery Charger | Short-circuit, over-current, over-voltage and reverse voltage protection |
| Charge Time | 10 hours |
| User Power | 5 V, 12 V, V-battery, each fused at 5 A |
| Communication | RS-232, 115200 baud |
| Wheel Encoders | 78,000 ticks/m |
| Internal Sensing | Battery Status, Wheel Odometry, Motor Currents |
| Environmental | note waterproof |
### Safety: Emergency-stop and lockout
![safety.png](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.
When in stop mode, the status panel stop light will illuminate red and Husky will not drive. The commands received during stop mode are not buffered; Husky will always act on the latest commands received. This means that if the commands are stopped before the stop is released, the Husky will not move. If the commands are continued, Husky will move at the speed commanded once the stop is released.
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 carefull 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!**
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.
![charging_connection.jpg](charging_connection.jpg)
![battery_connection.jpg](battery_connection.jpg)
The battery charger shipped with Clearpath Robotics's lead-acid battery-powered products uses a two-state charge cycle.
- A fast, high current initial charge, until the battery voltage reaches 27.2 V.
- A topping charge, during which the battery charges at 27.2 V constant voltage.
## Network Setup
### Network basics
The Husky A200 is shipped with a pre-configured network interface. It is hosting a DHCP server and a Wi-Fi access point. The Wi-Fi access point is named `Husky` and the password is `husky123`. The Husky A200 is also hosting a DHCP server, which will assign IP addresses to any devices that connect to the 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 available ethernet switch in the hatch.
![ethernet_switch.jpg](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 a internet-able network.
You can use the command `sudo nmtui` from the terminal to connect. If it does not work, try rebooting as this offen helps.
If using the University network (`uawifi`) 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
eap=peap;
identity=username@ad.ua.ac.be
password=password
```
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
sudo iptables -A FORWARD -o wlx74da38c9a498 -i enp3s0 -s 192.168.131.0/24 -m conntrack --ctstate NEW -j ACCEPT
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.
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
```
## Sensors
There are under normal circumstances several sensors available on the Husky by default:
1. 3 eRTIS sensors
2. Ouster OS0-128 LiDAR (with IMU)
3. Intel Realsense d435i camera
### 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:
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).
![rtis_sync.png](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)).
### 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.
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.
| Node | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `/husky_node` | Provides control and communication between the Husky platform and ROS. Accepts velocity commands and provides system feedback on `/status` |
| `/robot_state_publisher` | Subscribes to `/joint_states` and publishes the robot's state to `/tf` |
| `/bluetooth_teleop` | Publishes velocity commands from a joystick to `/twist_mux` |
| `/twist_mux` | Takes in multiple sources of velocity commands, and prioritizes what actually gets sent to the controller |
| `/ekf_localization` | Part of the robot localization package, more information regarding this package can be found [here](http://wiki.ros.org/robot_localization) |
### Default topics
You can view all topics that are active using `rostopic list`. The most important topics are summarized in table below.
| Topic | Message type | Description |
|-----------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `/bluetooth_teleop/joy` | `sensor_msgs/Joy` | Receives joystick commands, echo this topic to verify your controller is publishing |
| `/tf` | `tf2_msgs/TFMessage` | Transforms between coordinate frames, this should always be publishing, and hence a good topic to echo to test your ROS connection |
| `/status` | `husky_msgs/HuskyStatus` | Displays system status information |
| `/estop` | `std_msgs/Bool` | Displays the estop status |
| `/odometry/filtered` | `nav_msgs/Odometry` | The odometry estimate of the robot from `/ekf_localization` |
### Motion topics
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.
| Motion Topics | twist_mux Priority | Description |
|------------------------------------|--------------------|------------------------------------------------------------------|
| `/joy_teleop/cmd_vel` | 10 | Joystick teleop input |
| `/twist_marker_server/cmd_vel` | 8 | Interactive marker teleop input |
| `/move_base/cmd_vel` | 2 | Autonomous movement input, for the Husky navigation packages |
| `/cmd_vel` | 1 | Miscellaneous external input |
### Odometry topics
Husky publishes odometry information on the `odometry/filtered` topic, as `nav_msgs/Odometry` messages. These are generated by `ekf_localization_node`, which processes data from several sensor sources using an Extended Kalman filter (EKF). This includes data from the wheel encoders.
| Topic | Sources |
|--------------------------------|-----------------------|
| `husky_velocity_controller/odom` | `husky_node` |
| `imu/data` | `imu_filter_madgwick` |
| `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 :
```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,
you can install them with:
```bash
sudo apt-get install ros-kinetic-husky-desktop
```
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 of using the controller.
- 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.
### 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.
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.
### 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.
### 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.
### 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.
- 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:
- Ubuntu: 16.04.7
- Python: 2.7.12
- Python3: 3.6.13
- cmake: 3.20.5
- gcc: 9.4.0
- ROS: kinetic
### Network
The `br0` bridge connects the ethernet and Wi-Fi networks on respectively `enp3s0` and `wlp2s0`.
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:
```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
### Bash alias commands
the commands like `startServer` and `startOuster` are defined and can be configured in `~/.bash_aliases`.
## Other resources
- Official Husky guide: https://docs.clearpathrobotics.com/docs/robots/outdoor_robots/husky/user_manual_husky
- More Husky tutorials: https://docs.clearpathrobotics.com/docs/robots/outdoor_robots/husky/tutorials_husky
- Husky base installation guide for Ubuntu 16.04: https://github.com/RoboticsCollaborative/Husky