From Wiki for iCub and Friends
Revision as of 12:32, 25 September 2014 by Randaz (talk | contribs) (→‎Esdcan driver)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

iKart overview

The iKart

iKart is an holonomic mobile platform designed to provide to iCub autonomous navigation capabilities in structured environments. The main features of the platform are:

  • Easy plug-and-play connection with the iCub.
  • Omnidirectional movement: six omnidirectional wheels allow the platform to both translate and rotate on the spot.
  • On board computing capabilities: iKart is equipped with an Intel i7 quad core CPU to provide on board computing capabilities. The machine also acts as the server repository for the iCub software.
  • Power supply: the platform is equipped with a Lithium ion polymer battery (48V, 20Ah). The estimated autonomy is about two hours of normal operation of iKart+iCub system and for hours if only iKart is used.
  • Wireless connectivity: a 300Mbit/s wireless bridge provide wireless connectivity to both iKart and iCub.
  • Obstacle detection and localization: a laser rangefinder is mounted in the front of the platform. It can detect obstacles at thirty meters of distance, with a 270º angle of view.

iKart hardware description

In this section the main iKart hardware components are described. The picture below shows the location of the various components:

Ikart components.jpg

Main panel

The iKart main panel is shown in the picture below:

Ikart main panel.jpg

From left to right:

  • The battery switch. It is a three positions switch:
  • left position In this position the iKart (and iCub) is powered by the battery. The blue battery led will illuminate in this position. If the external power supply cable is also connected, the iKart will use the external power supply and the battery will not discharge. However, the battery cannot be recharged in this modality, even if the battery charger is connected.
  • middle position In this position the iKart is powered by the external power supply. The battery is completely disconnected.
  • right position In this position you can recharge the battery plugging the battery recharge cable into the apposite connector. The red battery recharge led will illuminate in this position. Remember that in this mode the iKart must still be powered through the external power supply, since the battery recharge do not directly supply power to the iKart but just to the battery.
The picture below illustrates the three power modes described above:

Ikart battery mode.jpg

  • The PC104 switch: This switch turns on/off the iCub PC104 board.
  • The battery recharge connector: the battery charger cable must be plugged into this connector.
  • The led indicators: Top row, from left to right: battery in use (blue), battery in charge (red), external power supply (green), motors on (yellow). Bottom row, from left to right: iKart on (green), iCub PC104 on (red).
  • The power button: press the button to turn on the iKart motherboard (like a normal PC)
  • The external power supply connector: the external power supply cable must be plugged into this connector.
  • The external fault connector: the external iKart and iCub fault buttons are connected through a 2 meters long cable to this connector. It's also possible to plug a jumper, in order to enable to the motors without connecting the external fault buttons.
  • The motor switch. This switch turns on/off the all the motors of iKart and iCub. Remember: never plug/unplug the power cable connecting the icub to the ikart if the power supply switches of the pc104/motors are on. Failing to do this will seriously damage the electronics!

Internal panel

The internal panel, accessible after removing the fiberglass back cover, contains several connectors, which should be not accessed during normal operation and are mainly used for diagnostic purposes and debug.

Ikart internal panel.jpg

From left to right:

  • CAN connector: using this connector it is possible to directly access the iKart CAN bus.
  • PS/2 connector: connector for an external keyboard.
  • VGA video connector: the output of the internal video board.
  • reset button: the iKart reset button.
  • Two USB connectors: general purpose USB connectors.


