From Wiki for RobotCub and Friends

We here describe the basic elements of a controlBoard configuration file. Each file configures a specific CAN-bus line and, the different parts of the robot (left_arm, right_arm, torso, etc. etc.) might be either corresponding to a single CAN-bus line, or divided among multiple CAN-bus lines or finally, two parts can be described by a single configuration file (e.g. icub_legs.ini describes both the left and the right leg). This situation varies across the different versions of the robot, as summarised in the following table.

Contents 1 How to choose the correct configuration file 2 [GENERAL] 2.1 Joints 2.2 MaxDAC 2.3 Zeros and Encoder 2.4 AxisMap 3 [LIMITS] 3.1 Max and Min 3.2 Currents 4 [CAN] 4.1 CanAddresses 4.2 CanDeviceNum 4.3 CanMyAddress 4.4 CanPollingInterval 4.5 CanTimeout 4.6 Broadcast 5 [VELOCITY] 5.1 Shifts 5.2 Timeout 6 [PIDS] 6.1 Pid 7 [CALIBRATION] 7.1 CalibrationType, Calibration1, Calibration2, Calibration3 7.2 PositionZero 7.3 VelocityZero 8 [HOME] 8.1 PositionHome 8.2 VelocityHome 9 Example of a config file

How to choose the correct configuration file

We here describe how to find the correct configuration file in order to change the properties of a specific motor and/or a specific iCub joint. Notice that the situation varies across different versions of the robot so pay attention to the information in the following tables.

V1.0
part	configuration file	entries in the file	network specification
left_arm (all joints)	icub_left_arm.ini	0 -> 15	pcan 1
right_arm (all joints)	icub_right_arm.ini	0 -> 15	pcan 2
head (all joints)	icub_head_torso.ini	0 -> 5	pcan 0
torso from (all joints)	icub_head_torso.ini	6 -> 8	pcan 0
left_leg (all joints)	icub_legs.ini	0 -> 5	pcan 3
right_leg (all joints)	icub_legs.ini	6 -> 11	pcan 3
V1.1
part	configuration file	entries in the file	network specification
left_arm from joint_0 to joint_7	icub_left_arm.ini	0 -> 7	pcan 1
left_arm from joint_8 to joint_15	icub_left_hand.ini	0 -> 7	ecan 0 or ecan 1
right_arm from joint_0 to joint_7	icub_right_arm.ini	0 -> 7	pcan 2
right_arm from joint_8 to joint_15	icub_right_hand.ini	0 -> 7	ecan 0 and ecan 1
head (all joints)	icub_head_torso.ini	0 -> 5	pcan 0
torso (all joints)	icub_head_torso.ini	6 -> 8	pcan 0
left_leg (all joints)	icub_legs.ini	0 -> 5	pcan 3
right_leg (all joints)	icub_legs.ini	6 -> 11	pcan 3
V1.2
part	configuration file	entries in the file	network specification
left_arm from joint_0 to joint_7	icub_left_arm.ini	0 -> 7	pcan 1
left_arm from joint_8 to joint_15	icub_left_hand.ini	0 -> 7	pcan 5
right_arm from joint_0 to joint_7	icub_right_arm.ini	0 -> 7	pcan 2
right_arm from joint_8 to joint_15	icub_right_hand.ini	0 -> 7	pcan 6
head (all joints)	icub_head_torso.ini	0 -> 5	pcan 0
torso (all joints)	icub_head_torso.ini	6 -> 8	pcan 0
left_leg (all joints)	icub_left_leg.ini	0 -> 5	pcan 3
right_leg (all joints)	icub_right_leg.ini	0 -> 5	pcan 4

The file is typically divided into multiple subparts described hereafter.

[GENERAL]

Joints

The number of joints connected to the canbus (typically 2 joints for each BLL control board and 4 joints for eqch 4DC board).

MaxDAC

Obsolete parameter.

Zeros and Encoder

We here describe the meaning of the entries Encoder and Zeros in the controlBoard configuration file. These two parameters are used to rescale and offset the number received from the control boards in response to a CAN_GET_ENCODER_POSITION message (practically the position of the motor as represented within the DSP). For each joint, the value contained in the DSP, here indicated 'dsp_enc', is converted into the joint configuration (as represented in the iCubInterface), here indicated ang, as follows:

ang = (dsp_enc / Encoder) - Zeros

AxisMap

The AxisMap gives the possibility to change the sequence of the joint that normally it respects the sequence of the CanAddresses. If you want to change this sequence you can write your own sequence in this field. For example in this case the sequence was 5 6 8 9 in CanAddresses and then the axis sequence is:

#Axis  Board 
0 5ch0
1 5ch1
2 6ch0
3 6ch1 
And so on.

