Add instructions for gliding setpoint

[Jaeyoung-Lim]

This adds the instructions to enable offboard gliding setpoints for fixed wing vehicles.

The feature was added in PX4/PX4-Autopilot#14643

[hamishwillee]

1. Just FMI, what is gliding and what does it mean to prioritise airspeed?

Looking at the linked PR I think it means that you fly without any throttle (pusher, puller motor) using whatever kinetic energy you already have. So prioritising airspeed perhaps means that we might change the attitude, and thereby sacrifice altitude to keep our airspeed up? And the docs seem to indicate that what the change actually does under the hood is set the cruising_throttle to -1 in offboard mode.

2. Does this only apply to local NED, or also SET_POSITION_TARGET_GLOBAL_INT etc?

3. Want to confirm how we set the types for FW. My reading of the current docs is that if it is a "pure" position setpoint, (x, y, z) we should we should set all the bits from 8 to 2048 (ie all except POSITION_TARGET_TYPEMASK_X_IGNORE, POSITION_TARGET_TYPEMASK_Y_IGNORE, POSITION_TARGET_TYPEMASK_Z_IGNORE). IS that right? Then for the other types we set the specific values - .e.g. 8192 for land setpoint.

4. My main concerns with this format of docs:

   • we imply but don't say that if you're in offboard mode and you want to land then you should set land setpoints, that if you want to glide then you set glide setpoints etc. Perhaps obvious?

• We say in description "Other operations, like taking off, landing, return to launch, are best handled using the appropriate modes.", but then why do we have these setpoints?
• If isn't particularly obvious at the beginning what you can do - you have to drill down. So for example it might be useful to say in the description that fixed wing vehicles can use position setpoints to land, takeoff, glide etc etc.

[Jaeyoung-Lim]

@hamishwillee Sorry for the late reply, to answer your questions:

1. That is correct - pitch is controlled through TECS(Total Energy Control System), and when the vehicle is gliding, TECS only tries to manage airspeed and stops caring about altitude which results in controlling pitch to regulate the airspeed

2. It only applies to SET_POSITION_TARGET_LOCAL_NED right now. I will add it to SET_POSITION_TARGET_GLOBAL_INT, but I am just missing some testing for that.

3. That is correct. However, currently the fw position controller doesn't care about velocity / acceleration commands so it will not do anything even if you don't ignore it.

4. That is a valid point and I will update it. But I don't "recommend" people using land setpoints while in offboard mode. It is not supposed to be something we actively support and can safely operate (e.g. nothing is safe in offboard mode). I agree that we need to mention this.

[hamishwillee]

@Jaeyoung-Lim Realised you modified the version of the file in the /de/ tree (german) rather than /en/ tree. So I have rebased this and moved your changes to the /en tree, with some minor updates to clarify what gliding means. I am going to merge this now. Please sanity check it!

However there is still and action on you to address point 4 of #813 (comment)

[Jaeyoung-Lim]

@hamishwillee Thanks,

I believe what you are mentioned is the following.

My main concerns with this format of docs:
we imply but don't say that if you're in offboard mode and you want to land then you should set land setpoints, that if you want to glide then you set glide setpoints etc. Perhaps obvious?
We say in description "Other operations, like taking off, landing, return to launch, are best handled using the appropriate modes.", but then why do we have these setpoints?
If isn't particularly obvious at the beginning what you can do - you have to drill down. So for example it might be useful to say in the description that fixed wing vehicles can use position setpoints to land, takeoff, glide etc etc.

I will clarify the docs on another PR