= HEBI C++ Examples: Clearpath Jackal + HEBI Arm =
HEBI Arms can be easily integrated with the Clearpath Jackal mobile base.

https://github.com/HebiRobotics/hebi_cpp_api_ros_examples/tree/master/src/integrations/clearpath_jackal

This example demonstrates installation of the HEBI control code and simple teleoperation script onto the Jackal, as well as optional visualization on and control from a remote PC.

{{attachment:jackal.png}}

== Jackal Instructions ==
These steps should be run on the Jackal, and install and setup the basic teleop control.

=== Installation / Build ===
Open a terminal, and run the following:

{{{
sudo apt-get install ros-kinetic-hebi-cpp-api ros-kinetic-moveit

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
git clone https://github.com/HebiRobotics/hebi_cpp_api_ros_examples.git hebi_cpp_api_examples
git clone https://github.com/HebiRobotics/hebi_description.git
git clone https://github.com/HebiRobotics/hebi_moveit_configs.git
cd ..
catkin_make
}}}
Also, to display the mounting hardware as part of the URDF, we need to set an environment variable on the system.  To do this, modify `/etc/ros/setup.bash`, adding the following line.  (Replace `/home/<jackal-username>/` with the path to the directory where you created the `catkin_ws` directory above).

{{{
export JACKAL_URDF_EXTRAS='/home/<jackal-username>/catkin_ws/src/hebi_cpp_api_examples/src/integrations/clearpath_jackal/jackal_to_hebi.urdf'
}}}
=== Parameters ===
Note -- the above code assumes default family/name configuration for the HEBI arm. If you have changed the family or name of the modules, you must change the parameters which define the modules on the network that the arm node will try to connect to.  The parameter files are in the `~/catkin_ws/src/hebi_cpp_api_ros_examples/config/a-2085-06_params.yaml` file.

Ensure the families and names parameters match the module family and names, ordered from proximal to distal, of your robot, and that these modules are visible on the network from your computer.  Use HEBI Scope (downloadable from http://docs.hebi.us/downloads_changelogs.html#downloads) to discover and configure modules on your network.

=== Running ===
Run the following command to start the teleop demo, which allows you to control the arm from the Jackal's controller.

{{{
roslaunch hebi_cpp_api_examples jackal_arm.launch
}}}
{{attachment:controller.png||width="600"}}

=== Configuring Autostart ===
First, we must ensure we source the workspace we have added.  To do this, modify `/etc/ros/setup.bash` to source `~/catkin_ws/setup.bash` instead of `/opt/ros/kinetic/setup.bash`.

Next, we set the launch file to be run at startup.  Copy the desired launch file into `/etc/ros/kinetic/ros.d`:

{{{
sudo cp ~/catkin_ws/src/hebi_cpp_api_examples/src/integrations/clearpath_jackal/jackal_arm.launch /etc/ros/kinetic/ros.d/
}}}
For more information, see the guide at:

http://www.clearpathrobotics.com/assets/guides/jackal/startup.html

== Remote Base Station (Optional) ==
You can set up a PC to connect to the Jackal's network, and visualize and command the robot directly through this PC.

=== Setup Connection ===
First, you must setup the PC to connect the the ROS master on the Jackal.  Follow Clearpath's guide at: http://www.clearpathrobotics.com/assets/guides/jackal/network.html#remote-ros-connection

=== Installation / Build ===
Open a terminal, and run the following:

{{{
sudo apt-get install ros-kinetic-hebi-cpp-api ros-kinetic-moveit ros-kinetic-jackal-description ros-kinetic-jackal-viz

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
git clone https://github.com/HebiRobotics/hebi_cpp_api_ros_examples.git hebi_cpp_api_examples
git clone https://github.com/HebiRobotics/hebi_description.git
git clone https://github.com/HebiRobotics/hebi_moveit_configs.git
cd ..
catkin_make
}}}
=== Running ===
Run the following command to start the teleop demo, which allows you to control the arm from the Jackal's controller.

{{{
roslaunch hebi_cpp_api_examples jackal_base_station.launch
}}}
Note that ROS launch files do not always work with multiple machine setups, so you may need to manually run `rviz` and load the configuration:

{{{
rosrun rviz rviz
}}}
Then click `File > Open`, and open `~/catkin_ws/src/hebi_cpp_api_ros_examples/src/integrations/clearpath_jackal/rviz_config.rviz`.

{{attachment:remote_visualization.png||width="600"}}

== Customization ==
The included example teleoperation script maps a few joystick buttons to preconfigured arm and gripper poses, which are sent via a standard MoveIt interface.  You can customize the script on the Jackal at `~/catkin_ws/src/hebi_cpp_api_ros_examples/src/integrations/clearpath_jackal/jackal_arm_teleop.py`, or you can run your own script on either the Jackal or base station PC to add autonomy to the system.

If you do not want to automatically start the joystick teleop script, but you do want to start the MoveIt contol of the HEBI Arm, remove the last lines in the `~/catkin_ws/src/hebi_cpp_api_ros_examples/src/integrations/clearpath_jackal/jackal_arm.launch` which start the teleop python script.

== Simulation ==
The HEBI-Jackal integration can also be used in simulation with Gazebo. In addition to following the instructions above, you should install the hebi_gazebo package in your workspace.
{{{
cd ~/catkin_ws/src
git clone https://github.com/HebiRobotics/hebi_gazebo.git
cd ..
catkin_make
}}}
Follow the package specific instructions at https://github.com/HebiRobotics/hebi_gazebo to setup the required environment variables (specifically the path to the HEBI Gazebo plugin).

To launch the simulation config, run 
{{{
roslaunch hebi_cpp_api_examples jackal_arm_gazebo.launch
}}}

Note that the HEBI parallel gripper is not currently simulated properly in Gazebo, so a non-gripper arm configuration is loaded.

If you would like to use a different arm configuration, you can modify this by setting the arm_type argument of the launchfile:
{{{
roslaunch hebi_cpp_api_examples jackal_arm_gazebo.launch arm_type:=A-2084-04
}}}