Absolute Encoder Calibration

This Python library serves as a toolbox to calibrate joins on robots integrated into ArmarX.

Standalone Usage

Note: This repository is integrated into Axii and already a feature of most robots such as ARMAR-6, ARMAR-DE, ARMAR-7a and ARMAR-7b. See below in "Robot-Specific Usage".

To activate it, run:

axii workspace add h2t/absolute_encoder_calibration
axii workspace upgr -m h2t/absolute_encoder_calibration
axii workspace install

Axii should then provide executables to start the Jupyter notebook with the correspoonding joint calibrations.

Robot-Specific Usage

The exmaples provided here are with ARMAR-DE. It is be very similar for ARMAR-7 and ARMAR-6 though.

Prepare

1. Open a terminal on the RT PC and enable your workspace, and then start the Jupyter notebook:

   start_armarde_absolute_encoder_calibration_notebook

   On other robots, this command will have a slightly different name.
2. Open the provided link in the terminal in your browser (Ctrl + Click on the link, e.g., http://armar-de-0:8888/?token=xxxx).
3. Start the notebook ARMAR_DE_Calibration.ipynb.
4. Start the Simox RobotViewer and load the robot model that corresponds to the robot you are going to calibrate.
5. Start etherkitten from the RT PC in a new terminal:

   etherkitten

   If for some reason etherkitten does not provide any readings on the onboard PC, you'll have to attach the bus to an external laptop that has ehterkittten installed and the run it there.

Calibrate Revolute Joints with Hard Stops

Note: Joints like ArmL2_Sho1, ArmL4_Sho3, and ArmL6_Elb2 are limitless joints, which require a different strategy to calibrate the absolute encoder, see section "Calibrate Limitless Revolute Joints" below.

1. In RobotViewer GUI, find the joint to be calibrated, e.g. ArmL1_Cla1 of ARMAR-DE. Move the joint to its lower and upper limit (slide bar of Joint Value). This step tells you where the lower and upper limits are. E.g. the image belows shows the lower and upper limit of ArmL1_Cla1.

   Fig. 1 Lower Limit

   

   Fig. 2 Upper Limit

2. Now, move the joint on the real robot to its lower limit (corresponding to RobotViewer like Fig. 1). Push it firmly against the hard stop and ensure that it does not come back. Do not touch the robot while reading sensor values.

3. Read the absolute values from the etherkitten GUI.

   1. Find the corresponding slave (Better to check the serial number and make sure it matches that in the hardware configuration file).

   2. Find sensor_actuator_board -> PDO -> Absolute Encoder Value, as shown below.

      

      Fig. 3 Absolute encoder values in PDO

   3. Read the value and enter it into the code block for the joint in the notebook, first entry (LOWER_LIMIT) of the tuple as shown below.

      Cla1_L = C(name="Cla1_L",
                 measured_limits_ticks=(LOWER_LIMIT, UPPER_LIMIT),
                 measured_zero_ticks=MIDDLE_OF_RANGE,
                 joint_offset_degree=15,
                 joint_limits_degree=(-82, 82),
                 method="hard_stop",
                 **ctx)

4. Repeat 1 to 3 for the upper limit and middle of the range and put the values to the field UPPER_LIMIT and MIDDLE_OF_RANGE, respectively. Please note that MIDDLE_OF_RANGE does not have to be very accurate - aligning it visually is sufficient.

5. Execute the first cell in the notebook, as well as the cell you just modified. It generates the hardware configuration line for the corresponding joint similar to this:

   <ModularConvertedValue name="absoluteEncoder" zeroOffset="524288" discontinuityOffset="698666" maxValue="2^20" isInverted="true" />

   Copy and paste it into the hardware configuration file.

6. Check the plots and Range of motion analysis below the plots and see whether they make sense.

Validate the Calibration on the Real Robot

1. If you attached the bus to the external laptop, reattach it to connect the bus back to the robot's PC. Otherwise, just launch the realtime unit, e.g. start_unit on the RT PC.
2. Open the kinematic unit GUI.
3. Put the robot to soft emergency stop (SS2), trigger the PDO device.
4. Move the calibrated joint to its lower and upper limit (according to the model), check the readings in the kinematic unit GUI. If it moves continuously from one limits to another, we are good to go.
5. Be careful at this step, hold the emergency stop (STO) for any unexpected motion. Release the soft emergency stop (SS2), and put the joint to position control mode. If the joint moves at all (e.g. automatically moving towards the limit), trigger the emergency stop (SS2 or STO) immediately. It is most likely that the sign of the relative encoder is wrong. To fix this, do the following, otherwise go to next step.
   1. Go to the hardware config of the joint, and check whether there are the following two entries

   <LinearConvertedValue name="relativePosition" factor="2.27256413020095e-06" offset="0" />
   <LinearConvertedValue name="velocity" factor="2.27256413020095e-06" offset="0.0" />

   in config field

   <Device type="Joint" name="ArmR5_Elb1" profile="default">
        <Slave type="Elmo" profile="U2 1:100">
            <Identifier>
                <VendorID>154</VendorID>
                <ProductID>198948</ProductID>
                <Serial>0x01087507</Serial>
            </Identifier>
            <Config>
                <Float name="loLimit">-0.680678</Float>
                <Float name="hiLimit">2.54818</Float>
                <Bool name="limitless">false</Bool>
                <Bool name="InvertedSTOValue">true</Bool>
                <LinearConvertedValue name="targetTorque" factor="-7.0" offset="0.0" />
            </Config>
        </Slave>

   2. If it is not there, then copy these two entries from the default profile Profiles.xml and search for U2 1:120.
   3. Flip the sign of the factors. Do not change the factor and ensure it is consistent with the profile.
6. Now repeat 5 and check if the joint is stable in position mode. If so, then try to move the joint to its lower and upper limit.
7. If the joint move smoothly inside the motion range, then you are done.

Calibrate Limitless Revolute Joints

TBD

Calibrate Magnetic Absolute Encoder

The ThumbCircumduction joint of the thumb of ARMAR-DE and ARMAR-7 has a magnetic absolute encoder. It measures the angle of the magnetic field. Since this joint is not backdrivable, you have to use a etherketten laptop to drive it to reach its lower and upper limits.

1. Similarly to other cases, you'll need to validate which limit is the lower/upper limit in RobotViewer.

2. Attach the ethernet cable of the hand (or the arm containing the hand) to the etherkitten laptop.

3. Drive the hand to the lower limit by setting a proper PWM value.

4. Read the magnetometer values. We are interested in the x and y readings. Record it as

   $x_l$
   and
   $y_l$
   .

5. Drive the joint to the upper limit and record the x and y value again, as

   $x_u$
   and
   $y_u$
   .

6. Compute the angle at both limits

   There was an error rendering this math block. KaTeX parse error: Undefined control sequence: \atan at position 12: \alpha_l = \̲a̲t̲a̲n̲2(y_l, x_l), \a…

7. Set the motorPositionZeroOffset in the hardware config file of that joint to

   $-\alpha_{low}$
   .

8. Compute the motorPositionScaling

   $s$
   . Find the range of the motion (in radian) as
   $R$
   , e.g.
   $\pi/2$
   .
   • Usually,
     s = R / \vert\alpha_u \bmod (2 \pi) - \alpha_l \bmod (2 \pi)\vert
   • However, for whatever reason, this does not match reality. In pratice, you can put the motorPositionZeroOffset in the hardware config, and set motorPositionScaling to 1, launch the unit and see the behavior of the joint. If it does not match the expected range of motion, then slightly twick the motorPositionScaling until satisfied.

9. In the kinematic Unit GUI, try to put the joint into position control mode. Ff the motor moves to the maximum even if you haven't change target or only changed slightly, then revert the motorPositionIsInverted entry.

10. Reboot the unit until you can control the joint smoothly in the entire range of motion.