When GPS Rescues are initiated within the minimum start distance, this PR makes the following changes:

• the minimum start distance now defaults to 15m (from 30m), with an allowed configuration range of 10-30m

• the descent distance is set to half the configured minimum start distance

• the quad climbs by the `rescueAltitudeBufferM' height (default is 5m), typically with some overshoot

• the quad flies out to at least the minimum start distance, by pitching forward 15 degrees while climbing, and waiting at the top of the climb until it is outside the minimum start distance. The rescue then proceeds normally.

• the gain factor that controls how quickly the IMU yaw heading adapts to the GPS course over ground heading is dynamically modulated, as described in Increase IMU yaw CoG gain at higher positive pitch angles #12791, which is as follows:

• the IMU yaw Cog gain is set to zero when climbing, rotating, or 'doing nothing', so that the IMU will not change or become disoriented from wind drift in these phases

• the IMU yaw Cog gain will be enhanced by up to 6 times during the fly home phase, if the quad is pitched forward and if there is a discrepancy between the groundspeed and the velocity to home. This leads to a more rapid correction in the yaw heading in the event of a significant IMU error when starting to fly home, minimising any possible flyaway distance.

In a normal rescue, ie one commenced outside the minimum start distance:

• the descent distance cannot be more than half the distance when the rescue was initiated

• the IMU yaw Cog gain modified as above

Most rescues, no matter how close, or how extreme the IMU error, including initiating rescues while fully inverted, should now be successful.

Users should expect more aggressive yaw corrections at the start of the rescue than previously.

Here is a video of the typical behaviour.

If the IMU is not disoriented at the start, because the pre-rescue flight pattern was mostly nose-forward and at reasonable speed, the initial rotation return should be smooth, even for initiations close to, or within, the minimum rescue distance.

When the IMU is badly disoriented, eg from prior drift, or from flying backwards immediately before the rescue, it must have a period of time in clean forward flight before it can correctly re-orient its heading to match the GPS-measured course over ground. While doing this, the quad may initially fly away in whatever direction the IMU tells it to, but should quickly realise that it is going the wrong way, and rapidly try to correct itself. These corrections can involve quite extreme yaw and roll movements, including yaw overshoot corrections, as the IMU tries to correct itself at the same time as the heading itself is changing. As the quad gets better oriented, points more directly to home, and picks up clean speed towards home, the IMU errors should resolve, and the rest of the flight home should be uneventful.

When a rescue is initiated close to home, especially within the minimum rescue distance, there won't be much time in forward flight for the IMU to correct itself. Additionally, there may be little forward velocity, and an uncorrected IMU error cannot be resolved until the forward speed is greater than 2m/s, and a near-home initiation would require a near vertical descent with little or no forward speed, giving the IMU no chance to correct itself. This is why in previous versions, an initiation within the minimum start distance was managed by disarming the quad; the risk of flyaway was too high.

With this PR, an initiation within the minimum start distance of 15m, and above the landing height, will cause the quad to climb, then fly out to at least the minimum start distance, and then perform a normal rescue. Note that if the IMU is in error, the flight out to 15m from home could be in any direction at all, including overhead or behind the takeoff point. Sufficient climb height should be configured to ensure clearing any trees that could be within 50-60m of the takeoff point.

BE AWARE that for all rescues initiated inside the minimum start distance, the craft will:

• always fly out to AT LEAST the minimum start distance before turning towards home, and
• in cases of extreme IMU disorientation, having attained that distance, rotate to point in ANY DIRECTION AT ALL, including further way from home, once the craft reaches the minimum start distance.

The default minimum start distance is 15m, with a descent distance starting at half that value, or 7.5m. Generally it is best to avoid initiating a rescue so close to home. We only provide a rescue functionality in this situation to handle unexpected situations, eg while learning to fly LOS, or accidental initiation. The return can be quite hectic and involve circling behaviours and rough landings. The intent is for the pilot to recover manual control as soon as practical.

If flying in a large open area, and if you really wants the ability to make the rescue work at any point in the sky, including directly above the take-off point, please take off from a point that has plenty of clear space all around.

A slightly increased minimum start distance will give a less hectic recovery, but will allow a greater potential fly-away distance, when initiated within the minimum start distance. If the minimum distance is set too close, the quad may not get enough forward speed to correct the IMU, and will show multiple rapid yaw/roll adjustments that do not resolve fully before landing, leading to circling around the home point during descent, and a rough landing. However, the quad will get home.

NOTE: extreme IMU disorientation happens in the following situations:

• after power up, the quad is flown straight up, or very slowly. The IMU never experiences any forward flight > 2/ms before the rescue is initiated. It therefore never orients itself to the course over ground, and has no idea which way the nose is pointing.
• The quad is fully inverted and has been drifting when the rescue is initiated
• the quad has been drifting backwards, or nearly backwards, for more than 6-8 seconds before the rescue is initiated
• the quad has been drifting in the wind at speeds >2m/s for 5-8 seconds or more
• any combinations of the above.

NB: As before, if a rescue is initiated:

• within 5m of home, and
• below the landing height of 5m
  the quad just disarms, to prevent injury caused by accidentally initiating a Rescue while the pilot and the quad are in close proximity, or when the quad is on the ground.