Manual

From Wiki for RobotCub and Friends

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 to the robotcub-hackers mailing list.

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

Contents 1 One. Hardware of the iCub 2 Two. Troubleshooting of the hardware 3 Three. Calibration 4 Four. Protocols 5 Five. Kinematics and Dynamics 6 Six. Software, Compiling YARP and iCub 7 Seven. Software, YARP 8 Eight. Software, dependencies 9 Nine. Software, iCub 10 Ten. Standardization of methods 11 Eleven. Guidelines 12 Twelve. Documentation 13 Thirteen. Committing changes 14 Fourteen. How to install the robot 15 Fifteen. Unofficial documentation 16 Sixteen. Known issues 17 Acknowledgments

One. Hardware of the iCub

To obtain the CAD and 2D drawings describing the mechanical and electronic parts which are presented in this chapter please follow this link. 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. For certain component, a link to the vendor website is available.

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

1. Parts and specifications: see the bill of materials extracted from the CAD
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. Quad-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
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. Other components: see the bill of materials (above)

Two. Troubleshooting of the hardware

1. Connectors
2. Cabling tools required: list as xls file
3. Tendons and replacement
4. Crimps
5. Common problems and solutions
   • Assembly instructions
   • Electrical wiring
6. 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
   • Arm Calibration Procedure
   • Head Torso Calibration Procedure
2. Fine calibration of the iCub:
   • Torso fine calibration
   • Head fine calibration
   • Arm fine calibration
   • Legs fine calibration
3. Calibration files, details
4. Available sensors, encoders, currents

Four. Protocols

1. CAN bus protocol and messages: see here
2. YARP protocols: port protocol, name server protocol
3. Other protocols
4. Software and hardware tools to analyse the protocols

Five. Kinematics and Dynamics

1. iCub joints specification: naming, conventions
   • Note: the kinematic is not final yet. The robot is of course final, the documentation is to be improved here.
2. iCub Forward Kinematic specification, D-H parameters (unmodified convention):
3. Vergence, version and binocular disparity quantities for motor control Vergence, Version and Disparity.
4. iCub dynamics
5. iKin: library for forward\inverse kinematic and control tasks; some iKin-based modules (e.g. iKinArmCtrl) are available as well. iKin requires IPOPT. Look how to install IPOPT here: Installing IPOPT.

Six. Software, Compiling YARP and iCub

In this section we guide you through the installation process of the YARP and iCub software.

Important: the software can compile on different platform, however we support only Windows and Linux Debian/Ubuntu. On Windows we support Visual Studio (>=8.0), on Linux gcc. See Section 15 for (experimental) instructions for Mac OS X.

Follow these steps:

1. Prepare your system
   • Libraries and Development Environment: Linux
   • Libraries and Development Environment: Windows
   • Get a Subversion client
   • Client typical flags for subversion
   • Check your system (optional)
2. Getting the software
   • Getting YARP
   • Getting the iCub software
3. Setup your environment
   • Compile environment (Linux, Windows)
4. CMake utility
   • Some info about CMake and tips about CMake problems
5. How to compile everything:
   1. Compilation in Linux
   2. Compilation in Windows
6. Compile YARP and the iCub software on the pc104
   • Compilation on the pc104

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. How to include a new device driver into YARP (and iCub)
12. How to add a new carrier
13. How to create a new Portable
14. YARP documentation, a general tutorial, and additional Wiki pages on Yarp

Eight. Software, dependencies

Compiling YARP and iCub requires some dependencies are met.

1. Device drivers
2. Libraries, supported compilers and tools:
   • List of Dependencies
   • Installation instructions: see Section 6.1 (Prepare your system).

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. iCub architecture, an introduction
   • iCub Software Architecture
   • iCub Cognitive Architecture
   • Software Implementation of the iCub Cognitive Architecture (Version 2.0)
3. Automation
   • Running applications
4. Software interface: standard port names for hardware devices
5. Documentation of key modules
   1. iCubInterface2 documentation and configuration file description.
   2. Framegrabber parameters: Dragonfly Parameters
   3. Running devices for the iCub
   4. What runs on the PC104 CPU
   5. ControlBoard config file, interfaces and examples: motor control in yarp and a simple tutorial on motor control
   6. Getting sensory data: inertia sensor, sound, images, encoders, forces, etc.
6. Simulators:
   1. The ODE simulator, installation and manual
7. Tools:
   1. Debugging tools
   2. Firmware update tools: (see also the list of CAN adresses).
   3. Other software tools:
      1. Online documentation for tools: http://eris.liralab.it/iCub/dox/html/group__icub__tools.html
      2. Guis: http://eris.liralab.it/iCub/dox/html/group__icub__guis.html
   4. Note on firmware versions: firmware versions
   5. Firmware source and build: more firmware in repository
   6. List of can addresses and associated firmware
8. Starting up the iCub: see here
9. Learning about the software:
   • Some iCub code tutorials: http://eris.liralab.it/iCub/dox/html/icub_tutorials.html
10. Software troubleshooting: solutions to common problems.

Ten. 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.
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
   • Configuration and resource files
4. Preparing scripts for an application
5. Cluster, example configuration and networking
   • Some old material: click here
6. Licensing

Eleven. Guidelines

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

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

Twelve. Documentation

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

Thirteen. Committing changes

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

Fourteen. How to install the robot

1. How to install the robot: installing_icub
2. Installation videos:
   • video_1: How to remove the robot from the box and fix it on a table: http://eris.liralab.it/misc/videos/video_1.wmv
   • video_2: How to connect the power suppliers: http://eris.liralab.it/misc/videos/video_2.wmv
   • video_3: how to set the power suppliers and how to connect the robot: http://eris.liralab.it/misc/videos/video_3.wmv

• Temporary page: upgrading repositories to svn: Upgrading the pc104 software repositories to subversion

Fifteen. Unofficial documentation

Place here pages contributed by users.

1. Testing the robot. Getting the attention system running
2. Installation of the software on Mac OS X:
   • Libraries and Development Environment: Mac OS X
   • Compile environment (Mac OS X)
   • Compilation in Mac OS X (experimental)
   • Getting the simulator to work on Mac OS X
3. Tweaking particular modules for MacOS X:
   • Getting the ARToolKit module to work on the Mac
4. SSH remote calls. Getting SSH to read your environment variables

Sixteen. Known issues

A list of known issues which will be fixed soon or later depending on their relevance.

1. Risk of shoulder failure during the calibration.
2. Wrist prono-supination backlash.
3. Wrist abduction calibration and positioning issues.
4. Difficulties in achieving a good cameras alignment.
5. Black camera images due to wear on camera flat cable .
6. Huge backlash on the eyes pan movement.
7. Limitations on the shoulder range of movements.
8. Control issues in positioning the hand joints.
9. Control issues in the shoulder coupling.
10. Export display from the PC104: ssh -X icub@pc104 .
11. Issue with the power supply switches.

Acknowledgments

List people who contributed to this manual.