Configuration files

From Wiki for iCub and Friends
Jump to: navigation, search

Specific rules and policies specifies where configuration files are kept and how they are managed.

Before you proceed you are encouraged to read YARP official documentation, in particular developers should look the the following pages:

while users can go directly to:

Due to its importance we revise here the main concepts.

Configuration files for YARP, iCub applications and robots can be kept in different places.

It is fundamental you keep in mind this important aspect:

There are files that are packages with the source files and are overwritten every time you install or just compile the code. Therefore these files should be considered read-only. This directory is called INSTALLED DATA. There are other files that can be written by the user, they are in the LOCAL USER DATA directory. These files, if present, get precedence over the ones in the INSTALLED directory.

To modify a parameter inside a file you have to first copy (import) it on the LOCAL USER DATA directory and then edit to modify its content. This file will shadow the original one and will be used instead.

The yarp-config utility

Because all this can be confusing YARP provides an utility yarp-config that helps in managing files.

The utility yarp-config allows managing robot and context files, by listing and copying the files from installation to the user private directories (we call this importing).

This tool knows where all files are located and where to put them given the system and user's environment.

The main commands are context to handle application configuration files and robot to handle robot directories.

 yarp-config context --list

Shows all the contexts (application directories) visible to YARP. To limit the list to the context in the installed locations you can add:

 yarp-config context --list --installed

To import contexts to a writable, user specific directory do:

 yarp-config context --import <context-name> 
 yarp-config context --import <context-name> file1 file2
 yarp-config context --import-all

The first two commands affects individual contexts, and allow to import a whole context (first command) or only some specific files (second one); the third command affects all contexts (not recommended).

After you finished importing a context you can go to your local private directory (in Linux usually: $HOME/.local/share/yarp/contexts/) and edit it.

The utility works similarly for robot specific files:

 yarp-config robot --list
 yarp-config robot --import <robot-name> 
 yarp-config robot --import <robot-name> file1 file2

In any case:

 yarp-config help

provides an explanation of the commands supported by the yarp-config tool.


Suppose you have installed both YARP and iCub.


 yarp-config context --list

The result should be something like:

* Directory : /home/nat/.local/share/yarp/contexts
* Directory : /usr/local/share/yarp/contexts
* Directory : /usr/local/share/iCub/contexts

This shows us that:

  • The local user directory /home/nat/.local/share/yarp/contexts is empty, i.e. no contexts have been imported
  • The shared installation directory for YARP /usr/local/share/yarp/contexts contains one context: yarpscope
  • The shared installation directory for iCub /usr/local/share/iCub/contexts contains several contexts

Depending on the configuration of your systems the exact name of the directories may be different. However the idea is the same..

To be able to modify a contexts, for example to customize one parameter you have to first import it in the user directory. Suppose for example you want to customize the context cartesianSolver:

 yarp-config context --import cartesianSolver

This is the output you should get:

Copied context cartesianSolver from 
/usr/local/share/iCub/contexts/cartesianSolver to 
Current locations for this context: /home/nat/.local/share/yarp/contexts/cartesianSolver /usr/local/share/iCub/contexts/cartesianSolver

Now type:

 yarp-config context --list 

To verify that cartesianSolver is indeed now present in /home/nat/.local/share/yarp/contexts

This means that files from cartesianSolver in /home/nat/.local/share/yarp/contexts/ will take precedence over the ones in /usr/local/share/iCub/contexts. This is indeed what we wanted since the latter contains the default values we are going to modify to customize the behavior of the module.

To undo you can remove the context:

 yarp-config context --remove cartesianSolver

Robot configuration (on the PC104)

To help users understand how to modify configuration files for the iCub robot (i.e. robotInterface) we provide some instructions specific to the pc104. The following rules apply to a robot with standard laptop installation.

  • Repository files are located in the folder:

You can check this by running:

 yarp-config robot --list

These files are not used by robotInterface but are the one provided with the repository. To keep the repository updated in case you wish to permanently modify a parameter you have to edit and commit these files. But again notice that these are not the files read by robotInterface. Read on to understand why.

  • When the user executes the following commands:

on the pc104 from the $ICUB_DIR folder, files are copied from usr/local/src/robot/icub-main/app/robots/<YARP_ROBOT_NAME> to the folder:


robotInterface tipically searches the configuration files of the robot in this folder. It's important to remember that this folder is overwritten every time the user runs ccmake/make. So build-pc104/share is not a good place in which to make permanent changes (trust us there are good reasons for this behavior).

  • If you want to make permanent changes (but you still do not want to commit files to repository) you can copy individual files to the local user directoy (which as we explained above takes priority with respect to the build-pc104/share folder). For this purpose, you can use the yarp-config tool to copy ALL the robot files:
yarp-config robot import <YARP_ROBOT_NAME>

If you want to copy just a subset of files, leaving the others in the build-pc104/share folder, you can use the following command:

yarp-config robot import <YARP_ROBOT_NAME> <file1> <file2> <...>
  • Summarizing, when you start robotInterface (or iCubInterface) on the PC104, robot configuration files are searched in the following order: the current directory . the local user directory /home/icub/.local/share/yarp/robot/<YARP_ROBOT_NAME> the build directory /usr/local/src/robot/icub-main/build-pc104/share/<YARP_ROBOT_NAME>

To get a summary of the robot specific files in the order accessed by robotInterface type:

 yarp-config robot --list
  • If you are not sure about which files are currently used by your robotInterface, you can look at the robotInterface log:
robotInterface &> log.txt

at the beginning of the log, you'll find the full path used by robotInterface, e.g.:

found /usr/local/src/robot/iCub/main/build-pc104/share/iCub/robots/iCubGenova01/./icub_all.xml