Manual

The iCub

This is the official iCub user-manual. It includes description of the procedures to install (Chapter 14) and maintain the platform, both at the hardware (Chapter 2) and software (Chapters 7 8 9) level. The sections describing the software will also describe how to install and use what is available with the robot and provide guidelines on how to develop new capabilities and algorithms.

• Structure of the manual: this document is an attempt in coalescing the robot knowledge into a linear document/manual. Emphasis on linear.

• How get additional help: please write any question by opening an issue in the robotology/QA GitHub repository.

• How to contribute: we welcome contributions and suggestions, but please add new pages to Section 16. From time to time we will incorporate new pages into the other sections of the manual.

• Citing our work: as researchers we live on citations. We provide a list of papers you are invited to cite in your papers that use the iCub or some of its components, see Section Acknowledgements (below).

One. Hardware of the iCub

To obtain the 3D mechanical drawings (CAD) and 2D production drawings describing the mechanical and electronic parts, please check out the: iCub SVN Repository.

This section overlaps consistently with the Deliverable 8.1 (specifications of the iCub open system). This section of the manual is meant to be used by first opening the bill of materials, reading the component type and then consulting the corresponding description in the subsections below.

The philosophy of this chapter is to provide links and references to the technical documentation and not necessarily to substitute it.

1. ICub Project Mechanical Documentation and Design Conventions
2. Brushless motors
3. DC motors
4. Controller cards
5. Motorola DSP and CodeWarrior
6. Other boards datasheets
7. Cameras
8. Microphones
9. Inertial sensing
10. CAN bus interface for debugging (ESD)
11. CFW CAN bus interface
12. Hall-effect readings, electronics
13. Force/torque sensors, electronics
14. Face specifications and control
15. Cables
16. Power supply
17. Wiring, general diagrams and details of the connections NEW!!!
18. Encoder magnets
19. Springs, belts and cables
20. CPU board PC104
21. Ball bearings
22. Commercial mechanical parts
23. Commercial electronic parts
24. iCub stand
25. iCub plastic covers
26. Available iCub versions

Two. Troubleshooting of the hardware

1. Tendons replacement
2. Common problems and solutions
   • Assembly instructions
   • Electrical wiring
   • iCubInterface Errors
   • Check of pronosupination joint
   • Connect VGA Cable to PC104
3. iCub required maintenance and cabling tool: list as xls file
4. In any case you can post your questions to the robotcub-hackers mailing list.

Three. Calibration

1. Initial calibration of the iCub:
   • Legs Calibration Procedure
   • Head Torso Calibration Procedure
   • Hand Arm Calibration Procedure for iCubV1.1-2-3)
   • (discontinued) Arm Calibration Procedure V1.0
2. Fine calibration of the iCub:
   • Torso fine calibration
   • Head fine calibration
   • Arm fine calibration
   • Legs fine calibration
3. Calibration types available on iCub and R1 robots

Four. Protocols

1. CAN bus protocol and messages: see here
2. YARP protocols: port protocol, name server protocol

Five. Kinematics and Dynamics

1. iCub joints specification: naming, conventions
2. iCub joints limits: CAD, hardware, software limits
3. iCub Forward Kinematic specification, D-H parameters (unmodified convention):
4. Vergence, version and binocular disparity quantities for motor control Vergence, Version and Disparity.
5. iKin: library for forward\inverse kinematic and control tasks; some iKin-based modules (e.g. iKinArmCtrlIF) are available as well. iKin requires IPOPT. Look how to install IPOPT here: Installing IPOPT.
6. iCub dynamics
   • iDyn: generic library for dynamics

Six. Software, Installing YARP and iCub

• Installation Instructions.
• Check the Installation.

Seven. Software, YARP

1. The architecture
2. The YARP companion and YARP executables
3. Scriptable stuff
4. CMake files, preparation
5. Basic OS classes
6. Basic communication classes
7. Advanced OS classes
8. Advanced communication classes
9. Device drivers, existing
10. Device drivers, how to write a new one, tutorial on building a new device in YARP. Important: see also how to compile the iCub devices
11. YARP documentation, a general tutorial, and additional Wiki pages on Yarp

Eight. Software, dependencies

