View source for Hexapod

= Installation =
The installation assumes that Ubuntu 12.04 LTS is installed. If not you should install an Ubuntu version. Notice that the version of Ubuntu determines line 3 in the following code i.e. precise.
<pre>
# Setup your computer to accept software from ROS.org
# 12.04 (precise)
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu precise main" > /etc/apt/sources.list.d/ros-latest.list'

# Set up your keys
wget http://packages.ros.org/ros.key -O - | sudo apt-key add -

# Installation
sudo apt-get update
sudo apt-get install ros-fuerte-desktop-full
sudo apt-get install ros-fuerte-orocos-toolchain
sudo apt-get install ros-fuerte-rtt-common-msgs

# Create your personal ros directory
mkdir ~/ros_personal

echo "source /opt/ros/fuerte/setup.bash" >> ~/.bashrc
echo "export ROS_PACKAGE_PATH=/opt/ros/fuerte/stacks:~/ros_personal" >> ~/.bashrc
echo "export RTT_COMPONENT_PATH=/opt/ros/fuerte/stacks/orocos_toolchain/install/lib/orocos" >> ~/.bashrc
echo "source /opt/ros/fuerte/stacks/orocos_toolchain/env.sh" >> ~/.bashrc
. ~/.bashrc

# Build SOEM
cd ~/ros_personal
git clone http://git.mech.kuleuven.be/robotics/soem.git
cd soem
git checkout origin/electric
rosmake soem

# Build hexapod
cd ~/ros_personal
svn checkout http://hexapod.wtb.tue.nl/svn/hexapod ./hexapod
roscd hexapod
rosrun rtt_rosnode create_rtt_msgs hexapod_msgs
rosmake

# You still should get
## (1) pr2_spring_transmission_example
## (2) rtt_generic_components (from the amigo trunk, ask with the amigo team)
</pre>
It is possible to put the code in a shell-file and run it.

= SVN =
The code can be found on: http://hexapod.wtb.tue.nl/svn/hexapod/.

To obtain an account you should contact Patrick van Brakel.
To keep the svn clean i.e. no build, bin or lib files do the following:
<pre>
sudo gedit /etc/subversion/config 
</pre>
Uncomment, by removing the '#' and add
<pre>
global-ignores = *.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo
  *.rej *~ #*# .#* .*.swp .DS_Store lib build bin .tb_history msg_gen srv_gen
</pre>

= Hardware =
The TU/e hexapod is a six legged robot with compliant joints. The compliance is obtained by using torsional springs between the actuators and the joints; for the last two segments additional steel cables are wrapped around pulleys for remote actuation. The motors as well as the joints have absolute encoders. From the difference between these readings, the torsion in the springs can be calculated. 

There are three main PCBs on the robot. The PCB inside the bottom of the robot (data acquisition module or DAM1) communicates with a computer. This can be the on board computer or an external pc. It is also equipped with an IMU that can measure pitch and roll angles, roll rates about three axes and acceleration along three axes. Furthermore, it receives power directly from the battery or external power supply and feeds it to the other boards.

== Start-up ==
The PCB on top of the robot (DAM 2) translates the signals it receives from a controller to electric currents for the actuators. 
The middle PCB is the on board computer on which it is possible to run the robot's software. 

To power the hardware, there is a 24V connection on the bottom of the robot. There is a possibility to connect one of the LiPo battery packs or alternatively to wire the robot to a laboratory power supply. When connecting a power supply, make sure the current is not limited too much (you need more than 3A, 10A should be enough. Alternatively, wiring a capacitor in parallel is an option). Once this is connected, the DAM 1 can be started using the small red button that is connected to two loose wires and after that, pressing the large white button on top starts DAM 2.

Connection to a computer, either the on board one or an off board pc, can be established using the "In" port on the piggyback EtherCAT board on the DAM 2. The "out" port should be connected to the "Out" port on DAM 1.

= Software =
A basic structure of the software is shown in the figure below. The grey components are not used, the grey components with grey text are not (yet) implemented.

[[File:ControlLoop2.png|800px|The basic control structure for the Hexapod.]]

