husky.tex

% Software License Agreement
%
% Author    Mike Purvis <mpurvis@clearpathrobotics.com>
% Copyright (c) 2014, Clearpath Robotics, Inc., All rights reserved.
%
% Redistribution and use in source and binary forms, with or without modification, is
% not permitted without the express permission of Clearpath Robotics.

\documentclass[]{clearpath-latex/clearpath-manual}
\graphicspath{{gen/}}
\usepackage{multirow}
\usepackage{gensymb}
\usepackage{dcolumn}
\usepackage{colortbl}
\usepackage{float}
\usepackage{fancyhdr}
\pagestyle{fancyplain}
\lfoot{Rev. 1.3.0}
\rfoot{Husky UGV}
\lhead{}
\chead{}
\rhead{}
\renewcommand{\headrulewidth}{0pt}


\begin{document}

\manualcover{cover-page.pdf}
\tableofcontents

\section{Introduction}

Husky is a rugged and easy-to-use unmanned ground vehicle for rapid prototyping and research applications. In this guide you will find information about the setup, operation, and maintenance of Husky.

\subsection{What's Included}

Contained in your Husky shipment are the following items:

\begin{itemize}[nolistsep]
  \item Clearpath Robotics Husky
  \item 24V Sealed Lead-Acid Battery Pack
  \item Battery Door Cover
  \item Battery Charger
  \item Lockout Keys x2
  \item Power Connectors x3
\end{itemize}


\subsection{What's Required}

To use Husky, you will require a PC capable of running Robot Operating System (ROS).
If a computer option was purchased from Clearpath Robotics with Husky, then the included laptop or minicomputer has
already been configured with Ubuntu 20.04 and ROS Noetic, plus appropriate ROS packages and other configuration for use with Husky.

\subsection{Expansions}
To expand the capabilities of Husky, consider the following accessories offered by Clearpath Robotics:


\begin{itemize}[nolistsep]
  \item Spare Battery
  \item IMU
  \item LIDAR
  \item Network Camera
  \item GPS
\end{itemize}

Each sensor package ships from Clearpath Robotics with a custom mounting bracket and cabling for easy attachment to Husky’s extruded aluminum payload mounting rail.


\section{The Basics}

This section provides an overview of the key specifications of the Husky platform. \autoref{husky_glance} gives a tour of key Husky components.


\begin{figure}[h]
  \centering
  \includegraphics[width=0.9\linewidth]{graphics/husky-front.png}
  \includegraphics[width=0.9\linewidth]{graphics/husky-rear.png}
  \caption{Husky at a Glance}
  \label{husky_glance}
\end{figure}
\newpage

\subsection{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 \autoref{status_panel}.

\begin{table}[h]
  \renewcommand{\arraystretch}{1.6}
  \centering
    \begin{tabular}{ >{\centering\arraybackslash}m{.1\linewidth} >{\raggedright\arraybackslash}m{.7\linewidth} }
      \hline
    \rowcolor{lightgrey} Icon & Description
      \\ \hline
    \includegraphics[width=0.7 cm]{graphics/battery-mini.png} &
      \textbf{Battery status} The four LED segments provide an approximate indication of the relative lifetime remaining in the battery,
      \\[4pt] \hline
    \includegraphics[width=0.7 cm]{graphics/comm-mini.png} &
      \textbf{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.
      \\[4pt] \hline
    \includegraphics[width=0.7 cm]{graphics/err-mini.png} &
      \textbf{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.
      \\[4pt] \hline
    \includegraphics[width=0.7 cm]{graphics/estop-mini.png} &
      \textbf{Emergency stop status} Illuminates red when Husky will not drive due to the emergency stop being activated, either onboard or wireless (if available).
      \\[4pt] \hline
    \includegraphics[width=0.7 cm]{graphics/charge-mini.png} &
      \textbf{Charge Indicator} Illuminates red when Husky user power is being supplied externally.
      \\[4pt] \hline
    \end{tabular}
  \caption{Husky Status Panel Icons}
  \label{status_panel}
\end{table}
\newpage

\subsection{Orientation References}

The reference frame used by all Clearpath Robotics ground vehicles is based on ISO 8855, and is shown in \autoref{rframe}. Husky is displayed from the front. 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.

 \begin{figure}[h]
	\includegraphics[width=\textwidth]{graphics/rframe.png}
	\caption{Husky Reference Frame}
	\label{rframe}
 \end{figure}

\subsection{Pinout Refrences}

Husky provides a female DE-9 connector for communication with a host device. The pinout of this connector is shown in \autoref{pinouttable} .


\begin{figure}[h]
	\centering
	\begin{tabular}{  >{\centering\arraybackslash}m{.4\linewidth} c c c c }
	\multirow{5}{*}{\includegraphics[width=0.4\textwidth]{graphics/pinout.png}} \\  \cline{2-5}
	& \cellcolor{lightgrey}  Pin & \cellcolor{lightgrey}  Name & \cellcolor{lightgrey}  Dir & \cellcolor{lightgrey}  Description \\ \cline{2-5}
	& 2 & RX & IN & Data from Platform\\  \cline{2-5}
	& 3 & TX & OUT & Data to Platform\\ \cline{2-5}
	& 5 & GND & N/A & Common Ground\\ \cline{2-5}
	\end{tabular}
	\newline
	\caption{Husky DE9 Pinout}
	\label{pinouttable}

\end{figure}

The connectors used in the Husky's user bay  are Weidmüller's 6 Position Terminal Blocks, to connect your own bare wires, you may use Digi-key part number 281-1856-ND.

\newpage

\section{System Specifications}

Key specifications of Husky are shown in \autoref{systemspecs} .

\begin{table}[h]
	\centering
	\begin{tabular}{>{\columncolor{lightgrey}}>{\raggedright}m{.25\textwidth} p{.25\textwidth} p{.25\textwidth}} \hline
	& 990 mm length & 39 in length \\
	& 670 mm width & 26.4 in width \\
	\multirow{-3}{*}{Dimensions}
	& 390 mm height & 14.6 in height \\ \cline{2-3}
	Track & 555 mm & 21.9 in \\ \hline
	Wheelbase & 512 mm & 20.2 in \\ \hline
	Weight & 50 kg & 110 lbs \\ \hline
	Maximum Payload\footnotemark[1] & 75 kg & 165 lbs \\ \hline
	All-terrain payload\footnotemark[2] & 20 kg & 44 lbs \\ \hline
	Speed (max) & 1.0 m/s & 3.3 ft/s \\ \cline{2-3}
	Ground clearance & 130mm & 5 in \\ \cline{2-3}
	Climb grade & 45\degree & 100\% slope \\ \cline{2-3}
	Traversal grade & 30\degree & 58\% slope \\ \cline{2-3}
	Operating Ambient Temperature & -10 to 30\textsuperscript{o} C & 14 to 86\textsuperscript{o} F \\ \hline
	& 3 hours typical & \\
	\multirow{-2}{*}{Operating time}
	&\multicolumn{2}{p{.5\textwidth}}{8 hours standby (no motion)}\\ \cline{2-3}
	& 24V 20Ah &\\
	\multirow{-2}{*}{Battery}
	& Sealed Lead Acid & \\ \cline{2-3}
	\multirow{2}{*}{Battery charger} & \multicolumn{2}{p{.5\textwidth}}{Short-circuit, over-current, over-voltage and reverse voltage protection}\\ \hline
	Charge time & 10 hours & \\ \hline
	& VBAT (approx. 24-29V unregulated) / 24V / 12V & \\
	\multirow{-2}{*}{User Power}
	& Fused at 5A / 3A / 7.5A & \\ \hline
	& RS-232 & \\
	\multirow{-2}{*}{Communication}
	& 115200 Baud & \\ \hline
	Wheel Encoders & 78,000 ticks/m & \\ \hline
	& Battery Status & \\
	& Wheel odometry & \\
	\multirow{-3}{*}{Internal Sensing}
	& Motor currents & \\ \hline

	\end{tabular}
\newline
\caption{Husky System Specifications}
\label{systemspecs}
\end{table}

\footnotetext[1]{Continuous operation on relatively flat terrain with wide turns}
\footnotetext[2]{Vehicle climbing 30° grade with high-mounted payload, or turning in place in high-friction conditions}
\newpage
\subsection{Vehicle Equations}

As a starting point, Clearpath Robotics recommends using the following relationship between wheel velocity and platform velocity:
\begin{figure}[h]
\centering
$v=\frac{v_r+v_l}{2} , \omega=\frac{v_r-v_l}{w}$
\end{figure}

$v$ represents the instantaneous translational speed of the platform and $w$ the instantaneous rotational speed. $v_r$ and $v_l$ are
the right and left wheel velocities, respectively. $w$ is the effective track of the vehicle, 0.555 m.

\section{Safety}
Clearpath Robotics is committed to high standards of safety. Husky contains several features to protect the safety of users and the integrity of the vehicle.

\subsection{General Warnings}

Husky is a rugged and high-performance vehicle. For the safety of yourself and others,
always conduct initial experiments and software development with the vehicle raised off the ground.
Place a wooden crate, a set of sawhorses, a sturdy storage tub, or any other solid flat structure having a
height greater than 6 inches under Husky to keep the wheels clear of the ground (“up on blocks”).

When starting out, favor slower wheel speeds. Husky’s control loops can accurately maintain velocities
as low as 0.1 m/s. Operating at such speeds will give you more time to react if things don’t go quite as you expect.

When Husky is operating, keep clear of the wheels, paying particular attention to the pinch hazard which exists between each wheel and the end of the corresponding bumper bar.

Under some conditions, components inside of the robot can become very hot to the touch. If there is a need to go inside of the unit, allow the robot to cool for a minimum of 15 minutes before touching anything internally.

\subsection{E-Stop and Lockout}

The red emergency stop button (e-stop) and lockout are located on the back of Husky, opposite the status panel,
shown in \autoref{estop-lockout}. Power supply to Husky’s motor drivers is enabled by a normally-open relay,
which is closed in series with the e-stop switch. When in e-stop mode, the status panel e-stop light will illuminate red,
and Husky will not drive. The commands received during e-stop are not buffered; Husky will always act on the latest commands
received. This means that if the commands are stopped before the e-stop is released, the Husky will not move. If the
commands are continued, Husky will move at the speed commanded once the e-stop is released.

\begin{figure}[h]
	\centering
	\includegraphics[width=0.6\textwidth]{graphics/estop-lockout.png}
	\caption{Husky Emergency Stop and Lockout}
	\label{estop-lockout}
\end{figure}

Always ensure the e-stop button is accessible at all times. Avoid mounting payloads that extend over the rear of Husky and would occlude the e-stop.

The lockout provides a way to secure Husky from performing any type of motion. When in lockout mode, the robot will still power on, but the motors will not drive.

\subsection{Electrical System}
Husky is powered by a single 24V sealed lead-acid battery, similar to the type found in electric wheelchairs, golf carts,
and other devices. Husky’s battery is capable of delivering 1800W—similar to wall mains. This gives Husky’s motors their
great performance, however, it is also enough power to cause severe bodily harm. Please observe the following precautions:

\begin{itemize}
	\item Do not tamper with the plug attached to the battery.
	\item Do not tamper with the fuse panel, except to check and change the fuses, and to connect and disconnect the battery plug.
	\item Do not operate Husky without the battery door in place. The battery is not restrained without the door, and will come loose, damaging the fuse panel.
	\item Charge the battery only with the charger provided by Clearpath Robotics.
	\item Please dispose of the batteries properly.
\end{itemize}

\subsection{Lifting and transport}
For the safety of users and to maximize the lifetime of Husky, please observe the following when manually transporting the robot:

\begin{itemize}
		\item Husky should be lifted by two persons, firmly gripping the front and rear bumper-bars.
		The battery can be removed to lighten the load of a manual transport.
		\item Ensure that Husky is e-stopped when transporting short distances and powered off when transporting
		longer distances.
		\item Note: It is not advised to push Husky, as this can cause damage to the motors
\end{itemize}
\newpage

\subsection{Performance Recommendations}

Included in Husky are native software checks and limits to protect the vehicle. However,
it is recommended to monitor the system’s status during usage with the \lstinline{/status} and \lstinline{/diagnostics} topics.
These topics provides useful information regarding voltages, currents, temperatures and general health of the system.

The total current draw does not include the motors drivers; it is the current consumed by the MCU and user power ports.
Husky’s motors are rated to draw 8A continuous, but they will spike to several times this, particularly when traversing
rough terrain and when turning on the spot. To reduce current draw, consider commanding wider-radius turns from
your control software.

The temperature is measured in the motor drivers and on the motor casings; the coils inside the motor casings cannot be measured.
Therefore, it is important to note that the temperature measured on the motor casings is a lagging indicator of
the temperature of the coils inside the casing. Be aware of the delay in heat propagation on the motors during heavy use.
The thermal limit of the system is 50 C\degree, and the system will shut down if this limit is reached.
Monitoring these fields over longer periods of operation will allow you to ensure that you are not putting
excessive wear on Husky's motors.
\newpage

\section{Getting Started}

You are ready to go! This section details how to get Husky into action.
To begin, place Husky “up on blocks” as described in the Safety section – make sure the wheels are clear of the ground.

For most Husky setups, there will be an Onboard PC which is directly connected to the Husky and a Remote PC which is used to control Husky and gather data. These two PCs must be set up to communicate with each other.


\subsection{Onboard PC Setup}

If you purchased an Onboard PC from Clearpath Robotics with Husky, it is already installed, connected, and powered.
Provided on this machine is the officially-supported ROS software for Husky, joystick teleoperation, and any sensor payloads purchased.

If not, or to set up your own Onboard PC, please visit \url{http://wiki.ros.org/Robots/Husky}


\subsection{Connecting the Onboard PC}

Husky’s serial port is located in the user power panel accessible from the user area, shown in \autoref{RS232}.

\begin{figure}[h]
	\centering
	\includegraphics[width=0.8\textwidth]{graphics/RS232.png}
	\caption{Husky RS232 Connector}
	\label{RS232}
\end{figure}

The connector is a female DE9, suitable for connection directly to a USB-serial adaptor,
or to a PC serial port via a straight-through modem cable (not a null modem cable).
How you connect the Onboard PC to Husky depends on whether the Onboard PC has a dedicated serial port.

\subsection{Wireless Access}

To get Husky connected to your local wifi, you must first access the internal computer
using a wired connection. Open the chassis, lower the computer tray, and connect to the network port
labeled \lstinline{STATIC} with a standard ethernet cable.

\subsubsection{Static IP Configuration}

Set your laptop's ethernet port to a static IP such as \lstinline{192.168.131.101}.  To do this in Ubuntu, follow the steps below:
\begin{enumerate}
  \item Click on the Wifi icon in the upper-right corner of your screen, and select \textbf{Edit Connections}
  \item In the \textbf{Network Connections} window, under \textbf{Ethernet}, select your wired connection and then click \textbf{Edit}
  \item Select the \textbf{IPv4 Settings} tab and then change the \textbf{Method} to \lstinline{Manual}
  \item Click the \textbf{Add} button to add a new address
  \item Enter a \lstinline{192.168.131.101} as the static IP under the \textbf{Address} column, and enter \lstinline{255.255.255.0} under the \textbf{NetMask} column, and then select \textbf{Save}
\end{enumerate}

\begin{figure}[h]
  \centering
  \includegraphics[width=0.5\linewidth]{wired_connection.png}
  \caption{Static IP Configuration}
  \label{staticip}
\end{figure}

\subsubsection{Connect to Husky via SSH over ethernet}

The next step is to connect to Husky via SSH.  To do so execute the following in a terminal window:

\begin{lstlisting}
ssh administrator@192.168.131.1
\end{lstlisting}

You will be promoted to enter a password.  The default password is \lstinline{clearpath}.

\subsubsection{Connect Husky to Wireless Network}

Now that you're connected via SSH over a wired connection, you can setup Husky to connect to a local wifi network. To do this, you will need to use Netplan - a preinstalled network configuration tool.

In a terminal window, execute the following command:

\begin{lstlisting}
sudo nano /etc/netplan/60-wireless.yaml
\end{lstlisting}

This will create an empty YAML file called \textbf{60-wireless.yaml} which you will populate to configure Husky's wireless networking via Netplan.

Copy and paste the following into the empty file you just created:

\begin{lstlisting}
network:
  wifis:
    WIRELESS_INTERFACE:
      optional: true
      access-points:
        SSID_GOES_HERE:
          password: PASSWORD_GOES_HERE
      dhcp4: true
      dhcp4-overrides:
        send-hostname: true
\end{lstlisting}

Modify the following variables in the file. Replace \lstinline{WIRELESS_INTERFACE} with the name of Husky's wifi interface (e.g. wlan0, wlp2s0, or wlp3s0). Replace \lstinline{SSID_GOES_HERE} with the name of the local wifi network. Replace \lstinline{PASSWORD_GOES_HERE} with the password of the local wifi network. 

Once you are done modifying the file, save it by pressing \textbf{CTRL + O}, then \textbf{ENTER}. Close the file by pressing \textbf{CTRL + X}.

Apply your new Netplan configuration and bring up the wifi connection.

In a terminal window, execute the following command:

\begin{lstlisting}
sudo netplan apply
\end{lstlisting}

While you're still wired to Husky, you'll need to identify the IP address of Husky's wireless connection.

In a terminal window, execute:

\begin{lstlisting}
ip a
\end{lstlisting}

A list of network connections will be displayed within the terminal. Locate the wireless network and make note of its IP address. Now that you know Husky's wireless IP address, you may now exit the ethernet SSH session by executing \lstinline{exit}.

Remove the ethernet cord and close up Husky.   Now you can SSH into Husky over the wireless network.  To do so, execute:

\begin{lstlisting}
ssh administrator@<IP_OF_HUSKY>
\end{lstlisting}

SSH sessions allow you to control Husky's internal computer.  You can do various things such as download packages, run updates, add/remove files, transfer files etc.

\subsection{Remote ROS Connectivity}\label{remote}

To use ROS desktop tools, you’ll need your computer to be able to connect to Husky’s ROS master. This will allow you to run ROS commands like \lstinline{rostopic list}, \lstinline{rostopic echo}, \lstinline{rosnode list}, and others, from a remote PC and the output will reflect the activity on Husky’s ROS master, rather than on your own machine.  This can be a tricky process, but we’ve tried to make it as simple as possible.

In order for the ROS tools on your computer to talk to Husky, they need to know two things:

\begin{itemize}[nolistsep]
  \item How to find the ROS master, which is set in the \lstinline{ROS_MASTER_URI} environment variable, and
  \item How processes on the other computer can find your computer, which is the \lstinline{ROS_IP} environment variable.
\end{itemize}

The suggested pattern is to create a file in your home directory called \lstinline{remote-husky.sh} with the following contents:

\begin{lstlisting}
export ROS_MASTER_URI=http://cpr-husky-0001:11311  # Husky's hostname
export ROS_IP=10.25.0.102       # Your laptop's wireless IP address
\end{lstlisting}

If your network doesn’t already resolve Husky’s hostname to its wireless IP address, you may need to add a corresponding line to your computer’s /etc/hosts file:

\begin{lstlisting}
10.25.0.101 cpr-husky-0001
\end{lstlisting}

\textbf{NOTE:} You can verify the hostname and IP address of Husky using the following commands during an SSH session with the onboard PC.

\begin{lstlisting}
hostname
hostname -i
\end{lstlisting}

Then, when you’re ready to communicate remotely with Husky, you can source that script like so, thus defining those two key environment variables in the present context.

\begin{lstlisting}
source remote-husky.sh
\end{lstlisting}

To verify that everything is set up propelry, try running a few ROS commands, such as the standard visual ROS tools:

\begin{lstlisting}
roslaunch husky_viz view_robot.launch
rosrun rqt_robot_monitor rqt_robot_monitor
rosrun rqt_console rqt_console
\end{lstlisting}

If the tools launch, then everything is setup properly.

Please contact Clearpath Support if you need assistance in configuring remote access. For more general details on how ROS works over TCP with multiple machines, please see:

\url{http://wiki.ros.org/ROS/Tutorials/MultipleMachines}.

For help troubleshooting a multiple machines connectivity issue, see:

\url{http://wiki.ros.org/ROS/NetworkSetup}

\newpage\subsection{Husky Desktop Packages}

To command or observe Husky from your desktop computer, first set up a basic
ROS installation. See the following page for details:

\url{http://wiki.ros.org/noetic/Installation/Ubuntu}

When your ROS install is set up, install the Husky desktop packages:

\begin{lstlisting}
sudo apt-get install ros-noetic-husky-desktop
\end{lstlisting}

Once your remote access to Husky's ROS master is configured (see options in \autoref{remote}),
you can launch rviz, the standard ROS robot visualization tool:

\begin{lstlisting}
roslaunch husky_viz view_robot.launch
\end{lstlisting}

From within rviz, you can use interactive markers to drive Husky, you can visualize its
published localization estimate, and you can visualize any attached sensors which have been
added to its robot description XML (\lstinline{URDF}).

Additionally from the desktop, you can launch the standard RQT Robot Monitor, which
watches the diagnostic output from Husky's self-montoring capabilities:

\begin{lstlisting}
rosrun rqt_robot_monitor rqt_robot_monitor
\end{lstlisting}

\newpage

\subsection{Connecting Power}
Husky comes with the battery fully charged and installed, but disconnected for safety during shipping.
To reconnect the battery:

\begin{enumerate}
	\item Ensure Husky’s main power button is in the outer “off” position and the e-stop is activated.
	\item Using curled index fingers to grip the battery door latches, press with thumbs on the latch buttons and lift the battery door free of the chassis.
	\item Carefully connect the battery plug to the mating connector in the fuse panel, shown in \autoref{battery-area}. Ensure that it is firmly seated and clicks into place. It will be difficult to connect it in the incorrect polarity.
	\item Replace the battery door cover, ensuring that it clicks into place and is flush with the rear panel.
\end{enumerate}

\begin{figure}[h]
	\centering
	\includegraphics[width=0.8\textwidth]{graphics/battery-area.png}
	\caption{Husky Battery Area}
	\label{battery-area}
\end{figure}

To power on Husky, firmly press the power button located above the status panel. It will illuminate blue, and the
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 e-stop is pressed. If it is not, press the e-stop button and
verify that the stop light illuminates. Leave the platform in an e-stop state until it is successfully receiving commands.

\subsection{User Bay Power Connections}
The user area power terminals are capable of supplying VBAT (approx 24-29V, unregulated) fused at 5A, 12V fused at 7.5A,
24V fused at 3A. 192W total power available. Upgrade to 480W available as an option. Each terminal comes equipped with a
removable connector into which your payload power leads may connect.

Husky UGVs with serial numbers lower than A200-0802 have different user power connections.  These older robots have
5V, 12V, and 24V supplies, all fused at 5A.

To begin, expose about 5mm of bare wire from the payload power leads and twist the exposed wire on both leads.  Take 2 molex terminals from the spare parts kit provided and insert the exposed wire and crimp the terminals, ensuring the wires are well secured inside the terminal, as shown in \autoref{connectors}. Take 1 connector housing from the spare parts kit provided and insert the positive payload power lead (red) into position 4, 5, or 6 of the connector until it locks into place and insert the negative payload power lead (black) into position 1, 2, or 3 of the connector until it locks into place.

\begin{figure}[h]
	\centering
	\includegraphics[width=0.5\textwidth]{graphics/updated-power-connector-1.jpg}
	\includegraphics[width=0.38\textwidth]{graphics/updated-power-connector-2.jpg}
	\caption{User Power Connectors}
	\label{connectors}
\end{figure}

When connecting payloads, be sure to observe correct polarity as marked on the inside of the user bay.
Do not exceed the specified maximum current limit of each power rail; failure to do so may result in damage
to Husky or your payload.

For more technical information on the power connectors, as well as their corresponding mating connectors, please visit: \url{https://www.digikey.ca/en/products/detail/molex/0039012065/930272?s=N4IgTCBcDaIOoFkwGYDsAGMBaAcgERAF0BfIA}

\subsection{Verification}
If a computer was purchased with Husky, it will be setup to interface automatically upon startup.
60-90 seconds after booting up, the Husky comms light will change from red to green
(or yellow, depending on e-stop status), indicating that ROS is up and has established communications with Husky.

To tele-operate Husky, plug a USB joystick into the included Onboard PC, and release the emergency stop.
After a few seconds, ROS should recognize the joystick and begin passing commands through to the mobile platform.
Press the enable button (typically button 1), and use the main joystick axis or left thumbstick to drive Husky.

Direct control using the Python or C++ interfaces is also possible, the API is available at
\url{http://www.clearpathrobotics.com/husky/downloads} However, please note that Clearpath Robotics no
longer provides support for these packages, and are they supplied "as is".

\section{Using ROS}
Robot Operating System (ROS) is an extensible framework for controlling and working with robotic systems.
Clearpath Robotics recommends using ROS with Husky. If this is your first time using ROS, it is strongly
recommended to run through our series of ROS101 tutorials to learn the basics of ROS
\url{http://support.clearpathrobotics.com}. If you did not purchase a PC from Clearpath Robotics, please visit \url{http://wiki.ros.org/Robots/Husky}
to set up your own Onboard PC.

\subsection{Nodes}
You can use \lstinline{rosnode list} to see all the nodes running by default on a Husky computer.
The baseline set of these is presented with commentary in \autoref{nodes-table}.

\bgroup
\begin{table}[h]
	\centering
	\begin{tabular}{>{\columncolor{lightgrey}}m{.25\linewidth} m{.5\linewidth}} \hline
	Node & Description \\ \hline
	/husky\_node & Provides control and communication between the Husky platform and ROS. Accepts velocity commands and provides system feedback on /status \\ \hline
	/robot\_state\_publisher & Subscribes to /joint\_states and publishes the robot's state to tf \\ \hline
	/bluetooth\_teleop & Publishes velocity commands from a joystick to /twist\_mux \\ \hline
	/twist\_mux & Takes in multiple sources of velocity commands, and prioritizes what actually gets sent to the controller \\ \hline
	/ekf\_localization & Part of the robot localization package, more information regarding this package can be found at \url{http://wiki.ros.org/robot_localization } \\ \hline
	\end{tabular}
	\caption{Standard Husky Nodes}
	\label{nodes-table}
\end{table}
\egroup
\newpage
\subsection{Topics}
You can view all topics that are active using \lstinline{rostopc list}. Some of the base topics are listed in \autoref{topics-table} and \autoref{topics-motion}.

\begin{table}[h]
	\centering
	\begin{tabular}{>{\columncolor{lightgrey}}m{.3\linewidth} m{.25\linewidth} m{.3\linewidth}} \hline
		Topic & Message type & Description\\ \hline
		\lstinline!bluetooth_teleop/joy! & \lstinline!sensor_msgs/Joy! & Receives joystick commands, echo this topic to verify your controller is publishing \\ \hline
		\lstinline!/tf! & \lstinline!tf2_msgs/TFMessage! & Transforms between coordinate frames, this should always be publishing, and hence a good topic to echo to test your ROS connection \\ \hline
		\lstinline!/status! & \lstinline!husky_msgs/HuskyStatus! & Displays system status information\\ \hline
		\lstinline!/estop! & \lstinline!std_msgs/Bool! & Displays the estop status\\ \hline
		\lstinline!/odometry/filtered! & \lstinline!nav_msgs/Odometry! &  The odometry estimate of the robot from \lstinline!/ekf_localization!\\ \hline
	\end{tabular}
	\caption{Standard Husky Topics}
	\label{topics-table}
\end{table}

\begin{table}[h]
	\centering
	\begin{tabular}{>{\columncolor{lightgrey}}m{.3\linewidth} m{.25\linewidth} m{.3\linewidth}} \hline
		Motion Topics & \lstinline|twist_mux| Priority & Description\\ \hline
		\lstinline|husky_velocity_controller/cmd_vel| & - & Receives motion commands from \lstinline|twist_mux| based off their priority\\ \hline
		\lstinline|joy_teleop/cmd_vel| & 10 & Joystick teleop input\\ \hline
		\lstinline|twist_marker_server/cmd_vel| & 8 & Interactive marker teleop input\\ \hline
		\lstinline|move_base/cmd_vel| & 2 & Autonomous movement input, for the husky navigation packages\\ \hline
		\lstinline|cmd_vel| & 1 & Miscellaneous external input \\ \hline
	\end{tabular}
	\caption{Standard Husky Motion Topics}
	\label{topics-motion}
\end{table}

\subsection{Workspace}
The expected model for extending Husky is to create a new ROS Workspace in the user’s home directory,
and add packages there. You can roslaunch additional nodes against the ROS Master already running on Husky
without needing to stop or start anything else. See the Overlays page on the ROS wiki for more details:
\url{http://wiki.ros.org/catkin/Tutorials/workspace_overlaying}

When it comes time for some of your own code to be launched on startup of Husky, edit the default workspace setup file,
located in \lstinline{/etc/ros/setup.bash}. Change the final line from the default to instead source your own workspace.
When this is done, copy the launch file for your software into the \lstinline{robot_upstart} folder, which is located at
\lstinline{/etc/ros/noetic/ros.d}. Now restart the Husky background service and your nodes should come
up with the rest of Husky:

\begin{lstlisting}
sudo systemctl restart ros
\end{lstlisting}

For more details on this process, please see the ROS wiki page about upstart, located at: \url{http://wiki.ros.org/robot_upstart}

\subsection{Payloads}
You can find a list of supported packages and related documentation for payloads on Clearpath Robotics’
ROS Wiki page here: \url{http://wiki.ros.org/ClearpathRobotics}
\newpage

\section{Battery and Maintenance}
Husky A200 is built for rugged, long-term use. Here are some steps that can be
taken to maintain and extend the life of the platform even further.

\subsection{Charging}
The battery shipped with Husky A200 may be charged off-board, 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 its connector in the fuse panel. From there:

\begin{enumerate}
	\item Connect the DC output cable from the charger to the battery terminal connector.
	\item Plug the charger power cord into the charger and then into a wall receptacle.
	\item The POWER LED and CHARGING LED lights on the charger will illuminate.
	\item When battery is fully charged, the CHARGING LED light will turn off.
	\item Unplug the charger from the wall, and then disconnect it from the battery.
\end{enumerate}

The battery charger shipped with Clearpath Robotics’ lead-acid
battery-powered products uses a three-state charge cycle.

\begin{enumerate}
		\item A fast, high current initial charge, until the battery voltage reaches 29.6V.
		\item A topping charge, during which the battery charges at 29.6V constant voltage
		until the current decreases to 500 mA.
		\item A precision float charge, during which the battery voltage is held at 27.6V.
		This mode allows the charger to remain connected to the battery during periods of non-use,
		keeping it in a state of full charge. When in this mode, the CHARGING LED will be off.
\end{enumerate}

\subsection{Battery Care}
Husky’s power supply is a sealed 24 V lead acid battery pack (VRLA), providing 20 ampere-hours of charge. These tips are
intended to help keep your Husky Lead-Acid Battery in tip-top shape.  With proper maintenance, the battery should
maintain the majority of its capacity for hundreds of cycles.

The most damaging thing to a lead-acid battery is a phenomenon called sulfation.
When a lead-acid battery is left in an uncharged state for long periods of time,
sulfate crystals solidify on the electrodes of the battery.  This effect can be permanent,
and it causes premature reduction in capacity.  Therefore, it is important to fully charge
the battery as soon as you are finished using it, regardless of how much capacity remains

Your Husky ships with a three-stage battery charger that completely charges a Husky battery.
Charging occurs in three stages: Constant current, topping charge, and float charge.
The bulk of the capacity (70\%) is regained during the first stage.

It is important to let the charger complete all three stages whenever possible,
to help maintain the life of the battery.  The initial stage will take 5-7 hours,
and a complete charge may take up to 14 hours.

\begin{figure}[h]
	\centering
	\includegraphics[width=0.7\textwidth]{graphics/battery-chart.png}
	\caption{Husky Battery Voltage Characteristics}
	\label{battery-chart}
\end{figure}

In general, following these tips will help maximize the life of the battery:

\begin{itemize}
	\item Always fully charge the battery as soon as you are finished using it.
	\item Charge batteries at room temperature.  Never charge lead-acid batteries at temperatures above 35 degrees Celcius.
	\item Charge batteries in a well-ventilated area.
	\item Do not allow the battery to freeze.  A low battery will freeze sooner than a fully charged one.  Never charge a frozen battery.
	\item Stored batteries should be topped up every month.  Completely cycle batteries every 4-6 months.
	\item At a discharge rate of 50% DOD (depth of discharge), the lifecycle of the Husky battery is 450-550 cycles.
	After this point, reduced capacity will be apparent.
	\item Regularly discharging the battery below 50% DOD will reduce the lifecycle of the battery, sometimes to less than 300 cycles.
\end{itemize}

\subsection{Wheels}
Tire pressure may change with temperature and should be checked periodically with a pressure gauge.
Inspecting tires, releasing pressure, and inflating tires are completed through the tire’s inflation stem.
Tire pressure should not exceed 20psi, and lower pressure may be desired based on terrain requirements.

If a tire must be removed, first unfasten the four M5 Socket Head Cap Screws that join the wheel to the axle hub,
and slide it off the axle. When replacing the tire, screws should be tightened to 3.7 ft-lb [5 N-m] torque.

\subsection{Chassis}
Husky is an all-terrain robot, but it is not waterproof. Care should be taken that no part of the main
chassis is ever submerged in water. When the chassis becomes wet or dirty, wipe it down with a damp cloth
and dry with a towel.

If water is suspected to have entered the Husky A200 chassis, remove the battery and allow Husky to fully dry for a minimum of 24 hours.

\section{Tips and Troubleshooting}

\subsection{Mechanical Tips}
Husky’s wheels can handle a range of different terrains, but work best when inflated to the proper pressure.
Lower tire pressures, for example 10 psi, ensure better traction in rough and varied terrain, where rocks or
other obstacles may be encountered. This has the adverse effect of lowering drivetrain efficiency and decreasing
battery charge, so high pressures up to a maximum of 20 psi should be used when driving on flat surfaces.

\subsection{Troubleshooting}

This section lists a few possible issues which may be encountered:

\begin{itemize}
	\item \textbf{The blue light around the power button does not display when pressing the power button.} Ensure that the battery is charged and correctly connected. Use a multi-meter to verify the voltage on the battery terminals.
	\item \textbf{Comm light stays red/flickers.} Your program may not be sending motion commands faster than 10Hz. If there is a poor quality connection, some commands may be lost, so it may be necessary to increase the frequency of commands sent. The maximum frequency commands can be sent is 50Hz
	\item \textbf{E-stop light illuminated.} Twist the red e-stop to release it, and confirm that the robot is not locked out.
	\item \textbf{Battery indicator flashing.} Battery voltage is too low for Husky to drive the motors. Charge the battery and try again.
	\item \textbf{A ROS package isn't starting.} Verify the upstart logs, \lstinline{/var/log/upstart/husky_core.log} to see if there are any error during upstart.
	\item \textbf{Husky experiences momentary drops in communication.} It's possible the robot has reached the thermal limit, or current limit. The maximum current limits are set to 18.3A, however, as  the motors are only rated for 8A continuous, anything above that will trigger the current limit eventually, the higher above this limit, the more quickly it will trigger.  If you are unsure whether this is the case, feel free to contact support@clearpathrobotics.com with a rosbag of your system. Clearpath robotics also offers a high torque upgrade if more torque is required for your project.
\end{itemize}

If you experience setup issues that aren’t listed here, or the suggested solution isn’t working out, please get in touch with our support team so we can help: support@clearpathrobotics.com.

\newpage
\section{Product Dimensions}

\begin{figure}[h]
	\centering
	\includegraphics[width=.9\textwidth]{graphics/husky-dimensions.png}
	\caption{Husky Dimensions}
\end{figure}
\newpage
\section{Service and Support}
Clearpath is committed to your success with Husky. Please get in touch with us and we'll
do our best to get you rolling again quickly: \href{mailto:support@clearpathrobotics.com}{support@clearpathrobotics.com}
or visit out knowledge base for at \href{http://support.clearpathrobotics.com}{support.clearpathrobotics.com}

To get in touch with our sales team regarding Husky or other Clearpath Robotics products, please
email \href{mailto:sales@clearpathrobotics.com}{sales@clearpathrobotics.com}.

If you have an issue that is specifically about ROS and is something which may be of interest
to the broader community, consider asking it on \href{http://answers.ros.org}{answers.ros.org}.
If you don't get a satisfactory response, please ping us and include a link to your question
as posted there. If appropriate, we'll answer in the ROS Answers context for the benefit of the
community.


\end{document}