Difference between revisions of "Manual"

From Wiki for iCub and Friends
Jump to: navigation, search
(Three. Calibration)
(Eleven. Guidelines)
Line 168: Line 168:
 
Here we describe better practices for software development on the iCub.
 
Here we describe better practices for software development on the iCub.
  
# Coding styles
+
# [[Coding styles]]
 
# Things to avoid
 
# Things to avoid
 
# Naming of ports, variables, scripts, modules, etc
 
# Naming of ports, variables, scripts, modules, etc

Revision as of 20:24, 9 January 2010

The iCub

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.

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. 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

Three. Calibration

  1. DSP code: firmware versions
  2. Other firmware code: more firmware in repository
  3. Initial calibration of the iCub:
  4. Fine calibration of the iCub:
  5. Calibration files, details
  6. 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 kinematics ICubForwardKinematics, D-H parameters (unmodified convention):
  3. Vergence, version and binocular disparity quantities for motor control Vergence, Version and Disparity.
  4. iCub dynamics
  5. Simulators
  6. 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
  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. 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.
  6. Debugging tools
  7. Firmware: update tools and version descriptions.
  8. Starting up the iCub: see here

Ten. Standardization of methods

  1. Organization of the repository:
  2. Cluster, example configuration and networking
  3. Modules, standardization, configuration
  4. Preparing scripts for an application
  5. Licensing

Eleven. Guidelines

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

  1. Coding styles
  2. Things to avoid
  3. 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).
  4. Other conventions

Twelve. Documentation

  1. Compiling the documentation
  2. Writing new documentation
  3. Servers, online material
  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: installing_icub
  2. Installation videos:

Fifteeen. 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:
  3. Tweaking particular modules for MacOS X:
  4. SSH remote calls. Getting SSH to read your environment variables

Acknowledgments

List people who contributed to this manual.