[ Documentation ] - Provide more documentation for the admittance controller

[firesurfer]

The documentation page of the Admittance Controller is currently rather rudimentary: https://control.ros.org/master/doc/ros2_controllers/admittance_controller/doc/userdoc.html

For many parameters it is unclear how they are determined and/or what their influence on the control behavior is. I think: Just play around with the parameters while having enable_parameter_update_without_reactivation enabled can not be the solution as it is very easy to crash into something while doing so. (e.g. I just adjusted admittance.joint_damping which resulted in a large sudden motion).

When we take a look at the code it refers to a very extensive pdf:

A reference is here: https://users.wpi.edu/~jfu2/rbe502/files/force_control.pdf

Unfortunately this pdf is not linked in the documentation. Nevertheless I think a hands on guide on how to setup and tune the controller should be included in the documentation.

List of parameters that are unclear (to me)

[ admittance.mass ] - The example shows increasing values for each axis and a formula. Some explanation behind that would be nice.

[ admittance.damping_ratio] - I guess it is something like a p controller gain? - Why is it set to such a specific value in the example?

[ admittance.stiffness] - I would guess that a higher stiffness means -> Harder position tracking? With the parameters in the example our UR16e only corrects for forces but not for torque - I had to reduce the rx,ry,rz values to ~1.0 in order for the controller to also correct for the torques.

[ kinematics.alpha ] - No clue what it does

[ admittance.damping_ratio ] - No clue what it does

Have a list of common issues

Additionally I think adding a short list of common issues would be nice. This could include points like:

• Gravity compensation does not work properly - e.g. arm moves upwards when being activated

Document which parameters can be changed at runtime

The documentation does not specify which parameters can only be changed at:

• initialization - can only be changed by editing the controllers.yaml
• configure
• activate
• runtime (when enable_parameter_update_without_reactivation == true)

Depending on the setup this is important if the user wants to change for example the controlled link control.frame e.g. because there are multiple end effectors on the arm.