Extend MAV_CMD_NAV_VTOL_TAKEOFF

[RomanBapst]

Motivation
MAV_CMD_NAV_VTOL_TAKEOFF is used to command a VTOL to takeoff from the ground vertically and transition to fixed wing flight via the specified heading. What happens after the transition is not well defined and typically different flight controller implementations did what they considered the "correct" thing to do.
In PX4 the current behavior is to treat the VTOL takeoff waypoint as a standard 3D waypoint once the vehicle transitioned to fixed wing flight. In Ardupilot (please correct me if I'm wrong) the 3D position of the waypoint is ignored once the vehicle transitioned to fixed wing flight.
A ground station like QGC cannot really display any meaningful predicted path if it does not know about the specifics of the implementation.

This is an attempt to extend the definition of MAV_CMD_NAV_VTOL_TAKEOFF in order to allow different behaviors of the vehicle after the transition to fixed wing flight.

Details

1. Add an altitude field which (together with lat/lon fields) fully defines the 3D location of the waypoint. This altitude is NOT the same as the transition altitude as those two measures don't necessarily need to be the same. Some use cases/air frames require low transition altitudes but a higher climbout altitude. Generally you want to transition as low as possible to conserve energy but you want to loiter high enough to clear potential obstacles.

2. Define VTOL_TAKEOFF_WAYPOINT_ROLE enum which specifies the role of the 3D vtol takeoff waypoint.
   This enum describes what exactly the vehicle will do after the transition to fixed wing flight has completed and what needs to happen in order for the MAV_CMD_NAV_VTOL_TAKEOFF to be considered "reached".

• Option VTOL_TAKEOFF_WAYPOINT_ROLE_IGNORE_POSITION

The way-point's only use is to define a transition direction if required by the "Transition Heading" parameter. Other than that the location does not serve any other purpose since the vehicle does not need to reach the position.

• Option VTOL_TAKEOFF_WAYPOINT_ROLE_FLYTHROUGH

Other than potentially defining a transition direction ("Transition Heading") the waypoint is treated as a "standard" waypoint which needs to be "reached" by the vehicle according to the measures implemented by the flight controller (acceptance radius).
This option is useful to obtain a predictable flight path.

• Option VTOL_TAKEOFF_WAYPOINT_ROLE_LOITER_ONCE

The same as VTOL_TAKEOFF_WAYPOINT_ROLE_FLYTHROUGH, however, instead of just reaching the waypoint, the vehicle needs to complete one full loiter circle at the waypoint location. The radius and direction are given by vehicle defaults.
This option is useful to accelerate convergence of wind estimation. This can be very important for vehicle relying on synthetic airspeed computation. It's also useful in cases where there are no other navigation commands following immediately (e.g. VTOL takeoff commanded by the user directly instead of being commanded as part of a mission) since then the vehicle is loitering at a known position and does not needs any immediate action.

Here is an attempt to sketch out the different options:

Other comments
The intent is to extend the message in such a way that it does not break existing implementations. This should be given by the fact that the proposal makes user to the two empty fields and does not alter any existing fields.

Related Links
PX4/PX4-Autopilot#15645
mavlink/qgroundcontrol#8221
Example implementation in QGroundControl:
mavlink/qgroundcontrol#10123

Alternatives

• one might argue that the behavior after the transition should always be defined by a consecutive waypoint and the implementation goes beyond the scope of the VTOL takeoff

[sfuhrer]

I like this approach. It shows a way to cleanly support both the current PX4 and Ardupilot implementation, plus adds the 3rd option that will enable us to use the VTOL_TAKEOFF as a standalone command without a subsequent mission.

[hamishwillee]

The first role, before this one, should be "system default" with a value of 0. This allows the recipient to know that the GCS doesn't care or hasn't been updated to the new meaning of the item.

[hamishwillee]

@sfuhrer Added a comment should this be climbout altitude, which got removed when I merged my update to fix the text.

IMO "altitude" implies final altitude, but would be more than happy with "Final altitude", "Target altitude" or "Climbout altitude".

If possible I would reverse the names - i.e. param 7 being final altitude and param 1 being the transition,. That's because to me param7 altitude is the final target. That might require the "roles" to be redefined though, and might not be possible if the default doesn't match.

[hamishwillee]

The most important there here is that a system that has not updated or does not choose to update should behave in the same way if it gets this command, and that this behaviour should be expected against the new message definition.

More precisely,

• The first option in the VTOL_TAKEOFF_WAYPOINT_ROLE needs to be something that says "do whatever you used to do", and ideally "system default behaviour".
• When that is set to 0 the name of param7 needs to be sensible.

This is pretty easy if all systems currently assume the param7 altitude is the transition altitude OR if they all assume it is the final altitude. If it is neither we have a breaking change and this will need a little more thought.

@WickedShell Can you confirm how ArduPilot treats the lat/lon/alt w.r.t. transition and climbout in a VTOL takeoff? Is this variable in parameters?

[RomanBapst]

The first option in the VTOL_TAKEOFF_WAYPOINT_ROLE needs to be something that says "do whatever you used to do", and ideally "system default behaviour".

@hamishwillee I will add a "system default" role. In PX4 currently the system default is to fly to the vtol takeoff waypoint at the transition altitude. Afaik in ardupilot the system default is to ignore the position (which is an existing role). I was thinking about making this the same default role for PX4 but thinking about it twice I believe we should prioritize consistency and leave the system default as is.

If possible I would reverse the names - i.e. param 7 being final altitude and param 1 being the transition,. That's because to me param7 altitude is the final target. That might require the "roles" to be redefined though, and might not be possible if the default doesn't match.

Are you suggesting to use param 7 as transition altitude only for the "system default" role and swap with param1 for everything else? I also think it's much cleaner to use param1 as transition altitude and param7 for climbout altitude but that of course breaks compatibility. Although, switching altitude params depending on the role is also a bit weird, don't you think?

[hamishwillee]

Afaik in ardupilot the system default is to ignore the position (which is an existing role)

Are you saying that if ardupilot has a mission with MAV_CMD_NAV_VTOL_TAKEOFF by default it will:

• takeoff vertically at the current position, ignoring the lat/lon
• transition at some height, ignoring altitude (param7)
• immediately complete the waypoint following transition and move to the next one?

If possible I would reverse the names - i.e. param 7 being final altitude and param 1 being the transition,. That's because to me param7 altitude is the final target. That might require the "roles" to be redefined though, and might not be possible if the default doesn't match.

Are you suggesting to use param 7 as transition altitude only for the "system default" role and swap with param1 for everything else? I also think it's much cleaner to use param1 as transition altitude and param7 for climbout altitude but that of course breaks compatibility. Although, switching altitude params depending on the role is also a bit weird, don't you think?

What I am saying is:

1. I can't really define what I want unless I know what both PX4 and ArduPilot do by default.
2. The default behaviour must be "do whatever you always did".
3. My assumption was that all flight stacks use param7 as an acceptance altitude, along with the lat/lon. That is generally what lat,lon, alt (param5,6,7) mean. If that is the case then keeping that meaning is desirable.

Does that make sense?

[hamishwillee]

@RomanBapst OK, so I had a chat to @WickedShell about this. As I understand the situation (note, the ArduPilot bit below should now be accurate):

PX4 current behaviour:

1. Takeoff vertically
2. Transition at parameter/internally defined altitude to FW
3. Proceed to lat/lon/alt defined in the command, as though this was an ordinary waypoint.
4. Complete the mission item/waypoint under normal acceptance rules for a 3D waypoint

Note, I presume PX4 respects the MAV_FRAME in command for ALT?

ArduPilot current behaviour:

1. Takeoff vertically
2. Transition at parameter/internally defined altitude to FW
3. Transition completes the item. Proceed to next waypoint.
   • lat/lon/alt ignored - assumption is "if zero they are ignored" but this is forced.
   • MAV_FRAME is ignored by default in all messages, but can be forced in a param

Note: ArduPilot might not be able to store all these options " we only have 12 bytes to store mission items, we don't store a full mission_item_int, we compress/grab the fields we need. Not sure if we have enough extra fields to store everything else requested here".

From a design point of view we ignore that. ArduPilot don't have to implement mission items properly if they don't want.

So ArduPilot treat this as purely an instruction to takeoff. PX4 treat it as an instruction to takeoff and then become a normal waypoint.

To me both are not "odd" interpretations. Given there are lat/lon/alt I would assume these to be used, but I would also expect them to be used as the transition point, and for transition to be the completion of the item. Then you would plan your mission as a primitive. Making this a takeoff and then a waypoint seems a bit weird.

So where does this leave us? For compatibility (so the same default command does the same thing before and after)

• param5, 6, 7 must be a target waypoint after transition - otherwise old PX4 systems getting the command will behave differently
• param4, 6, 7 must be ignored by ArduPilot. I think we can simply state that 0 or some other invalid value for these (e.g. NaN) means " use current.
• param1 = transition alt. 0 and NaN mean "ignore - use system default".

If you do that I think you don't need the roles. If you want to loiter or whatever, add a loiter point as the next item.

Thoughts?

[RomanBapst]

@hamishwillee The main motivation of this PR is to be able to use the VTOL takeoff item as a standalone item!
You could compare it to VTOL_LAND. That commands also flies the drone to the ground and lands it, nothing else is needed after it.
We are using the VTOL_TAKEOFF command as a guided action command, which means the user presses takeoff from the flyview and specifies transition and climbout altitude. He does not need to worry about anything after that since the drone will happily be flying loiter at the specified location. Of course you could always send a second command after the transition has completed but that it much less robust I think.

How does the current proposal not maintain compatibility would be my question? The two newly introduced parameters were ignored before, right?

[RomanBapst]

@hamishwillee

param1 = transition alt. 0 and NaN mean "ignore - use system default".

I don't think this can be the transition alt as PX4 currently is using param 7 for transition alt.

If you do that I think you don't need the roles. If you want to loiter or whatever, add a loiter point as the next item.

That's possible to do for mission, it's less practical as a guided action as you need to send two commands. Sending one command which defines the entire behavior is much more robust.

[hamishwillee]

I don't think this can be the transition alt as PX4 currently is using param 7 for transition alt.

That's why you need to read #1875 (comment) carefully. That states my assumptions, one of which is that PX4 has no transition alt - just a waypoint alt.

See:

• Takeoff vertically
• Transition at parameter/internally defined altitude to FW (i.e. not defined)
• Proceed to lat/lon/alt defined in the command, as though this was an ordinary waypoint.
• Complete the mission item/waypoint under normal acceptance rules for a 3D waypoint

Now I think you are saying: :

• Takeoff
• Proceed to param 5, 6, 7 and transition
• ?

Once you've confirmed the assumptions, only then would I know what makes sense.

[hamishwillee]

We'd probably best use use 0 rather than NaN.

• Yes 0 is a valid altitude but it is unlikely to be the desired climbout altitude
• A GCS will be sending 0 by default if it has not been updated. So you want the 0 value to mean "do what you always did"

[hamishwillee]

@RomanBapst @sfuhrer My updated assumption about PX4 existing behaviour:

• Takeoff vertically
• Transition at altitude defined by param 7.
• Proceed to waypoint defined by param 5, 6, 7.
• Complete waypoint at point (modulo acceptance radius)

Is that right?

Now you want it to be the same but.

• Takeoff vertically
• Transition at altitude defined by param 7.
• Proceed to waypoint defined by param 5, 6, 1.
• If sent as a command (not mission). For the roles:
  • VTOL_TAKEOFF_WAYPOINT_ROLE_DEFAULT: The vehicle could ignore all the params and do what it likes - the only rule is "take off"
  • VTOL_TAKEOFF_WAYPOINT_ROLE_IGNORE_POSITION: Obey transition at param7 but then immediately start loitering (waypoint accepted) around current position - or whatever the default behaviour is when in guided mode not obeying a command
  • VTOL_TAKEOFF_WAYPOINT_ROLE_FLYTHROUGH: Obey both transition alt and waypoint position. Fly as though you're going to fly through it. Once accepted, start loitering around it (or do whatever the default behaviour is when in guided mode not obeying a command)
  • VTOL_TAKEOFF_WAYPOINT_ROLE_LOITER_ONCE - as above, but path is with intent to loiter around the waypoint - so you'd loiter once, then in PX4 you'd continue to loiter. In a flight stack that chooses to fly straight you'd then fly straight.
• If in a mission
  • VTOL_TAKEOFF_WAYPOINT_ROLE_DEFAULT: The vehicle could ignore all the params and do what it likes - the only rule is "take off". Acceptance can be at any point.
  • VTOL_TAKEOFF_WAYPOINT_ROLE_IGNORE_POSITION: Obey transition at param7 but then accept waypoint and start next one.
  • VTOL_TAKEOFF_WAYPOINT_ROLE_FLYTHROUGH: Obey transition and fly through waypoint to next waypoint in the list.
  • VTOL_TAKEOFF_WAYPOINT_ROLE_LOITER_ONCE - Obey transition and fly around waypoint. Then fly to next waypoint on list.

Is that all correct? Please confirm.

Why would you want to loiter once? Is it if you know that you're going to loiter on the next command so that you have a good entry path?

If so I think you're right - this is not incompatible in that an non-updated system sending the command to a system that has been updated will get the same behaviour.

We could add a role "takeoff command only". That would be the same as VTOL_TAKEOFF_WAYPOINT_ROLE_DEFAULT for ArduPilot.

[hamishwillee]

Discussed with @RomanBapst in MAVLink call last night. We're now on the same page.
Thinking is currently that we don't need the loiter role - if you need to progress to specific loiter behaviour you add a loiter waypoint in a mission. Otherwise if using a command most flight stacks should loiter on reaching the takeoff waypoint "by default".

So essentially the options are

• "do what you like",
• "takeoff to param7 altitude and transition - transition completes the action", (i.e. use transition but not waypoint information)
• "takeoff to param7 altitude and transition, then fly to waypoint defined by param5,6,1. Reaching waypoint completes the action". i.e. use the full path planned by the transition and waypoint.

This is waiting on Roman to discuss with Silvan and then update.

[hamishwillee]

@RomanBapst @sfuhrer We discussed it in the dev call, and generally we think that extending this command makes hard to understand, which is in turn risky for implementers. We might be better off replacing the old message and taking time to do whatever else we might like.

Then we could do something like this, which allows the two use cases we actually want - accept immediately on transition, and transition then got to waypoint.

      <entry value="XXXXX" name="MAV_CMD_NAV_VTOL_TAKEOFF_WAYPOINT" hasLocation="true" isDestination="true">
        <description>
          Takeoff from ground vertically in VTOL mode.
          Transition to forward flight with the specified heading at the transition altitude (param1).
          Following transition, fly to climbout waypoint defined by params 5, 6, 7.
          If the transition value is set to the invalid value (NaN) a system default transition altitude is used.
          If the climbout waypoint values are set to the invalid value, the command will complete immediately after the transition.
          Further navigation depends on the value of param3 (VTOL_TAKEOFF_WAYPOINT_ROLE).
	  The command should be ignored by vehicles that don't support both VTOL and fixed-wing flight (multicopters, boats, etc.).
        </description>
        <param index="1" label="Transition Altitude" units="m">Transition altitude. NAN: Transition at flight stack default altitude.</param>
        <param index="2" label="Transition Heading" enum="VTOL_TRANSITION_HEADING">Front transition heading.</param>
        <param index="4" label="Yaw Angle" units="deg">Yaw angle. NaN to use the current system yaw heading mode (e.g. yaw towards next waypoint, yaw to home, etc.).</param>
        <param index="5" label="Latitude">Climbout Latitude. NaN/INT32_MAX to use transition latitude.</param>
        <param index="6" label="Longitude">Climbout Longitude. NaN/INT32_MAX to use transition latitude.</param>
        <param index="7" label="Altitude" units="m">Climbout Altitude. NaN to use transition altitude.</param>
      </entry>

@auturgy is going to comment on what he'd like to see in a message like this.

But note that I don't plan on looking at this again unless you re-engage, and if you haven't done so in a month or so I will close this PR.

[RomanBapst]

@hamishwillee I'm sorry, I lost track of this. I will make the changes today as discussed before. We agreed that we don't need the loiter role which simplifies a lot. With the loiter role gone the only thing that this PR really adds it the loiter altitude (which I think makes sense in any case).

[RomanBapst]

@hamishwillee @auturgy I thought about it a bit more and came to the conclusion that any change I'm trying to do to this message bears the risk to cause unexpected behavior in the case where flight controller and ground station don't use the same message definition. The command as it's defined right now leaves a lot of room for interpretation and therefore also PX4 and ardupilot have implemented this command in different ways.

I therefore welcome the idea of creating a new command with some more thought put into it.

[RomanBapst]

@hamishwillee @auturgy This is my first suggestion of how I think the command could look like.
The difference to the old implementation are:

• it clearly defines a climbout waypoint (param 5, param6 and param7) which if valid defines a 3D waypoint the vehicle needs to reach before the command is completed.
• it allows the transition altitude param1 to be NAN, in which case the default transition altitude defined by the flight controller is used

    <description>
      Takeoff from ground vertically with heading specified by param 4.
      Transition to forward flight with heading specified by param2 at the transition altitude (param1).
      If the command additionally specifies a valid 3D coordinate (e.g. param5, param6 and param7 are not NAN) then the vehicle
      will navigate towards this waypoint after completing the transition to forward flight and treat it like a standard 3D waypoint. Otherwise completing the
      transition to forward flight completes this command.
  The command should be ignored by vehicles that don't support both VTOL and fixed-wing flight (multicopters, boats, etc.).
    </description>
   <param index="1" label="Transition Altitude, NAN: Use flight controller default transition altitude" units="m">Altitude</param>
    <param index="2" label="Transition Heading" enum="VTOL_TRANSITION_HEADING">Front transition heading.</param>
    <param index="3">Empty</param>
    <param index="4" label="Yaw Angle" units="deg">Yaw angle. NaN to use the current system yaw heading mode (e.g. yaw towards next waypoint, yaw to home, etc.).</param>
    <param index="5" label="Climbout Latitude">Latitude, NAN: Invalid, transition to forward flight completes this command</param>
    <param index="6" label="Climbout Longitude">Longitude, NAN: Invalid, transition to forward flight completes this command</param>
    <param index="7" label="Climbout Altitude" units="m">Climbout altitude after the transition to fixed-wing mode. NAN: Invalid, transition to forward flight completes this command.</param>
  </entry>

[RomanBapst]

New idea: MAV_CMD_NAV_VTOL_TAKEOFF_RELATIVE

• specify loiter point relative to current location via bearing
• specify transition heading as either specific (param) or system default
• no more lat lon since command is relative to vehicle takeoff location

[hamishwillee]

@RomanBapst The first idea (#1875 (comment)) seems a lot like the intent I had for the proposal above. So that one makes sense to me.

I am not sure I fully understand the MAV_CMD_NAV_VTOL_TAKEOFF_RELATIVE - probably need to see a definition. But I might interpret this description as "take off at a particular bearing in MC mode, when you reach the specified transition altitude do a transition" then continue at that bearing.
My concerns being that if you don't ascent vertically on your takeoff there is a risk of hitting something low, and that a bearing defines a direction, but not an end point for which you would accept the waypoint.

@auturgy YOu were going to add suggestions on what you need from a VTOL takeoff?

[RomanBapst]

@hamishwillee

I am not sure I fully understand the MAV_CMD_NAV_VTOL_TAKEOFF_RELATIVE - probably need to see a definition

The problem with specifying a global coordinate in the message is that you are bound to that global coordinate but the actual takeoff location in the field might be a different one. Therefore, we could trash the global position of that command and just specify a transition heading and possibly a loiter bearing and distance. This would mean that wherever you end up doing the takeoff, the experience will be consistent.

[hamishwillee]

Ah, thanks. YOur original post did not mention distance :-). I'm not opposed but it would need clear specification.

[hamishwillee]

@hamishwillee

I am not sure I fully understand the MAV_CMD_NAV_VTOL_TAKEOFF_RELATIVE - probably need to see a definition

The problem with specifying a global coordinate in the message is that you are bound to that global coordinate but the actual takeoff location in the field might be a different one. Therefore, we could trash the global position of that command and just specify a transition heading and possibly a loiter bearing and distance. This would mean that wherever you end up doing the takeoff, the experience will be consistent.

@RomanBapst

Yes the takeoff relative to every other takeoff will be consistent flight path, but relative to the rest of the plan it means that the flight path will be different every time. I don't know if it matters, but nor do I know if it "helps". I'd try this out with a few hand draw scenarios.

I've been trying to get @auturgy to comment on "what is it that is needed for a VTOL takeoff point", to no luck. To progress this, can I suggest you create a new PR with the latest thinking. That gives us a concrete proposal to agree/argue and we can be selective about what in this ginormous thread we include.

I'm going to close this for that reason.