IKart is equipped with a 48V, 20Ah lithium ion polymer battery (model ePLB P4820 from Eig http://www.eigbattery.com). The battery is located on the back of the iKart, and can be extracted/replaced simply disconnecting the power cable and lifting the wireless bridge placed on the its top. On the back of battery is located a button which controls the internal battery management circuitry. This button should be never be pressed during normal operation. However, if a fault condition occurs (e.g: overheating, short circuit etc), the battery will enter in protection mode and will stop to supply current (the voltage will also drop to about 20V). In this case, the battery can be restored to normal operation by following this procedure: resume_iKart_battery_from_fault.

The battery autonomy is estimated to be about two hours during normal operation (iKart+iCub) and four hours if only iKart is used (iCub power supply cable disconnected). The battery can be recharged using its own charger, with the recharge cable plugged into the connector located on iKart main panel. During the battery recharging, the iKart can continue to normally operate if connected to the external power supply.


Battery Control Board (BCS)

It is a electronic board, located on right side of iKart, which monitors the status of charge of the battery. The board broadcasts information about the battery voltage, the current consumption and the estimated charge of the battery through a serial cable connected to the motherboard. If the battery charge is low, the user will be first warned, then if the charge reaches a critical level, a shutdown procedure will be initiated in order to prevent data loss.



IKart is equipped with a DAP-1522 wireless bridge (technical specifications can be found on the manufacture website http://www.dlink.com/products/?pid=663), located just on the top the iKart battery. On the back of the wireless bridge, two LAN ports are used: one port is connected to the iKart motherboard, the other one is connected to iCub PC104 (through the power cable which connects iKart with iCub). The wireless bridge is powered by the iKart 48V-to-5V DC/DC converter.

Ikart wireless.jpg

Hard Disk

The iKart hard disk is located under the front plate, on the left side.

Fault control board

The fault control board is plugged on the motherboard parallel connector.


File:Ikart fault board.jpg

Motor control boards

iKart uses two BLL motor control boards, identical to those used in iCub to control the brushless motors (http://wiki.icub.org/wiki/Controller_cards). The two boards are connected on the same CAN bus and have address 1 and 2 respectively. The board with address 1, located on the left under the frontal plate, control the motor on the back of iKart. The other board, placed on the right side, controls the two frontal motors of iKart. The boards are directly powered by the 48V power line.

Ikart bll.jpg

Wheels suspensions

The three idle wheels of the iKart platform are equipped with a suspension mechanism. The preload of the suspensions can be individually tuned through two nuts that are located on the top of the mechanism, inside the iKart. A screw, also located on the top of the mechanism, allows to set the limit of the suspension. During the iKart assembly, the preload is tuned in order to take in account the weight of the battery and of the whole iCub placed on the top of the platform.

Ikart suspension.jpg

CAN to USB converter

A CAN-USB2 converter is used to communicate with the motor control boards. The interface is located under the front plate, on the right side. Technical information about the CAN-USB2 converter can be found on the manufacturer website: http://www.esd.eu/esd2004/german/PDF-file/CAN/Englisch/can-usb2_e.pdf


Internal power supply

The iKart in equipped with three internal power supply modules:

  • An ATX power supply (input: 48V) which provides power to the iKart motherboard.
  • A 48V-to-12V DC/DC converter, which provides power to the laser rangefinder.
  • A 48V-to-5V DC/DC converter, which provides power supply to the wireless switch.

Laser scanner

An UTM-30LX Laser Range finder (Hokuyo Ltd) is mounted in front of the iKart. It is powered by the iKart 48-to-12V DC/DC converter, while the data are transmitted on through a separated USB cable. The range finder is able to detect obstacles up to 30m, with a scan angle of 270 degrees. The maximum refresh rate is 40Hz.


Joystick receiver

The joystick receiver is a standard XBox 360 wireless receiver. It is placed on the of the battery and is connected to an internal USB connector. The wireless range is about 10 meters.


External power supply (read carefully!)

iKart uses the same external power supply of iCub (please refer to: http://wiki.icub.org/wiki/Power_supply) although with different settings. The external power supply must be in fact configured in order to provide a voltage of 52.5V with a current limit of 18A. Using these settings is extremely important:

  • Since the iKart battery has a nominal voltage of 52V, the external power supply voltage must be always higher then the battery voltage, in order to prevent an undesired battery discharge when the iKart power supply switch is set to battery (blue led on).
  • A current limit of 18A, instead, is required in order to prevent accidental brownouts due to to the high inrush-current when the iKart motor switch is turned on. Since an unexpected reset during a write operation on the disk may compromise the integrity of the saved data, it is extremely important to increase the current limit of the power supply to 18A.
  • Remember: never plug/unplug the power cable connecting the icub to the ikart if the power supply switches of the pc104/motors are on. Failing to do this will seriously damage the electronics!


How to connect and reuse the iCub power supply for the iKart?

  • Let's begin by the starting point : what is the configuration of the Power Supply?
    • you should have 3 connections in between the 2 Power Supplies (the slimest one delivering 12V and the biggest one delivering a tension in betwwen 24V min to 40 max):
      • The main power cord connected to your iCub
      • one slim black wire as Ground reference in between the 2 power supplies
      • one cable compounded of 2 wires (1 black and 1 red or yellow in this picture below) labelled SH which enabled the biggest power supply (see : picture below to know where is it connected what is the normal configuration of the red selector)

Back panel Xantrex normal conf.jpg

  • At first, remove all the wirings from the back panel of the biggest Xantrex power supply : that is to say, first remove the 3 screws on the sides of the wire holder box (see : picture below) and then remove the connections on minus and plus L-shapped supports:
    • Minus support is compounded of 2 big black wires ended by a ring connector and one little black wire which is connected to the 12V power supply so as to create a GND reference.
    • Plus support is compounded of 2 big wires with RED tape ended with a ring.

XantreX back panel holder wire box.jpg

  • Attach the black wire and the red wire, from the cable labelled CBL35 you could find inside the iKart box Kit received, respectively with the minus and the plus L-shapped support as shown on picture below.

Connections XantreX.jpg

!!!! be careful !!!! you will need to solder a terminal on both wire. we used the ring terminal for AWG6 wires part number 130552 from TE Connectivity orderable from RS as code number 373-370. see picture below


  • The last but not the least, just copy the settings done for the switches and jumpers from the picture below, this is the settings to get the power supply independent from the other one.

Back side switches jumpers.jpg

iKart Software

In this section the core modules required to run the iKart are described. A diagram describing how these module are interconnected is presented below (click to enlarge).


iCub Interface

iKart uses the same iCubInterface application used by the iCub to communicate with the motor control boards. The system configuration is specified in the files iKart.ini and ikart_wheels.ini, which are located in the $IKART_ROOT\app\iKart\conf folder and installed by the make install command in the folder $ICUB_ROOT\app. The robot configuration is extremely simple, since a single CANbus line is used. This results in a single Yarp device driver which is used to control the robot analogously to the way in which iCub is controlled. The only difference between the two is that instead of having multiple robot parts such as head, left_arm, right_leg, etc. iKart has one only robot part, called wheels.

iKart Control

The iKartCtrl module is the main control module that acts as the interface between the user commands and the robot. The application consists of several threads which run concurrently, each of them responsible for a particular robot interface.


This thread receives the user commands and transform them into speed reference signals which are sent to the individual motors. The input commands can be sent to the controller through three different input ports:

  • /ikart/joystick:i This is the port to which connect the output of the joystickCtrl module.
  • /ikart/control:i On this port a user module (for example, a navigation software) can send commands to the iKart.
  • /ikart/aux_control:i Additional port providing the same functionality of /ikart/control:i

While all the three ports provide the same functionality, they have different (decreasing) priority. An input on the joystick:i port overrides an input on control:i port, which, in turn overrides an input on the aux_control:i. In this way, for example, the user can always take control of the iKart through the joystick, even if another module is sending wrong commands to the iKart. The commands sent to iKart through these ports can be expressed in two formats:

  • percentage respect to the maximum speed. This is the format used by default by the joystickCtrl module. The bottle is consituted by five values, with the following meaning
  • protocol identifier (int): an int value fixed to 1.
  • heading (double): the commanded linear direction of the iKart, expressed in degrees. The heading must me expressed accordingly to iKart reference frame, represented in the picture at the end of this section.
  • linear speed (double): the commanded linear speed, expressed as a percentage of the robot maximum linear speed (0-100.0%).
  • angular speed (double): the commanded angular speed, expressed as a percentage of the robot maximum angular speed (0-100.0%).
  • motor scaling factor (double): a scaling factor expressed in percentage (0-100.0%) that multiplies both the linear and the angular speed.
  • metric format. This is the preferred format for user modules. The bottle is constituted by four values, with the following meaning:
  • protocol identifier (int): an int value fixed to 2.
  • heading (double): the commanded linear direction of the iKart, expressed in degrees. The heading must me expressed accordingly to iKart reference frame, represented in the picture at the end of this section.
  • linear speed (double): the commanded linear speed, expressed in m/s.
  • angular speed (double): the commanded angular speed, expressed in deg/s.


It computes the iKart odometry, using the information take from the motor encoders. It provides the two following yarp ports:

  • /ikart/odometry:o. This port broadcasts the robot odometry. The bottle is constituted by six values (double), with the following meaning:
  • x position [m]
  • y position [m]
  • orientation [deg]
  • x velocity [m/s]
  • y velocity [m/s]
  • angular velocity [deg/s]
Please note that wheels slippage and model inaccuracies may affect the odometry accuracy, resulting in a cumulative error. This is not an issue of the iKart platform, but it is an intrinsic problem of the odometry computation in all mobile robot. For this reason, odometry information must be integrated with a localization mechanism (based for example on the laser data). Please refer to the SLAM section for information about performing absolute localization with the iKart. For the orientation of the x and y axes, please refer to the iKart reference frame picture at the end of this section.
  • /ikart/odometer:o. Information about the cumulative distance traveled by the robot is broadcasted by this port. The bottle is constituted by two values (double), with the following meaning:
  • traveled distance [m]
  • traveled angle [deg]
Both the odometry and the odometer information can be zeroed by sending the command reset_odometry to the /ikart/rpc port.


It retrieves the laser rangefinder measurements through its yarp interfaces, and broadcasts the data on the output port.

  • /ikart/laser:o. Contains the laser scan measurements. The data is constituted by an array of 1080 double, corresponding to the measurements (expressed in mm) obtained from the laser during a counterclockwise scan (each measurements corresponds to an angle of 270/1080= 0.25 degrees).

iKartCtrl RPC commands

The iKartCtrl module also provides a port /ikart/rpc to which the user can send rpc commands. Below is reported the list of the available rpc commands:

  • help displays the list of the available commands
  • run turns on the three motors (use to run again the iKart after pressing the fault button)
  • idle turns off the three motors.
  • reset_odometry set to zero both the odometry and the odometer data.

The iKart Reference frame

Both the cartesian joystick/user commands and the iKart odometry are expressed into the iKart reference frame which is oriented according to the following convention:

  • the y axis is directed forward.
  • the x axis is directed toward right.
  • the heading angle is positive clockwise and negative counterclockwise.

Ikart ref frame.jpg

Joystick Control

The joystickCtrl module allows to take the input from a joystick and send it on a yarp port (by default: /joystickCtrl:o). The module takes in input a .ini file in which the user can specify the configuration of the joystick, including axis remapping, different scaling factors, deadbands, etc. A complete list of the available configuration options is reported in the module documentation.

Below is reported the default joystick configuration to control the iKart. The joystick configuration is specified in the file: $ICUB_ROOT/app/joystickCtrl/iKart.ini. By default the .ini file assigns to button 0(A) and 1(B) the execution of the scripts ikart_motors_run.sh and ikart_motors_idle.sh. The other buttons can assigned by the user to execute any custom .sh script.


Laser GUI

The laserScannerGUI provides a simple graphical interface in order to visualize the measurements performed by the frontal laser rangefinder. The module receives the measurements from the iKartCtrl module through the /ikart/laser:o yarp port. A list of all the available options (e.g. zoom, refresh rate etc.) is displayed by pressing the key 'h'.


Battery Manager

The iKartBattteryManager is the module responsible of verifying the status of charge (SoC) of the battery. The module is automatically started from the script /etc/rc.local during the boot sequence and periodically reads the from the /dev/ttyUSB0 serial port the SoC of the battery. The default update rate is 10 seconds. In order to preserve the robot sensible components from dangerous brownouts, the module takes the following actions if the battery is low:

  • The user will be notified with a wall message if the charge of the battery level is lower than 10%.
  • If the battery reaches a critical level (below 5%), the module will start an emergency shutdown procedure, by stopping the iCub and iKart motor interfaces, and turning off the machine, with a two minutes advance notice.

The module executes independently if the yarp server is running or not. If yes, infomation about the SoC of the battery is sent through the /ikart/battery:o port. You can also ask the module to save a timestamped logfile of the performed battery measurements, by specifying the option --logToFile into the startup script (default: off).

Battery Display

The iKartBatteryDisplay is a graphical tool which displays the current SoC of the battery. The module receives the battery info from the iKartBatteryManager module through the /ikart/battery:o yarp port. Since the iKart obviously doesn't have a graphical output, this module will not run on the iKart machine. Instead, the iKartBatteryDisplay is thought to be executed by the user on all the machines remotely connected to the iKart. The provided always-on-top window will remember to the user the remaining autonomy of the robot, so it's a good idea to keep an iKartBatteryDisplay instance always running on each user machine connected to the iKart.


Starting the iKart with the joystick

There are cases in which you may want to start moving the iKart just after the boot, without connecting to the robot in ssh, starting all the application etc. This joystick start-up is particularly useful if, for example, you turned on the iKart in a room where there is no wireless connection, and you want to move it to another room. In order to command the iKart to perform a joystick start-up, you have to follow the procedure:

  • Turn on the the iKart (with the motor switch on and the fault button unpressed).
  • Turn on your joystick by pressing the central joystick button.
  • Wait for the beep coming from the iKart, indicating that the boot is finished.
  • At this point you have for 5 seconds the chance, by pressing any button on the joystick (or moving the sticks) to initiate the joystick start-up procedure.

If a joystick activity has been detected, the iKart will automatically initialize the following processes (and will make automatoically all the required connections):

  • The Yarp server.
  • The iCubInterface required to control the iKart motors.
  • The iKartControl module.
  • The joystickControl module.

You will be now able to move the iKart around usually the joystick as in normal operation.

How the joystick-startup procedure works

The script responsible for the joystick-startup procedure is ikart_start.sh which is originally located under $IKART_ROOT/app/iKart/ikart_boot and copied to $ICUB_BIN during the installation procedure. The scripts executes the joystickCheck module in order to verify if a joystick activity is detect, and executes initializes the yarp server and the control software if so. The ikart_start.sh script is automatically executed from the main boot script /etc/rc.local after the low-level drivers initialization.

Stopping/Restarting the joystick-startup

An analogous script ikart_stop.sh is provided in order to stop all the modules launched by the ikart_start.sh script, when controlling the iKart is no longer required. Currently, there is no way to execute this script using the joystick, so it has to be manually invoked through an ssh connection to iKart. Please also note the yarp server started by the ikart_start.sh script will be not stopped by the ikart_stop.sh script. Finally, remember that the joystick start-up procedure, which is particularly convenient during the boot, can be also manually invoked anytime, by launching the ikart_start.sh script from a console, or through an ssh connection.

Additional/user modules

In this section only the core iKart module have been described.

A general description of the iKart navigation software can be found here.

Additional user modules, providing other useful functionalities, are contained in the iKart repository. Please refer to the individual module documentation for a detailed description of their usage.

Using the iKart

Starting the robot

Before starting the iKart, verify that:

  • The motor switch must be on
  • The fault button must not pressed. If you do not want to use the fault button, plug the provided jumper into the fault connector. Remember that in this way you will not be able to stop iKart and iCub in case of problems, so use the jumper with caution.
  • The iCub arms are properly positioned (the iKart will may not pass through a door if its arm are extended, and no checks about the robot posture are performed during the navigation!)
  • The joystick is turned on. Remember that in case of problems, the joystick commands have always the priority on the navigation software and the other user module.

You can now turn the main panel switch to the battery operated mode, and AFTER doing this you can disconnect the external power supply cable.

Using the gYarpManager

iKart can be also started using the gYarpManager tool. All the ikart applications (including the navigation modules, the GUIs etc) can be started using the corresponding .xml scripts, which have to be previosuly installed with the command make install_applications from the $IKART_ROOT directory (see also the installation section )

Ikart gYarpManager.jpg

Launching from command line

This is not the recommended way to start the iKart, since there are several modules to be launched and the port connections have to be done manually. However, the procedure is here described for the sake of completeness.

$ iCubInterface --context iKart --config conf/iKart.ini 
$ iKartCtrl 
$ joystickCtrl --context joystickCtrl --from conf/ikart.ini --silent
$ yarp connect /joystickCtrl:o /ikart/joystick:i

Remember that all above modules must be launched on the iKart machine (on which also the yarp server must be already running).

Recharging the battery

Battery can be recharged both when iKart is off and when iKart is running on the external power supply.

  • Recharging the battery when iKart is off.
  1. Connect the battery recharge cable
  2. Put the power supply switch of the iKart frontal panel on the recharge position. The red led will turn on.
  3. Press the start button on the battery charger.
  4. The charger will automatically turn off when the recharge is complete.
  5. The recharge cable can be disconnected.
  6. Before turning on the iKart, remember to put battery switch back to the the external power supply position or the battery position.
  • Recharging the battery during normal operation (iKart is on).
  1. Connect the battery recharge cable. Do not disconnect the external power supply cable.
  2. Put the battery switch of the main panel on the recharge position. The red led will turn on.
  3. Press the start button on the battery charger.
  4. You can see the battery status of charge using the batteryDisplayManager application.
  5. The charger will automatically turn off when the recharge is complete.
  6. The recharge cable can be disconnected. Do not disconnect the external power supply cable.
  7. The power supply switch of the iKart frontal panel can be now put back on the external power supply position.
  • It is not possible to recharge the battery and at the same time use the battery as primary power supply with the external power supply disconnected.

iKart (re)installation

Additional information related to the installation/configuration of iKart software are reported in this section.


The two motor control boards use a firmware version which is different respect to the iCub. The firmware version is called 3.51 and the binary file can be found in $ICUB_ROOT\firmware\build\2BLL.iKart.out.S. The firmware of the boards can be upgraded using the canLoader application, as in iCub (see also: http://wiki.icub.org/wiki/CanLoader). The CAN interface must be set to socketCAN and the bus number to 0.


Esdcan driver

iKart uses an ESD CAN-USB2 interface to communicate with the motor control board. The driver of the CAN-USB2 interface is contained in the socketcan linux package (further documentation here: http://lxr.linux.no/linux+v2.6.36/Documentation/networking/can.txt). You should check the installation of the socketcan package from the the kernel module configuration menu (by launching make menuconfig from the /usr/src/linux directory). Please be sure that the following kernel modules/options are installed/enabled:

  • networking support
    • CAN bus subsystem support
      • Raw CAN Protocol
      • Broadcast Manager CAN Protocol
      • CAN Device Drivers
        • CAN bit-timing calculation

After compiling the kernel, you can check if the driver modules are correctly loaded by:

  • typing dmesg and searching for a string similar to esd_usb2 2-1:1.0: device can0 registered.
  • modprobing the modules can, can_raw, can_bcm.

Additionally to the kernel modules installation, the can-usb2 driver has to be initialized by the user before using it. This operation is automatically performed at the end of the iKart boot sequence, by a line contained in the /etc/rc.local script:

ip link set can0 up type can bitrate 1000000

After executing this command, the CAN interface will be also visible in the list of interfaces shown by the command ifconfig.

In order to final check if everthing is correctly working, you can run the canLoader application:


From the GUI, choose the socketcan interface and click on the connect button. If the list of the motor control boards appears in the window below, the CAN interface is properly configured.

Joystick driver

iKart uses the xboxdrv userspace driver (further information can be found on: http://pingus.seul.org/~grumbel/xboxdrv). Since the driver runs in the user space, no additional kernel modules are required. Instead, it is highly recommended to blacklist the xpad kernel module (which is the Ubuntu default choice) since the two drivers can enter in conflict. This operation is performed by editing the file /etc/modprobe.d/blacklist.conf and adding a line:

blacklist xpad

To install the xboxdrv userspace driver simply do:

sudo apt-get install xboxdrv

The xboxdrv userspace driver is automatically launched at the end of the iKart boot sequence by the following line of the etc/rc.local file:

xboxdrv --silent

Finally, in order to help the joystickCtrl module to properly recognize the joystick configuration (the number of axis, buttons etc) the following line has to be added to the .bashrc file.

export SDL_LINUX_JOYSTICK="'Xbox Gamepad (userspace driver)' 8 0 0"


  • If you want to stop and restart the xboxdrv driver, remember that it be executed with superuser privileges.
  • if you want to use a different joystick type, the SDL_LINUX_JOYSTICK variable has to be changed accordingly.


Serial ports /dev/TTYACM0 (laser scanner) and /dev/TTYUSB0 (battery control system) must have the right permissions in order to be accessed. Add the icub user to the dialout group with the following command:

usermod -a -G dialout icub

Serial port communication can be tested using the gtkterm utility.

  • /dev/TTYACM0 (laser) configuration:

56800 baud, 8 bits, even parity

  • /dev/TTYUSB0 (battery control system) configuration:

56800 baud, 8 bits, even parity

Start-up scripts

The main iKart start-up scripts are stored in the $IKART_ROOT\app\iKart\ikart_boot directory. In particular:

  • rc.local : It is the main script that initializes the hardware drivers. It is invoked by the operating system during the boot sequence. During the iKart installation, the script must be copied to the /etc directory. All the commands included in this file are executed with super-user privileges.
  • ikart_start.sh : It is invoked by the /etc/rc.local script. The script checks if joystick activity is detected and, if so, automatically starts the yarp server and the iKart motor interface. The script must be copied to the $ICUB_BIN directory. NOTE: By default, the yarp server launched by this script is the standard yarp server, not the yarpserver3. If you want to launch the yarpserver3 you can uncomment the corresponding line in the ikart_start.sh script.
  • ikart_stop.sh : It can be executed by the user to stop the modules previously launched by ikart_start.sh. The script must be copied to the $ICUB_BIN directory.
  • .bashrc: This script configures the user environment variables. It includes the default search paths for the yarp/icub software. The script must be copied to the $HOME directory.
  • ikart_motors_run.sh: a shortcut script that reactivates ikart motors from the idle state (e.g. if the fault button has been pressed)
  • ikart_motors_idle.sh: a shortcut script that puts the ikart motors in to the idle state.

ADDITIONAL NOTES: The following line must be added to /etc/sudoers to allow the iKartBatteryManager module to perform emergency shutdown:

icub    ALL=(ALL) NOPASSWD: /sbin/shutdown

Yarp and iCub repositories

The yarp and iCub repositories are located under the folders /usr/local/src/robot/yarp2 and /usr/local/src/robot/iCub respectively.

- GTK2.0 Rel. 2.14
- GTKMM Rel. 2.14
- QT3
- GNU Scientific Library, GSL Rel. 1.14
- OpenCV 2.0
- Open Dynamics Engine: ODE Rel. 0.10
- Simple DirectMedia Layer: SDL Rel. 1.2
- Interior Point OPTimizer library: Ipopt Rel. 3.5.0

[TO BE COMPLETED] icub-common

  • To compile the Yarp repository on the iKart, follow the steps:
cd $YARP_ROOT/build
ccmake ..

check that the following mandatory cmake options are turned on:


Once cmake has generated the makefiles, compile the yarp repository:

  • To compile the iCub repository on the iKart, follow the steps:
cd $ICUB_ROOT/main/build
ccmake ..

check that the following mandatory cmake options are turned on and generate the project:


compile the repository and install the iCub applications:

make install
make install_applications
  • To compile the ikart contrib repository, first add the following lines to the ~/.bashrc file:
EXPORT IKART_ROOT=/usr/local/src/robot/iCub/contrib/src/iKart
EXPORT IKART_DIR=/usr/local/src/robot/iCub/contrib/src/iKart/build

then run ccmake on the ikart contrib repository:

cd $IKART_ROOT/build
ccmake ..

compile the repository and install the iKart applications:

make install
make install_applications

finally append the contents of the file $IKART_ROOT/app/ikart/ikart_boot/rc.local at the bottom of the /etc/rc.local file

  • iKart also acts as a server for the Yarp and iCub repositories mounted by the PC104. These repositories are located in the folders:
- /exports/pc104/ [TO BE COMPLETED]
- /exports/pc104/ [TO BE COMPLETED]

The two repositories must be compiled from the PC104, NOT from the iKart. [TO BE COMPLETED]

Network configuration

iKart is a standard PC, so it does not require particular configuration. The PC104, instead, must be configured in order to mount the repository from the iKart machine. This configuration is suggested because in this way the repository can be always accessed by the PC104 using a wired network. Wireless mounting is discouraged.

Basic configuration

The basic iKart network configuration is contained in /etc/hosts and /etc/network/interfaces. Here an example is reported:

/etc/hosts localhost ikart pc104 console


auto lo
iface lo inet loopback
auto eth0
iface eth0 inet static

PC104 configuration

The PC104 is configured to mount the repository from the iKart. Releavant scripts can be found in the repository https://robotcub.svn.sourceforge.net/svnroot/robotcub/trunk/iCub/pc104/Debian-OS-customizations/pc104squeeze.

/etc/hosts is configured to have the following line: ikart

iKart and ROS

It is possible to interface iKart with ROS using the ikart_ros_bridge application. The application must run on a machine with both Yarp and ROS installed. We suggest to install ROS not on the iKart but on a different machine.

ROS installation

We currently tested the ikart_ros_bridge using: 1) the electric ROS distribution on a Ubuntu 11.04-natty machine. 2) the fuerte ROS distribution on a Ubuntu 12.04-precise machine. The packages included in other ROS distributions may have different names and some work may be required to make the ikart_ros_bridge properly run.

Below are reported the steps to install the suggested ROS distribution (further information can be found at http://www.ros.org/wiki/fuerte/Installation/Ubuntu)

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu precise main" > /etc/apt/sources.list.d/ros-latest.list'
wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
sudo apt-get update
sudo apt-get install ros-fuerte-desktop-full

After the installation, the ~/bash_icub_env file must be edited to set the new environment variables:

source /opt/ros/fuerte/setup.bash
export ROS_ROOT=/opt/ros/fuerte/ros
export PATH=$ROS_ROOT/bin:$PATH
export PYTHONPATH=$ROS_ROOT/core/roslib/src:$PYTHONPATH
export ROS_PACKAGE_PATH=~/ros_workspace:/opt/ros/fuerte/stacks:$ROS_PACKAGE_PATH

Additional info: http://www.ros.org/wiki/ROS/Tutorials/InstallingandConfiguringROSEnvironment

The iKart ros bridge

The ikart_ros_bridge module connects to the output ports opened by the iKartCtrl module and publish the corresponding topics onto the ROS workspace. Viceversa, motor commands sent by a generic ROS node can be translated by the ikart_ros_bridge into the proper commands which can be executed by the iKartCtrl module.

Ports and topics accessed by ikart_ros_bridge

A list of the yarp ports / ros topics used by ikart_ros_bridge is reported below:

ikart_ros_bridge input ports:

  • /ikart_ros_bridge/laser:i: it receives the laser scanner data from /iKartCtrl/laser:o
  • /ikart_ros_bridge/odometry:i: it receives the odometry data from /iKartCtrl/odometry:o
  • /ikart_ros_bridge/odometer:i: it receives the odometer data from /iKartCtrl/odometer:o
  • /ikart_ros_bridge/goal:i: it receives the user goal to be sent to the ROS navigation stack.

ikart_ros_bridge output ports:

  • /ikart_ros_bridge/command:o it broadcast the current iKart velocity commands to be sent to /iKartCtrl/command:i
  • /ikart_ros_bridge/localization:oit broadcast the current iKart localized position.

ikart_ros_bridge subscribed topics:

  • /cmd_vel: it receives the iKart velocity commands computed by the navigation stack.
  • /tf: it receives the transformations related to the reference frames: <map>, <odom>.

ikart_ros_bridge published topics:

  • /tf: it broadcasts the transformations related to the reference frames: <base_link>, <base_laser>, <home>.
  • /ikart_ros_bridge/laser_out: it broadcasts the received laser scanner data.
  • /ikart_ros_bridge/odometry_out: it broadcasts the received odometry data.
  • /ikart_ros_bridge/odometer_out: it broadcasts the received odometer data.

In the picture below are shown the connections between ikart_ros_bridge and the other applications during a typical navigation demo (click to enlarge):

Ikart ros bridge connection.jpg

Compiling iKart_ros_bridge

Before compiling, you have to configure your environment.

gedit .bashrc

add the path to source folder of iKartRosBridge to the ROS_PACKAGE_PATH environment variable. For example:

export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:/usr/local/src/robot/iCub/contrib/src/iKart/src/iKartRosBridge

Now you can compile the ikart_ros_bridge



Running the ikart_ros_bridge

1.Check that the machine can reach the yarp nameserver located on the iKart:

yarp check

if there are problems, verify that:

  • you can can ping the iKart
ping ikart
  • you are using the correct yarp namespace
yarp namespace <your_namespace_name>

If you still cannot find the nameserver, maybe a wrong default nameserver address has been saved in the configuration of your machine. You can force Yarp to find the nameserver on the specific iKart ip address and save this configuration using the command:

yarp conf <ikart_ip_address> 10000 --write

2.Start the ROS name server:


3.Start the core iKart applications (joystickCtrl, iKartCtrl etc.) Further information are reported in iKart user manual section: http://wiki.icub.org/wiki/IKart#Starting_the_robot

4.Start the ikart_ros_bridge application:


Reference frames used by ikart_ros_bridge

The ikart_ros_bridge applications uses the following reference frames uner the /tf topic.

  • <base_link> internal use only.
  • <ikart_root> the mobile base local reference system. gotoRel <x> <y> <angle> commands (see [here]) are expressed in this reference system.
  • <base_laser> the frontal laser scanner reference system. It is linked to <ikart_root>
  • <robot_root> the standard iCub root reference frame (definition here). It's linked to <ikart_root>.
  • <map> It is the fixed world reference frame. It is broadcasted by the ROS map server. The origin of this reference frames is constant and saved in the map file.
  • <home> The user can change the location of the <home> reference frame using the set home RPC command. By default <home> = <map>. If <home> is changed, the position of the mobile platform is expressed <home>. ikart_ros_bridge broadcasts the localized position of the iKart on the /ikart_ros_bridge/localized:o yarp port. gotoAbs <x> <y> <angle> commands (see [here) are expressed in this reference system.
  • <odom> If the map-localization is not employed, <odom> represents the fixed world reference frame. However the origin of this reference frames is not constant: it corresponds to the point where the ikartCtrl has been started (or its odometry has been resetted from the user). This reference frame is not published if ikart_ros_bridge is launched using the option --no_odom_tf.
  • <userXX> the user can set its own reference frames by sending a set frame RPC ommand. The <userXX> frames are expressed in the <world> fixed reference frame.

In the picture below is shown the tree of the reference frames, as shown by the ROS view_frames utility:

rosrun tf view_frames


In the picture below, a example screenshot is taken from rviz to display some of the transformations between the above mentioned reference frames. <map> is the fixed reference frame. <ikart_root> and <robot_root> are the local reference frames.


RPC commands used by ikart_ros_bridge

The ikart_ros_bridge module provides a port /ikart_ros_bridge/rpc which can be used by the user to send rpc commands. Below is reported a list of the available rpc commands:

  • help displays the list of the available commands
  • set home <x> <y> <angle> set the origin and the orientation of the <home> reference frame. The provided values must be expressed in the <map> reference frame.
  • set current home set the origin and the orientation of the <home> reference frame using the current position of the iKart.

Additionally, the following three commands are used to interact with the ROS navigation stack (more on this here):

  • gotoAbs <x> <y> <angle> set the goal for a navigation task, expressed in the <home> reference frame.
  • gotoRel <x> <y> <angle> set the goal for a navigation task, expressed in the <ikart_root> reference frame.
  • stop stops a current navigation task

Running the SLAM gmapping node

The following script will start the gmapping node and the ROS visualizer rviz:

roslaunch ikart_build_map.launch

Please refer to gmapping package documentation for further information about the configuration parameters used inside the script: http://www.ros.org/wiki/gmapping


When you are satisfied with the map create with gmapping, you can save it to a file:

rosrun map_server map_saver -f map_filename

Alternatively you can run the shortcut:

$IKART_ROS_BRIDGE/launch/save_map.sh map_filename

Note: You can edit the saved map using a standard graphical editor: the color codes used for each pixel are used to represent blocking wall (black) or free areas (light grey). By adding black lines or clearing areas on the map you can instruct the navigation package to keep away the robot from those area or grant access to them.

Loading a previously saved map

The gmapping node is used to create a map of environment. During the normal operation/navigation, instead, you may want just to localize the ikart into a previously saved map. A saved map can be loaded using the command:

rosrun map_server map_server map_filename.yaml

Alternatively you can run the shortcut:

$IKART_ROS_BRIDGE/launch/load_map.sh map_filename

Running the AMCL localization on a previously saved map

The localization task is performed by the AMCL (Adaptive Monte Carlo Localization) module.

This module allows to compensate for the integral error of the wheels odometry, providing an accurate estimation of the robot position respect to a fixed reference frame.

x x

The AMCL module can be configured to estimate the robot position using:

  • the laser data AND the wheels odometry.
  • the laser data only.

Using AMCL with iKart wheels odometry

This is the classical way to run AMCL. The odometry information and the laser scans are obtained from the ikartRosBridge module (through the /tf topic and the /ikart_ros_bridge/laser_out topics). All configuration parameters are included in the script:

roslaunch ikart_localize.launch

Using AMCL with estimated laser odometry

Recently we investigated the accuracy of the estimated wheels odometry. Since it may happen that on certain surfaces the wheels have a not negligible slippage, is it possible to prevent AMCL to use the wheel odometry data, and use only the laser information. To do so, it's required to run a ROS module called laser_scan_matcher, which estimates the odometry using the laser information. Currently the laser_scan_matcher is not included in standard ros distribution, but you can follow the installation instructions provided here.

The following script contains all the required configuration to run AMCL with laser_scan_matcher. Please note that the iKartRosBridge must be launched using the --no_odom_tf option, otherwise it will enter in conflict with the odometry estimation provided by the laser_scan_matcher module.

roslaunch ikart_laseronly_localize.launch

Example scripts

The following example scripts can be used to start/stop all AMCL-related ROS modules at once:

to start: roscore, iKartRosBridge, mapserver, amcl and rviz

to start: roscore, iKartRosBridge, laser_scan_matcher, mapserver, amcl and rviz

to stop all the ros modules including iKartRosBridge, mapserver, amcl and rviz

Guess of the initial pose

The localization node must be initialized giving to the node an estimated position of iKart on the map. This guess initial position must be published on the /initialpose topic. The AMCL node will then try to localize the iKart by searching a match between the received laser scans and the map, updating this information with the odometry data. In order to facilitate the localization process, it is a important to give to the node a good guess of the robot initial position.

You can also specify the iKart initial pose graphically, using the 2D Pose Estimate tool of the ROS graphical interface rviz: click on the map and drag an arrow to select the orientation (keyboard shortcut: 'p').

After having set a reasonable good guess of the initial position, the estimated localization of the robot will automatically improve as soon as it moves around, as shown in the following sequence of pictures (the red uncertainty cloud progressively reduces, just rotating the robot on place).


For further information about the AMCL pacakge, refer to the official documentation: http://www.ros.org/wiki/amcl

Opening the visual GUI rviz

You can use one of the following scripts (the display is optimized for the different tasks):

roslaunch rviz_build_map.launch
roslaunch rviz_navigate.launch

Issues related to rviz

As reported in the rviz manual, there are several issues the affect the module, most of the them related to the opening/redirection of the display and the use of the 3D hardware acceleration. In particular, if rviz segfaults during the startup, it is most likely that your system does not supports the default rendering mode, called PBuffer. You can change it by using one of the three following modes:

export OGRE_RTT_MODE=PBuffer (default)
export OGRE_RTT_MODE=Copy

Additional info about this issue can be found here: http://www.ros.org/wiki/rviz/Troubleshooting

NOTE: Currently it's not possible to run rviz in VirtualBox, since the 3D hardware acceleration is not supported yet.

Autonomous navigation

Several modules can bu used to perform autonomous navigation tasks.

  • iKartNav
  • iKartGoto
  • iKartPathPlanner <--- currently, the preferred choice
  • the ROS navigation stack

A very quick comparison between the module capabilities is shown in the following table:


Standard navigation commands and navigation status

All these modules can be controlled using the same interface, i.e. sending one of the following command to their rpc port:

  • "gotoAbs" <x> <y> <angle> sets as goal the coordinates <x>, <y>, <angle> expressed in the world reference frame. <angle> is optional, if not the specified the robot will maintain the orientation assumed during the navigation path.
  • "gotoRel" <x> <y> <angle> sets as goal the coordinates <x>, <y>, <angle> expressed in the mobile base reference frame. <angle> is optional, if not specified the robot will maintain the orientation assumed during the navigation path.
  • "stop"
  • "pause"
  • "resume"
  • "quit"

In the following sections these commands are referred as standard navigation commands.

NOTE: The orientation of the world (absolute) and the local (relative) reference frames has been previously defined here

The navigation modules have also a standard description of their internal status, typically broadcasted through a yarp port (e.g. /XXX/status:o) or accessible on rpc request. Currently, seven possible statuses are implemented (status.h).

  • IDLE: the navigation module is ready to receive a new goal command.
  • MOVING: the robot is currently moving to reach the commanded target. Depending on the module, it may be able or not to receive a new goto command.
  • WAITING_OBSTACLE: The robot is trying to reach the commanded target, but an obstacle is currently blocking the path. Depending on the module, a timeout event can be triggered stopping the navigation if the obstacle is not removed after a certain amount of time.
  • REACHED: the last goto command has been successfully executed (goal reached).
  • ABORTED: the module detected a deadlock status which prevents the goal to be reached (e.g. an obstacle is obstructing the path, or no path can be found).
  • PAUSED: the module has paused the navigation task with a "pause" command. It can be resumed with a "resume" command.
  • THINKING: the new goal has been accepted and the module is currently computing the path.

The possible status transitions are depicted in the picture below.



iKartNav is reactive navigation module: the platform uses only its sensory information (e.g. the odometry, the laser scanner) to locally compute the movement direction towards the goal. No a-priori knowledge of the environment (e.g. map) is used. This is particularly useful when it is required to perform a navigation task in an unknown, unmapped environment. On the other hand the path followed by the robot may be sub-optimal in complex environments: in this case large areas have to be explored before finding the right t path to the goal. The navigation algorithm is based on the artificial potential fields. The goal represents the attractor, while the obstacles detected by the laser scanner generate a repulsive potential field. The intensity of this potential field is given by the equation:

Ikart nav eq1.jpg

We can define the associated repulsive force f as:

  • Ikart nav eq2.jpg

Additionally we define two unit vectors g,t as follows:

  • g: the normalized direction towards the goal
  • t: the normal unit vector to the repulsive force f (thus tangent to the equipotential line U=UM)

The direction of the robot v is thus computed as the weighted superimposition of the attractive and repulsive forces:

v = wg g + wf f + wt t

where the weights wg, wf, wt are care set accordingly to the following rules:

  • wg = 1 - UM if t · g >= 0
  • wg = 0 if t · g < 0
  • wf = UM2
  • wt = UM

In the above formula the attractor towards the target g is prevalent when the robot is far from obstacles, and it is overridden by f and t when close to the obstacles. Being UM =maxi{Ui} ∈ [0;1], the tangent part t is felt before the repulsive part f, so the repulsive part is used as an emergency repulsive force when the robot gets very close to the obstacle.

Ikart nav1.jpg

Additional info:

  • Ros/map are not used.

How to use:


iKartGoto is a basic point-to-point navigation module which executes straight trajectory from the robot current location to the user-specified goal. Since the module is only able to generate straight trajectories (eventually corrected to avoid an obstacle on the path), the module is not suited for complex navigation tasks in structured environments. Instead iKartGoto is thought to ensure the robot to reach a pre-computed waypoint of a more complex path.

In order to guarantee the reaching of the specified goal, the module internally uses a PID controller whose feed-back is constituted by the current position of the mobile base (obtained either from the robot's odometry or from an external map localization module, such as AMCL).

The module also implements an obstacle detection/avoidance mechanism. The two different behaviors, corresponding to two different detection areas (A and B in the picture below) can be independently activated by the the user. The obstacle avoidance behavior activates when an obstacle is detected in the lateral 'A' areas. In this case the robot will correct his trajectory, according to the repulsive potential field generated by the obstacle. Instead, if an obstacle is detected in the frontal 'B' area, corresponding to the movement direction, the robot will stop and wait until the obstacle is removed. If the object is not removed by the user, a timeout event will be triggered and the navigation command will terminate.

y y

As mentioned before, iKartGoto is used to perform simple point-to-point navigation tasks or to track a sequence of waypoints pre-computed by a path planner. In this latter case the module does not accepts new goals until the current destination is reached (if the user wants to send a new goal, a stop command has to be sent first). When the current goal is reached, a status is

Additional info:

  • iKartGoto is used by the iKartPathPlanner module to track the computed waypoints.
  • The navigation speed, the goal tolerance and the parameters controlling the obstacle avoidance behavior are stored in the iKartGoto.ini file.
  • Laser odometry (and not wheel odometry) is suggested for this type of navigation (read again here)

How to use:

  • Start ROS and the localization service with the script ros_start_all_no_odom.sh (you have to load you load your own map)
  • Launch the iKartGoto.xml application.


The iKartPathPlanner module allows to perform complex navigation tasks (i.e. reaching a different room on the provided map) by computing a waypoint-point based path. When the module is launched, the provided map file is internally converted to graph representation, in which each node corresponds to a square cell of fixed sized (typically 5x5cm). Obstacles (e.g. walls, corners etc.) are enlarged taking in account the diameter of the mobile base, in order to simplify the computation of the navigation path. When the user issues a new navigation command, the plan is computed by performing an A* search on the graph and the raw set of nodes corresponding to the minimum path is returned. The path is subsequently refined by reducing the set of employed waypoints to those whose direct connection does not cross an obstacle. Depending on the complexity of the map and the position of the goal,the algorithm may take few seconds to compute the path. Once that the global navigation plan is computed, each waypoint is sequentially sent to the local point-to-point trajectory executor (e.g. the iKartGoto module) that will pursue the local goals one after the other, until the final destination is reached.


The position of the mobile platform and the current path is sent through a yarp port in order to be visualized using the standard yarpview tool.


Additional info:

  • Laser odometry (and not wheel odometry) is suggested for this type of navigation (read again here)

How to use:

  • Start ROS and the localization service with the script ros_start_all_no_odom.sh (you have to load you load your own map)
  • Launch the iKartPathPlanner.xml application.

the ROS navigation stack

Another possibility is to directly use the ROS navigation stack. You can start the navigation stack launching the following script (the AMCL node must be already running):

roslaunch ikart_navigation.launch

You can send one of the standard navigation commands to the navigation stack using the port /ikart_ros_bridge/command:i

The motor control output coming from ikart_ros_bridge has to be connected to the ikartCtrl:

yarp connect /ikart_ros_bridge/command:o /ikart/control:i

You can also send navigation commands using the 2D nav goal tool of the ROS graphical interface rviz: click on a location on the map a drag an arrow to select the orientation (keyboard shortcut: 'g')

For further information about the navigation stack, refer to the official documentation: http://www.ros.org/wiki/navigation

iKart dimensions

In the picture below are reported the most significative measurements related to the odometry computation and the main geometric transformations between the iKart reference frames.

Image ikart_dimensions.jpg

Important things to remember

  • The external power supply settings are different respect to the iCub. The supply voltage must be set to 52.5V ant the current limit to 18A.
  • The iCub configuration file must be edited in order to disable the robot legs.
  • When moving around the iKart, be sure that the arms are put in a safe position (i.e. not fully extended) in order to avoid collisions with the surrounding environment.
  • Remember to replace the wireless joystick batteries regularly.
  • NEVER plug/unplug the power cable connecting the icub to the ikart if the power supply switches of the pc104/motors are on. Failing to do this will seriously damage the electronics!

Common customizations

Using grub

It's possible to use grub to install multiple OS on the iKart (NB: since the iKart is not equipped with keyboard/video, a default selection and a timeout has to be defined). Some users have pointed out that if the iKart hangs up (it may happen), the default grub behavior is to turn off the timeout, in order to let the user to select which entry to boot. This however has a drawback: the machine will wait indefinitely for the user input, but the user does not know what is really happening (because there is no video) and it's leaded to think that the machine is stuck. To fix this problem, Linux forums suggest to edit the file /etc/grub.d/00_header with the code below (not tried yet):

cat << EOF
if [ \${recordfail} = 1 ]; then
  set timeout=-1
  set timeout=${GRUB_TIMEOUT}


If you have questions, or you experience difficulties, please contact the rc-hackers mailing list: robotcub-hackers@lists.sourceforge.net