Manual

From Wiki for iCub and Friends
Revision as of 20:05, 27 July 2011 by Paulfitz (talk | contribs) (Fifteen. Unofficial documentation)
Jump to: navigation, search
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 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.

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. Available iCub versions
  27. 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
  6. In any case you can post your questions to the robotcub-hackers mailing list.

Three. Calibration

  1. Initial calibration of the iCub:
  2. Fine calibration of the iCub:
  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. 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.
  5. iCub dynamics
    • iDyn: generic library for dynamics

Six. Software, Installing 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
  2. Getting the software
  3. Setup your environment
  4. CMake utility
  5. How to compile everything:
    1. Compilation in Linux
    2. Compilation in Windows
  6. Compile YARP and the iCub software 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:

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. NEW: The Linux on the pc104
  2. iCub architecture, an introduction
  3. Automation
  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.
    7. NEW: Using force control on iCub
  6. Simulators:
    1. The ODE simulator, installation and manual
  7. Tools:
    1. Debugging tools
    2. Firmware update tools: (see also the list of CAN addresses).
    3. Other software tools:
      1. Online documentation for tools: http://eris.liralab.it/iCub/main/dox/html/group__icub__tools.html
      2. Guis: http://eris.liralab.it/iCub/main/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:
  10. Solutions to common problems: Software troubleshooting.

Ten. Standardization of methods

  1. Organization of the repository:
  2. CMake Usage
  3. Modules, standardization, configuration
  4. Preparing scripts for an application
  5. Cluster, example configuration and networking
  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

Thirteen. Committing changes

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

Fourteen. How to install the robot

  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.

Fifteen. Unofficial documentation

Place here pages contributed by users.

  1. Best installation method on Macs as of 2011 is with Homebrew: Homebrew installation instructions for YARP/iCub
  2. Juxi's pages on installing YARP/iCub on Mac OS X:
  3. Testing the robot. Getting the attention system running
  4. Installation of the software on Mac OS X:
  5. Tweaking particular modules for MacOS X:
  6. 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.

Seventeen. Doxygen documentation links

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

  1. YARP Doxygen: click here
  2. iCub documentation: click here

From non-standard repositories...

  1. the EU CHRIS project (FP7 ICT-215805): click here
  2. the EU ITALK project (FP7 ICT-214668):click here

In need of documentation...

  1. the EU EFAA project (FP7 ICT-270490) repository, see efaa.upf.edu
  2. the EU Xperience project (FP7 ICT-270273) cognitive architecture, see www.xperience.org
  3. the EU RoboSKIN project middleware (FP7 ICT-231500), see www.roboskin.eu

Acknowledgments

List people who contributed to this manual.