Document the various ways of controlling a joint

[chapulina]

Ignition Gazebo offers many out-of-box controllers with different features and intended use cases, for example:

• JointController
• JointPositionController
• JointTrajectoryController

It can be difficult for users to choose what to use. So it would be nice to have a high-level joint control tutorial explaining the features and usage of each of them, and why a user would choose one over the other.

Desired behavior

We should have a new tutorial in https://ignitionrobotics.org/api/gazebo/5.1/tutorials.html which summarizes all ways of controlling a joint.

Alternatives considered

Instead of documenting just joint controllers, we could document all ways of moving things, including links, models, etc. This reminds me of this great Gazebo classic tutorial: Setting Velocity on Joints and Links

Implementation suggestion

Add a tutorial here: https://github.com/ignitionrobotics/ign-gazebo/tree/ign-gazebo5/tutorials

[ishaanmane]

Hey @chapulina Can I please work on this issue

[ahcorde]

Hi @ishaanmane

Nobody pick this issue yet! it's all yours! Happy to review your PRs.

[ishaanmane]

Thank you working on it

…

On Thu, Sep 23, 2021 at 10:58 PM Louise Poubel ***@***.***> wrote: Assigned #1019 <#1019> to @ishaanmane <https://github.com/ishaanmane>. — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#1019 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7DC6VQ7C3AR52WH57ET53UDNPVPANCNFSM5DWAXGYA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[LeePerry]

Hi. Is there any progress on this? I’m a new user to Gazebo looking for a joint control tutorial. (I can’t get any of the related demo worlds in Garden to work.) Thanks

[yaswanth1701]

Hi @ahcorde, I think I can document the various joint controllers and also for the movement of link and models. So, should I contribute to this issue ?

[ahcorde]

Hi @yaswanth1701,

Feel free to contribute, there are two places that you can contribute with tutorials:

• https://github.com/gazebosim/gz-sim/tree/gz-sim7/tutorials ( the joint controller docs may live here)
• https://github.com/gazebosim/docs/tree/master/harmonic ( if yo uare thinking about porting this http://gazebosim.org/tutorials?tut=set_velocity&cat= too, the best place probrably is here)

[yaswanth1701]

Oh, thanks a lot. I will start working on this.

[yaswanth1701]

Hi @ahcorde and @azeey, I wrote a bit of a tutorial for the joint controllers and was thinking of asking for your suggestions on whether this is the right direction or if should I make some changes. If possible can you please give your input on this?

---

Tutorial for Joint controllers

1) joint_controller

• Joint controller which can be attached to a model with a reference to a single joint.
• Currently, only the first axis of a joint is actuated.

possible use of this controller type is where one wants only to actuate a single joint.

modes of joint_controller

1. Velocity mode

2. Force mode

Velocity mode:

This mode lets the user control the desired joint directly.

parameters:

<joint_name> (type: String):
specify the joint name (same as one in SDF)
<use_force_mode>(type: Bool): 
by default, this is set to False or one can explicitly specify it as False. 
<initial_velocity> (type: Double):
specify the initial command velocity(default is set to 0.0)

Force mode:

A user who wants to control joint velocity using a PID controller can use this mode.

parameters:

<joint_name> (Type: String):
specify the joint name (same as one in the SDF file)
<use_force_control> (Type: Bool):
set this to True
<p_gain> (Type: Double):
The proportional gain of the PID. The default value is 1.
<i_gain> (Type: Double):
The integral gain of the PID. The default value is 0
<d_gain> (Type: Double):
The derivative gain of the PID. The default value is 0.
<i_max> (Type: Double):
The integral upper limit of the PID. The default value is 1.
<i_min> (Type: Double):
The integral lower limit of the PID. The default value is -1.
<cmd_max> (Type: Double):
Output the max value of the PID. The default value is 1000.
<cmd_min> (Type: Double):
Output min value of the PID. The default value is -1000.
<cmd_offset> (Type: Double):
Command offset (feed-forward) of the PID. The default value is 0.

This mode lets the user explicitly set the values of PID gains and also bounds for velocity.

Note: This mode is for the user who looking to manually tune PID for velocity control according to a specific use case (e.g. Custom models). For general purposes, velocity mode will give the best results.

In both the modes commanded velocity(cmd_vel) can be published or subscribed at the topic: /model/<model_name>/joint/<joint_name>/cmd_vel.

Example usage:

At the end of the model’s SDF file append the following lines:

• Velocity mode

<plugin filename="gz-sim-joint-controller-system"
name="gz::sim::systems::JointController">
<joint_name>joint_name</joint_name>
<initial_velocity>5.0</initial_velocity>
</plugin>
</model>
</world>
</sdf>

• Force mode:

<plugin
 filename="gz-sim-joint-controller-system"
 name="gz::sim::systems::JointController">
 <joint_name>joint_name</joint_name>
 <use_force_commands>true</use_force_commands>
 <p_gain>0.2</p_gain>
 <i_gain>0.01</i_gain>
 </plugin>
 </model>
 </world>
 </sdf>

[azeey]

@yaswanth1701 thank you so much for taking this on!

What you have so far is definitely in the right direction. I would say it would be great to build a full example of a robot where the joint is controlled with these modes and to include example commands and expected results (eg. a gif showing the robot move in a certain direction or robot arm going to a certain configuration). We should assume the audience to be beginners learning Gazebo so including just the <plugin> snippets might not be sufficient to get them going.

Regarding the parameters, I think it would be better to link to https://gazebosim.org/api/sim/8/classgz_1_1sim_1_1systems_1_1JointPositionController.html than to list them in the tutorial.

[yaswanth1701]

@azeey thanks for the review, Sure I will try make it more friendly towards beginners and will let you know on updates soon.