Motivations: This is the first draft of the user-manual of the iCub. It includes description of the procedures to install and maintain the platform, both at the hardware and software 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.
This document is an attempt in coalescing the robot knowledge into a linear document/manual. Emphasis on linear.
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.
- 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 Fifteeen. Unofficial documentation
- 16 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.
- Parts and specifications: see the bill of materials extracted from the CAD
- Brushless motors
- DC motors
- Controller cards
- Motorola DSP and CodeWarrior
- Other boards datasheets
- Inertial sensing
- CAN bus interface for debugging (ESD)
- Quad-CAN bus interface
- Hall-effect readings, electronics
- Force/torque sensors, electronics
- Face specifications and control
- Power supply
- Wiring, general diagrams and details of the connections
- Encoder magnets
- Springs, belts and cables
- CPU board PC104
- Ball bearings
- Commercial mechanical parts
- Commercial electronic parts
- iCub stand
- Other components: see the bill of materials (above)
Two. Troubleshooting of the hardware
- Cabling tools required: list as xls file
- Tendons and replacement
- Common problems and solutions
- DSP code: firmware versions
- Other firmware code: more firmware in repository
- Initial calibration of the iCub:
- Fine calibration of the iCub:
- Calibration files, details
- Available sensors, encoders, currents
- CAN bus protocol and messages: see here
- YARP protocols: port protocol, name server protocol
- Other protocols
- Software and hardware tools to analyse the protocols
Five. Kinematics and Dynamics
- 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.
- iCub kinematics ICubForwardKinematics, D-H parameters (unmodified convention):
- Vergence, version and binocular disparity quantities for motor control Vergence, Version and Disparity.
- iCub dynamics
- 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:
- Prepare your system
- Getting the software
- Setup your environment
- CMake utility
- How to compile everything:
- Compile YARP and the iCub software on the pc104
Seven. Software, YARP
- The architecture
- The YARP companion and YARP executables
- Scriptable stuff
- CMake files, preparation
- Basic OS classes
- Basic communication classes
- Advanced OS classes
- Advanced communication classes
- Device drivers, existing
- 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
- How to include a new device driver into YARP (and iCub)
- How to add a new carrier
- How to create a new Portable
- YARP documentation, a general tutorial, and additional Wiki pages on Yarp
Eight. Software, dependencies
Compiling YARP and iCub requires some dependencies are met.
- Device drivers
- 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.
- The Linux on the pc104
- iCub architecture, an introduction
- Software interface: standard port names for hardware devices
- Documentation of key modules
- iCubInterface2 documentation and configuration file description.
- Framegrabber parameters: Dragonfly Parameters
- Running devices for the iCub
- What runs on the PC104 CPU
- ControlBoard config file, interfaces and examples: motor control in yarp and a simple tutorial on motor control
- Getting sensory data: inertia sensor, sound, images, encoders, forces, etc.
- Debugging tools
- Firmware: update tools and version descriptions.
- Starting up the iCub: see here
Ten. Standardization of methods
- Organization of the repository:
- Organization of sources, binaries, applications and config files
- Here is a summary of the software development guidelines of the cognitive architecture
- Cluster, example configuration and networking
- Some old material: click here
- Modules, standardization, configuration
- Preparing scripts for an application
Here we describe better practices for software development on the iCub.
- Coding styles
- Things to avoid
- Naming of ports, variables, scripts, modules, etc
- Module names in the iCub repository (and therefore module directory names as well) conform to the convention 'wordOneWordTwo'. Changing the CVS structures requires some updates (SUBDIRS, CMakeLists.txt's etc.) if they're not already that way. We moved the "qGui"s to the gui folder, naming them 'guiXy' so if a user wants to look for a gui it is easy to type gui+<tab> and all gui's show up (dropping furthermore the 'q' as it is not interesting for a user what library is used).
- Other conventions
- Compiling the documentation
- Writing new documentation
- About modules: http://eris.liralab.it/iCub/dox/html/module_documentation.html
- About applications: http://eris.liralab.it/iCub/dox/html/application_documentation.html
- Servers, online material
- Documents that aren't connected to the source code
Thirteen. Committing changes
Fourteen. How to install the robot
- How to install the robot: installing_icub
- 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
Fifteeen. Unofficial documentation
Place here pages contributed by users.
- Testing the robot. Getting the attention system running
- Installation of the software on Mac OS X:
- Tweaking particular modules for MacOS X:
- SSH remote calls. Getting SSH to read your environment variables