= Simulator =
For simulation purposes, the [http://gazebosim.org/ Gazebo] simulator has been adopted in the very first hexapod development because of its integration with ROS. In a short time, Gazebo has changed and has become a stand-alone software. The early version of the robot model is not compatible with both ROS Fuerte and Gazebo. A complete re-writing of the interface code is needed. However, a porting from the old version to the new one has been attempted. To get started a few basic steps are presented below.

To start, proceed with the installation following the instructions [http://gazebosim.org/wiki/Install here]. Choose the latest stable release.

It's important to specify the robot model in the SDF format. The *.urdf.xacro format is no longer supported. To convert such a file, a script is available in the repository. Once you have defined the correct filename of the model to be converted, type
<pre>
roscd hexapod_model/models/scripts
source update.bash
</pre>
== Hierarchy convention ==
The folder tree has this structure: 
* '''hexapod_model'''
** '''model_name'''
*** hexapod.world ("launch" file)
*** model.config
*** model.sdf
*** model.urdf
*** meshes
*** '''plugins'''
**** '''build'''

== Plugins ==
Gazebo plugins are lines of code compiled as a shared library and inserted into the simulation. The plugins have direct access to all the functionality of Gazebo through the standard C++ classes. 
They are used to load models, control the robot, etc.
From gazebosim.org:
<blockquote>Each plugin type is managed by a different component of Gazebo. For example, a Model plugin is attached to and controls a specific model in Gazebo. Similarly, a World plugin is attached to a world, and a Sensor plugin to a specific sensor. The System plugin is specified on the command line, and loads first during a Gazebo startup. This plugin gives the user control over the startup process.</blockquote>

Write your plugin_name.cpp in the hexapod_model/model_name/plugins folder. Then edit the CMakeLists.txt so that it looks like this:

<pre>cmake_minimum_required(VERSION 2.8 FATAL_ERROR)
include (FindPkgConfig)
if (PKG_CONFIG_FOUND)
  pkg_check_modules(GAZEBO gazebo)
endif()
include_directories(${GAZEBO_INCLUDE_DIRS})
link_directories(${GAZEBO_LIBRARY_DIRS})


add_library(plugin_name SHARED plugin_name.cc)
target_link_libraries(plugin_name ${GAZEBO_libraries})</pre>

As a next step, go in the plugins/build folder and build the library.
<pre>
cmake ../
make
</pre>

It's important to define the models and the plugins that you want to load in your hexapod.world file. Here's its generic model:

<pre>
<?xml version="1.0"?>
<sdf version="1.4">
  <world name="default">
    <include>
      <uri>model://ground_plane</uri>
    </include>

    <include>
      <uri>model://sun</uri>
    </include>

    <plugin name="plugin_name" filename="libplugin_name.so"/>
  </world>
</sdf>
</pre>

It's important to set the GAZEBO_PLUGIN_PATH correctly, pointing to the shared libraries. To do so, edit your .bashrc file:

<pre>
gedit ~/.bashrc

#GAZEBO
export GAZEBO_PLUGIN_PATH=$HOME/ros/hex/hexapod/trunk/hexapod/hexapod_model/''model_name''/plugins/build:${GAZEBO_PLUGIN_PATH}

source ~/.bashrc
</pre> 

To have more insight, follow the [http://gazebosim.org/wiki/Tutorials/1.9/plugins tutorial].

== Model spawning ==
The hexapod_model folder contains the models, each one with its ''model_name'' folder. 

It's important to set the GAZEBO_MODEL_PATH correctly, pointing to ''hexapod_model''. To do so, edit your bashrc file adding this line:
<pre>
gedit ~/.bashrc

#GAZEBO
export GAZEBO_MODEL_PATH=$HOME/ros/hex/hexapod/trunk/hexapod/hexapod_model/:${GAZEBO_MODEL_PATH}

source ~/.bashrc
</pre>
== What is missing? ==
Compatibility problems show up for the moment. The model implementation has no elastic transmission and no interface hardware-simulator.

= Getting started with the robot =
Essential files for robot startup are presented here.
== hexapod_launch ==
The 'hexapod_launch' package contains launch files, whose task is to call Orocos scripting language files (ops) contained in the hexapod_launch/deploy_files folder and start the ROS master.  
Some of the deploy scripts contain hard coded paths. Make sure to substitute them with your own. A shell file, rename.sh, was written to automatically do this, but be sure to change the path in this file to your own path. It is located in hexapod_launch. Another possible solution for the future is to seperate the scripts more clearly and call them in a launch file, in which ROS launch syntax can be used to avoid hard coding paths.

== Essential launch files description ==
{| border="1" class="wikitable"
|-
! File name 
! Description
|-
| robot_model_and_state_publisher.launch
| Loads robot parameters and kinematic model, plus starts the state publisher
|-
| start.launch
| Deploys the full set of components currently available to control the robot.
|}

In order to control the robot, the robot model file must '''always''' run.
== OROCOS components ==
=== Hardware interface and measurement components ===
A series of components interfacing with sensors and actuators constitute the essential core of the robot. Real-time data flow has to be preserved
at all time during communication. Measurement and safety components are included in this section, because they base their functionality on the three main interface components (actuator, encoder and IMU drivers) that
communicate directly with the EtherCAT boards.

==== Actuator driver ====
This component sends the control message to the actuators, that has the form of a current setpoint.
The signal that is sent through the output port has the dimensions of a torque, being the current multiplied by the motor torque constant. 
In order for the signal to be sent, a command message has to be sent as well.
==== Encoder driver ====
The encoder driver, as the name says, reads the encoders, transforming them into human readable angle values.
==== IMU driver ====
IMU data flows through this component, that outputs the pitch and roll estimates together with acceleration and gyro values.
==== Safety ====
For the actuators to work, the safety module has to send an authorization signal. 
The conditions for which a green light command message is sent are that the legs are not trying to move out of their workspace and
that the last link is not damaging the steel cable of the thigh by bending the shank. Moreover, an operation can be called to check 
the actuators status. An error message is displayed in the following cases:
 
* there's an overheating of the bridge driver overheating.
* the drive input voltage drops below 16V.
* invalid hall commutation is detected.

==== Ground contact detection ====
To manage the transitions between stance and flight phases, the ground contact detection is crucial.
Because of the series elastic transmission, the difference between joint and actuator encoders readings is available. 
When the legs are touching the floor, a deflection in the compliant transmission occurs. 
By measuring the average difference for the hip encoders readings during stance and flight phase, it's possible to determine a deflection region corresponding to ground contact, and subsequently a threshold 
can be easily fixed in order to distinguish the two phases.
==== Height detection ====
The vertical position measurement of the hexapod's body over time, a desired performance index for a hopping robot, is hard to estimate.
In literature, body height of legged robots is generally computed by averaging the tips vertical positions of the legs, transformed to the world coordinate frame, when they are touching the floor. 
==== Gait components ====
These components are responsible for the legs reference trajectory definition. According to the desired motion, different kind of gaits exist.
* Tips positioning
The user can specify a preferred cartesian objective for each leg tip, and subsequently a reference trajectory is generated.
* Continuous gait: the continuous gait component generates a third order cartesian trajectory for the legs. A fifth order trajectory has been tested as well, and needs some final debugging to work correctly.
* Turning gait: a slow turning gait is available via this component.  

A list of tunable properties allows to specify the following gait parameters and, as a consequence, the type of gait:
** The gait duty factor: fraction of time the leg is on the ground.
** The cycle time: time spent for a gait cycle.
** The phase: normalized time shift between reference trajectories with respect to a reference.
**Leg stroke: leg distance from the body.

==== Kinematics ====
Hexapod forward and inverse kinematics are integrated using the Kinematics and Dynamics Library (KDL)
of OROCOS. KDL is an application independent framework for modelling and computation of
kinematic chains. It includes class libraries for geometrical entities, various kinematic chains, and their motion.
==== Feedforward ====
The feedforward block sums its signal to the controller output feeding the plant. 
The amplitude of 18 current signals can be singularly specified, and an operation
that manages the current offset for the shank, in case of horizontal jump movement, is exposed for
external program or state machine callers.

= Hopping = 
One of the main goals of the design of the TU/e Hexapod robot is for it to be able to run and/or jump. To achieve this, the idea is that the resonance frequency is utilized. The approach that is used, is the one proposed in <ref>Hopping at the Resonance Frequency: A Trajectory Generation Technique for Bipedal Robots with Elastic Joints, Ugurlu et al.</ref>. The authors of this article use 9 steps to generate a joint reference for a jumping robot. This method is adapted to work on a hexapod and applied here.

== Determining the resonace frequency ==
The first step in this approach is to determine the resonace frequency of the standing robot. In our case, this is done by making the robot stand up (up to position_3) and giving it a sudden push on the top, as a way of applying a delta function. As we are interested in the vertical displacement, and the IMU only gives accelerations, the vertical acceleration is measured. As a sinusoidal response is expected in the displacement, the second derivative should also be a sinusoid at the same frequency. This measurement is documented using a reporter component in OROCOS and the resulting data is imported into matlab to calculate the single sided amplitude spectrum.

The resulting amplitude spectrum is shown in the figure on the right. A clear peak is visible at 4.0 Hz, which is a reasonable value for the resonance frequency, looking at the robot in practice. 

[[File:SSAS_Hexapod_vertical_mode_6.jpg|thumb|400px|Single-sided amplitude spectrum of the Hexapod in vertical oscillation mode with 6 legs on the ground.]]

= Troubleshooting =
* The Soem master could not initialize on eth1
Make sure that you are connected to eth1 or otherwise change it in the *.ops file.
To list the network ID's form your PC use the following command in the terminal:

<pre>
ifconfig
</pre>

* If the setcap cannot be found.
Install the setcap.

<pre>
sudo apt-get install libcap2-bin
</pre>

* If the followin error occurs:
<pre>
[ ERROR  ][Soem] Could not initialize master on eth1
</pre>
Set the permission for the deployer-gnulinux such that it can use ethernet.

<pre>
roscd ocl
cd bin
sudo setcap cap_net_raw+ep ./deployer-gnulinux
</pre>

* If, while running the orocos software, you are getting errors/warnings like 
<pre>
Actuator CF & FT disabled, difference act-jnt is too large"
</pre>
or HexapodSafety will not start, giving a similar error.

Stop and restart HexapodDriverEncoder while in position_init

= Log =
Log any hardware failure and/or breakdown here. After repair works, ALWAYS recalibrate the encoders! Look for hardware_calibration.ops in hexapod_launch.

{| border="0" cellpadding="2"
|-
| Mar 21 || Femur cable of leg 1 broke during testing of walking gait. Fixed by Speciaalmachinefabriek Ketels.
|-
| Mar 31 || Femur cable of leg 6 broke during testing of hopping/jumping. Fixed by Speciaalmachinefabriek Ketels.
|-
| Apr 7  || Femur cable of leg 6 wrapped around the wrong slot during testing of new walking gait trajectory. Fixed by Speciaalmachinefabriek Ketels.
|-
| Apr 16 || Femur cable of leg 6 wrapped around the wrong slot during testing of jumping.
|}

= Useful references =
Some interesting tips and tricks can be found on [http://servicerobot.cstwiki.wtb.tue.nl/index.php?title=Software/tips_and_tricks the wiki of AMIGO]. Regarding realtime performance, also look at [http://servicerobot.cstwiki.wtb.tue.nl/index.php?title=Allow_OROCOS_to_work_(almost)_realtime this page]. For these links, an account for the AMIGO wiki is needed. This can be obtained with the AMIGO team.

== Reports ==
{| border="0" cellpadding="2"
|-
| Boris Mrkajic || Systems and Control Library Development || [http://cstwiki.wtb.tue.nl/servicerobot/files/Final_Thesis_Boris_Mrkajic.pdf  pdf]
|-
| Max Baeten || Control of the Philips Experimental Robotic Arms using EtherCAT || [http://cstwiki.wtb.tue.nl/servicerobot/files/Free_Space_Report_Max_Baeten.pdf pdf]
|-
| Niek Bilterijst || Low Level Spindle Control of AMIGO || [http://cstwiki.wtb.tue.nl/servicerobot/files/LowLevelSpindleControlonAMIGO.pdf pdf]
|-
| Tim Clephas || Design and control of a service robot - ''The birth of AMIGO'' || [http://cstwiki.wtb.tue.nl/servicerobot/files/Final_Thesis_Tim_Clephas.pdf  pdf]
|-
| R. Woering || Simulating the "first steps" of a hexapodal robot || [http://www.mate.tue.nl/mate/pdfs/12670.pdf pdf]
|-
| Jeroen Willems || Control of a hexapodal robot || [http://cstwiki.wtb.tue.nl/images/Willems_Hexapod_2011.pdf pdf]
|-
| Rokus Ottervanger || Reviving the Hexapod || [http://cstwiki.wtb.tue.nl/images/Ottervanger2014RevivingTheHexapod.pdf pdf]
|}

== References ==

<references/>

= Timetable =
*'''April'''
** ''Week 1''
*** Restore simulator
**** Look into Gazebo/OROCOS online documentation
**** Order the models 
**** Spawn the robot on new Gazebo 2.2 version
** ''Week 2 & 3''
*** Elaborate a simple model for the jumping dynamics
** ''Week 4''
*** Simulate the model and find torques to be sent to enable the jumping feature
*'''May'''
** ''Week 1''
*** 
****
** ''Week 2''
*** 
**** 
** ''Week 3''

** ''Week 4''

*'''June'''
** ''Week 1''
*** Restore simulator
****
** ''Week 2''
*** Implement feedforward when robot is in STATE_LAND
**** Write suitable command to joint actuators
** ''Week 3''

** ''Week 4''