Whit the AxisMap 2 3 0 1 …. It becames

#Axis  Board 
0 6ch0
1 6ch1
2 5ch0
3 5ch1

[LIMITS]

Max and Min

Maximum and minimum value (in degree) for the joints.

Currents

Maximum value (in mA) for the currents. If a bigger value is recorded then the corresponding joint is disabled. At present, only brushless boards (BLL) have this value expressed in mA; in the 4DC boards this value is less intuitive but, soon or later, its meaning will be changed to be expressed in mA.

[CAN]

CanAddresses

This field contains the addresses of the control board connected to the canbus line. These addresses can be changed with the canLoader20 gui and should be compatible with this document.

CanDeviceNum

Not used

CanMyAddress

The address of the pc where the iCubInterface is running (should always be set to 0).

CanPollingInterval

Interval in milliseconds between two polling messages.

CanTimeout

Timeout used when waiting for a reply (gives a warning if the answer was not received).

Broadcast

This section describes the meaning of the broadcast parameters. Practically, each parameter tells the iCubInterface to send (on the CAN bus) a message to the control boards. This message will force the control boards to start broadcasting a specific information according to the following table:

parameter	function	periodicity
broadcast_pos	enables the broadcast of positions (should always be enabled, i.e. "broadcast_pos 1")	cyclic every 4ms
broadcast_pid	enables the broadcast of voltages given to the motors (duty cycle)	cyclic every 4ms
broadcast_fault	enables the broadcast of the board status	cyclic every 4ms
broadcast_current	enables the broadcast of the currents given to the motors and trajectory tracking errors	cyclic every 4ms
broadcast_canprint	enables boards to send debugging messages	sent only at startup by the pc104
broadcast_vel_acc	enables the broadcast of the velocities and acceleration	cyclic every 4ms

The generic broadcast should be enabled as follows:

broadcast_xxx 1

and disabled as follows:

broadcast_xxx 0

Previous syntax will enable broadcast from all boards in the corresponding CAN bus line. Optionally, if you want to save some bandwidth, you can enable/disable broadcast of specific boards with the following syntax:

broadcast_xxx 1 0 1 ... 1

where the parameter broadcast_xxx should be followed by a list of 1/0 whose length should equal the number of joints (specified in [GENERAL]Joints parameter).

[VELOCITY]

Shifts

We here descibe the meaning of the parameter Shifts in the control board configuration file. Currently, (when controlling the icub in velocity mode) velocities are represented in the CAN bus with a 16-bits fixed-point arithmetic value; this value represents the velocity in "encoder tics per milliseconds", i.e. [tics/ms] (Note: velocities are represented in "degrees per second" in the iCubInterface). The number of fractional bits is specified in the "[VELOCITY]/Shifts" entry of the controlBoard configuration file, e.g. icub_left_arm_safe.ini. Default value is 4 and is used when no [VELOCITY]/Shifts entry is found by the parser.

(1) If Shifts=0, velocity are specified as 16-bits integers in the CAN bus and therefore the minimum velocity will be -32768 [tic/ms], the maximum will be 32767 [tics/ms] and the absolute value minimum velocity will be 1 [tics/ms]. In order to convert these values in degrees you need to know the encoder resolution. EXAMPLE: if you consider the joints of the shoulder an encoder tic corresponds to 360/4096 degrees (we currently have 12 bits per revolution). Therefore, the absolute value minimum velocity 1 [tic/ms] corresponds in degrees to 0.09 [deg/ms] or otherwise 90 [deg/s].

(2) If Shifts=8, velocity are specified as 8-bits integers and 8-bits fractional parts, i.e. scaled by 2^(-8). Therefore the minimum velocity will be -128 [tic/ms], the maximum will be 127 [tics/ms] and the absolute value minimum velocity will be 2^(-8) [tics/ms]. EXAMPLE: if you consider the joints of the shoulder an encoder tic corresponds to 360/4096 degrees (we currently have 12 bits per revolution). Therefore, the absolute value minimum velocity 2^(-8) [tic/ms] corresponds in degrees to 0.34 [deg/sec]. Accordingly you can compute the maximum and minimum velocity.

Timeout

This parameter allows to set a timeout on the velocity control. If a velocity messages is received by the control board, then the motor will be moved with the prescribed velocity for Timeout[ms]. If no new velocity message is received within Timeout[ms] the control mode is switched to POSITION and the current motor position is maintained. If a new velocity message is received before Timeout[ms], then the new velocity will be executed, the timeout counter reset and the VELOCITY control mode maintained for Timeout[ms] more.

[PIDS]

Pid

This parameter describes the controller which is used for controlling the position of each joint. Practically, the implemented controller is the following:

u = -Kp * (q-qd) - Kd * (dq-dqd) - Ki * int(q-qd) + Offset