Compiling YARP and iCub requires some dependencies are met.

1. Libraries, supported compilers and tools:
   • List of Dependencies
   • Installation instructions: see Section 6.
2. On the robot: Device drivers

Nine. Software, iCub

This section explains how the software is organized. Here you will find more details about how we the repository, modules and applications.

1. The Linux on the pc104
2. Configuration files
3. iCub architecture, an introduction
   • iCub Software Architecture
   • iCub Cognitive Architecture
   • Software Implementation of the iCub Cognitive Architecture (Version 2.0)
4. Automation
   • Running applications
5. Software interface: standard port names for hardware devices
6. Documentation of key modules
   1. iCubInterface documentation and configuration file description.
   2. Framegrabber parameters: Dragonfly Parameters
   3. Getting 640x480 images at framerate: Getting 640x480 images
   4. ControlBoard config file
   5. Using force control on iCub
   6. >>> NEW: controlling the iCub with new Yarp interfaces iControlMode and iInteractionMode <<<
   7. Camera Calibration
   8. The ODE simulator is installed with the software (see Section 6)
   9. Firmware update tools
   10. List of CAN addresses and associated firmware.
   11. Other software tools:
       1. Online documentation for tools: http://wiki.icub.org/iCub/main/dox/html/group__icub__tools.html
       2. Guis: http://wiki.icub.org/iCub/main/dox/html/group__icub__guis.html
   12. Note on firmware versions: firmware versions
   13. Firmware source and build: more firmware in repository
7. Starting up the iCub: see here
8. Learning about the software:
   • Some iCub code tutorials: http://wiki.icub.org/iCub/main/dox/html/icub_tutorials.html
9. Interoperability with other languages and middleware

Ten. Robot configuration

• documentation regarding the configuration of ethernet based robots: see here

Eleven. Standardization of methods

1. Organization of the repository:
   • Organization of sources, binaries, applications and config files
   • New repository. This page contains a long description of the new build system, namespaces and file conventions.
   • Applications. This page contains a descriptions about how applications are stored in the repository and installed.
2. CMake Usage
3. Modules, standardization, configuration
   • How to write a module
   • Here is a summary of the software development guidelines of the cognitive architecture
4. Licensing

Twelve. Guidelines

Here we describe better practices for software development on the iCub.

1. Coding styles
2. Naming Conventions (modules, ports, etc...)

Thirteen. Documentation

1. Writing new documentation
2. Where is the documentation?
3. Documents that aren't connected to the source code
   • Document location
4. ChangeLog

Fourteen. Committing changes

1. Software
2. Hardware
3. Contributing to the Manual

Fifteen. How to install the robot

ADDED NEW VIDEOS !!!

1. How to install the robot: Installation of the robot.
2. Installation instructions for the iCub laptop/server: Laptop installation instructions.
3. Temporary page: upgrading repositories to svn: Upgrading the pc104 software repositories to subversion.

Sixteen. The iKart mobile platform

1. Installation and usage of the iKart mobile platform is described in the iKart manual

Seventeen. Talking head

1. Talking head documentation

Eighteen. Unofficial documentation

Place here pages contributed by users.

• Instructions for compilation on Mac OS have been moved to the installation page (see Section 6).
• SSH remote calls. Getting SSH to read your environment variables

Nineteen. Known issues and troubleshooting

In this section we include a list of known issues and suggestions on how to troubleshoot them:

1. Hardware known issues
2. Software troubleshooting

Twenty. Doxygen documentation links

See Chapter 12 for iCub and YARP documentation.

A list of links to existing documentation for various iCub-related projects.

From non-standard repositories...

1. the EU CHRIS project (FP7 ICT-215805): click here
2. the EU ITALK project (FP7 ICT-214668):click here
3. the EU EFAA project (FP7 ICT-270490): click here
4. the EU Xperience project (FP7 ICT-270273): click here

In need of documentation...

1. the EU RoboSKIN project middleware (FP7 ICT-231500), see www.roboskin.eu

Acknowledgments

This is a list of people how contributed to the manual: List people who contributed to this manual.

Citing our work. We warmly invite you to cite the following papers when you use the iCub or one of its components in your work: Citations.