where:

u	motor PWM duty cycle
Kp	proportional gain
Kd	derivative gain
Ki	integral gain
q	joint position
qd	desired joint position
dq	joint velocity
dqd	desired joint velocity
int()	time integral
Offset	offset to be added to PID controller (can be used as a feedforward)

The [PIDS] group in the controlBoard configuration file, can be used to specify the values for Kp, Kd, Ki and Offset to be used by each joint of the robot. On top of these values, other three quantities are useful:

MaxDuty	maximum duty cycle to the joint motor
Shift	2^Shift scaling factor for Kp, Kd, Ki, i.e. if Shift=4 gains are scaled by 2^-4=1/16
MaxIntegral	maximum value for the integral part of the controller

Overall, a complete PID is specified by seven parameters, nominally Kp, Kd, Ki, Offset, MaxDuty, Shift and MaxIntegral. For the i-th joint, these parameters should be specified according to the following syntax:

Pidi    Kp   Kd   Ki   MaxIntegral MaxDuty  Shift Offset

E.g. if we want to specify:

joint	0
Kp	10
Kd	20
Ki	1
MaxIntegral	1333
MaxDuty	1333
Shift	2^-4 scaling factor for Kp, Kd, Ki
Offset	0

then the following line should be specified in the [PIDS] group:

Pid0    10   20   1   1333 1333  4 0

[CALIBRATION]

CalibrationType, Calibration1, Calibration2, Calibration3

These values are the calibration options described in this word document word document

PositionZero

This parameter describes the position the robot should reach after the calibration procedure. when using absolute encoder usually the PositionZero is equal to the Calibration1/Encoder value minus the Zeros.

VelocityZero

This parameter describes the velocity of the movement reaching the PositionZero position.

[HOME]

PositionHome

The position to park the robot when closing the iCubInterface.

VelocityHome

The velocity when parking the robot.

Example of a config file

//
// Initialization file for robot head, 8 dof on can bus controller.
//
[CAN]
CanAddresses 1 2 3 5 6 132 128 128 128 128 128 128 128 128 128
CanDeviceNum		0
CanMyAddress		0
CanPollingInterval	10
CanTimeout		300
CanTxTimeout    500
CanRxTimeout    500
broadcast_pos      	1
broadcast_pid      	0  
broadcast_fault    	1
broadcast_current  	0
broadcast_overflow 	1
broadcast_canprint 	1
broadcast_vel_acc  	0

[VELOCITY]
Shifts 12 12 12 12 12 12 12 12 12 12

[GENERAL] 
Joints 10
MaxDAC 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0

AxisMap        0         1         2         3        4         5         6       8       9       7
Encoder -1951.29  -1951.29  -1399.46  -1093.33  -586.66    293.33    11.375  11.375  11.375     1.0
Zeros         40        47     55.45     -38.4    50.5      8.96       180     180     180       0
Verbose 0


[LIMITS]
//     0      1      2     3     4       5     6      7      8       9
Max   24    +47	   +52    19    66      50    50     30     70       0
Min  -39    -47    -52   -44   -63       0   -50    -30    -10       0

Currents 485 485 485 485 485 485 8400 8400 8400 8400
 
[PIDS]
 
Pid0     50     500   1   1333 1333  4 0
Pid1     50     500   1   1333 1333  4 0
Pid2    100     700   2   1333 1333  4 0
Pid3     40     400   1   1333 1333  4 0 
Pid4    100    1000   1   1333 1333  4 0
Pid5    100    1000   1   1333 1333  4 0
Pid6  32000      60   0    333  333 14 0 
Pid7  32000      60   0    333  333 14 0
Pid8  32000      60   0    333  333 14 0
Pid9      0       0   0    333  333 14 0

[CALIBRATION]
//                  0          1        2         3          4          5          6        7        8       9
CalibrationType     0          0        0         0          0          0          3        3        3       3
Calibration1    500.0	  1000.0    900.0     300.0     1333.0     1333.0       2047     2047     2047     0.0
Calibration2     20.0	    20.0     20.0     -20.0       20.0       20.0       10.0     10.0     10.0     0.0
Calibration3      0.0	     0.0      0.0       0.0        0.0        0.0      958.9   2728.9   3024.6     0.0
PositionZero      0.0        0.0      0.0       0.0        0.0        0.0        0.0      0.0      0.0     0.0
VelocityZero     10.0       10.0     10.0      10.0       10.0      10.0         4.0      4.0      4.0     0.0


[HOME]
//                  0          1        2         3          4          5        6       7        8        9
PositionHome      -40        -68      -55         0        -10          0      0.0     0.0    -10.0      0.0
VelocityHome       10         10       10        10         10         10       10      10       10       10


[ENDINI] // do not remove this line!