45 release notes draft

docs/release/Betaflight-4.5-Release-Notes.md

@@ -0,0 +1,243 @@
+# Betaflight 4.5 Release Notes
+
+## 1. Cloud Build
+
+The cloud build system [introduced in 4.4](https://betaflight.com/docs/release/Betaflight-4.4-Release-Notes#1-cloud-build) retains the same user interface.  Updated board configurations should result in correct default hardware assignment.
+
+## 2. GPS
+
+The code connecting Betaflight to a GPS Module has been thoroughly overhauled.  
+
+When the FC boots, our UBLox code cycles through all available baud rates on the GPS Port until we connect to the module.  Then we instruct the module to change its baud rate to match the requested baud rate, which defaults to 57600, and we re-connect at that baud rate.  We then detect the 'class' of GPS module (M10, M8 etc) so that we know what kind of configuration requests it will respond to, and we re-configure it to send only the values we need, and stop it sending any other data. This ensures that the traffic on the serial port is the absolute minimum required for our purposes, and reduces CPU time.
+
+If the FC is connected to Configurator at boot time, we request the full satellite information list, so that we can populate the detailed satellite information list on the left side of Congfigurator's GPS tab.  Otherwise this information is not requested, because we do not require it while in flight, and it adds a lot of serial port traffic when enabled.
+
+The CPU cost and task timing for GPS data has been extensively reviewed and optimised.  Even so, GPS Rescue puts a huge load on a CPU.  For reliability it is best to use a 4k PID loop on all F4 processors, especially at 57600 baud.  More information about CPU load vs Baud Rate is available in the [GPS Rescue 4.5 documentation](https://betaflight.com/docs/wiki/archive/GPS-Rescue-v4-5).  The CLI `tasks` command may be used to check CPU usage and task over-runs when evaluating the impact of baud rate in relation to PID loop frequency. 
+
+The UBlox module 'class', and the baud rate it is actually connected at, may be checked with the CLI `status` command.
+
+The `GPS_CONNECTION` debug has been added, including a number of fields to help debug GPS task baud rates during the connection process, CPU cost, and ongoing execution times and intervals.
+
+Note that the GPS module must be powered up at the same time as the FC for it to be correctly configured.
+
+NMEA support is now very limited.  Using NMEA is not recommended.  Modern M10 GPS modules with a backup battery are highly recommended.  
+
+There should be no need for a user with an M8 or higher UBlox module to customise it in any way, e.g. with uCenter, unless it is somehow strangely locked and unresponsive to normal UBlox configuration commands.  They should essentially all work 'out of the box'.
+
+Thanks to @unit/freasy, ctzsnooze and SteveCEvans for this epic effort.
+
+## 3. GPS Return to Home Improvements
+
+In 4.5 there was a determined effort to make GPS Rescue even more reliable and precise than in 4.4.  Many significant changes and improvements were implemented.
+
+Task timing was carefully optimised.  
+
+Note: for most standard F4xx GPS Rescue builds, looptime should not exceed 4k, to provide enough clock cycles for all the required sensor data to be analysed and handled properly. 
+
+In 4.4, if there was significant drift, due to wind, when initiating GPS Rescue, and a long climb period, the quad could think that it was flying nose-forward in the direction of the drift.  This caused the initial yaw correction to be wrong, and the quad would then fly off in the wrong direction, often at high speed.  After a few seconds, it would correct, but take a wide arc to return to the correct heading.  4.5 improves this considerably, but without a Mag, it still can happen, to some extent.
+
+Hence we also put a lot of effort into checking and optimising the Mag code (see later), and optimising its integration with GPS Rescue.
+
+In 4.5, if Mag is properly oriented, configured, and calibrated, and is confirmed to return reliable heading information, the quad should rotate correctly at the start of a rescue, and point directly to home every time, regardless of drift.  This significantly improves safety of a rescue on windy days.
+
+In 4.4, if there was a long descent phase on windy day, the quad could overshoot home and then need to turn 180 degrees to get back against the wind, which could result in a fast spiral descent with a rough landing.  In 4.5, this should be less of a problem, because we don't start to pitch forward after an overshoot until the yaw heading is largely corrected.  In 4.5, a properly validated Mag will improve heading control on windy days during the descent phase.
+
+GPS Rescue can now be initiated directly overhead, in an emergency, eg when flying LOS, so long as the machine is more than the minimum allowed initiation height.  In this situation, the quad will climb, fly out to the minimum distance, turn back to home, and enter a normal rescue at that point.  This should only be used in an emergency, because the heading the quad will initially take is quite unpredictable, depending mostly on prior drift direction and velocity.
+
+The sanity checks are now a bit less intrusive and should be less likely to trigger except when they absolutely are required.  In particular, initiating too close will let it descend slowly in 'do nothing' mode until it lands or the user regains control.
+
+The GPS tab in Configurator has been updated to include a more useful satellite list and to show the Mag heading information.
+
+An edge case issue where the motors could spin up if the Rx link initiated at a vulnerable time, and when GPS Rescue was set to ignore home point, was fixed.
+
+Please carefully read the [GPS Rescue 4.5 documentation](https://betaflight.com/docs/wiki/archive/GPS-Rescue-v4-5) for more information.  
+
+thanks to @ctzsnooze, @ledvinap, @SteveCEvans @haslinghuis
+
+## 4. Magnetometer update
+
+This code was extensively revised, with a lot of improvement in compass task scheduling and driver support.
+
+Previously, the compass task ran at 10Hz, and its state engine could mean that new data points arrived at half or a third of that rate.
+
+In 4.5 we receive compass data values at the highest rate supported by the chip.  In the case of the QMC5883L, this is 200Hz, and for the older HMC5883L, it is 80Hz.  This greatly improves the accuracy of the calibration process, and reduces data lag issues.
+
+The biggest improvement is in our calibration process.  This now works much better, giving consistent results, when the previous code was almost a random number generator.
+
+We can now use `set mag_declination` in the CLI to enter our local Magnetic Declination value and better correct Magnetic to True North.
+
+A [detailed wiki note](https://betaflight.com/docs/wiki/archive/Magnetometer) now explains how magnetometers work, how to orient the mag and check that the orientation is correct, how to calibrate the mag and how to check the calibration, how to set the correct declination value in the CLI etc.  
+
+Users can now set up a Mag and be sure that it works.
+
+Note that Mag units must be mounted as far as possible away from motors and high-current wires or the data will be extremely noisy, almost unusably so.  Getting clean data from a Mag on a 5in quad is quite difficult.
+
+Important: note that after initiating a calibration, the frame of the quad must be 
+'tapped' hard to start the 30s data acquisition period.  This was introduced to give the user time to get ready to start collecting data.  This tap must be done within 15s of initiating the calibration.  If no tap is detected, the old values will not be updated.
+
+The `MAG_CALIB` and `MAG_TASK_RATE` debugs have been added to investigate calibration and scheduling issues.
+
+Please read the [wiki note](https://betaflight.com/docs/wiki/archive/Magnetometer) carefully, and test it thoroughly, before using the Mag in a GPS Rescue.  Note that the current default for GPS Rescue is to use the Mag.  If you are not 100% sure that your Mag is working, don't use it.
+
+thanks to @pichim, @ctzsnooze, @SteveCEvans
+
+## 5. RPM Limiter build option
+
+This is a custom build option, requiring `USE_RPM_LIMIT` in the custom flashing options.  It limits the max average RPM to a user-specified value, and is primarily intended to help standardise quad behaviour for Spec Racing.
+
+Thanks @Tdogb, @Limonspb, @karatebrot
+
+## 6. Automatic LEDstrip colour based on VTx channel
+
+Ledstrip colour can now be automatically set according to VTx channel. Enter `set ledstrip_profile = RACE` and `set ledstrip_race_color = BLACK` (disabled) to activate.  The VTx should use RaceBand frequencies.  Resulting colours should be Whilte, Red, Orange, Yellow, Green, Blue, Violet, Pink for R1-R8 respectively.
+
+Thanks @cruwaller
+
+## 7. Rainbow colour effect for LEDstrip
+
+See: [PR12323](https://github.com/betaflight/betaflight/pull/12323/files)
+
+Thanks @ASDosjani
+
+## 7. Angle and Horizon Mode update
+
+Angle and Horizon modes are completely different from 4.4.
+
+Angle mode is a lot snappier, due to `angle_feedforward`.  High angle P values, which used to cause oscillation, are no longer needed.  At P values which do not oscillate, the responsiveness to stick inputs is much quicker.
+
+It also now uses the user's RC Rate settings to determine stick feel, facilitating the transition to Acro or Horizon.  Angle no longer has its own specific stick configuration.
+
+Angle Mode is now 'earth referenced' by default.  This means that a pure yaw stick input, while pitched forward, will result in a perfectly coordinated turn.  The code mixes in exactly the right amount of roll so that the horizon stays 'level' in the camera.  It also helps stabilise the quad during fast yaw inputs in Angle mode.  
+
+Roll inputs in angle mode will always add extra roll, and the 'horizon' in the camera will respond accordingly, if that's what the pilot wants to achieve.  
+
+The earth referencing behaviour can be disabled with `set angle_earth_ref = 0`, or its strength halved with `set angle_earth_ref = 50`.  Whoop racers may well prefer to disable it, however most beginners, and anyone doing cinematic shooting in Angle mode, should find it really nice.
+
+Angle and Horizon mode motor control is now significantly smoother, due to filtering refactoring and optimisation, reducing motor heat and minimising camera jello.
+
+Horizon mode has been changed a lot.  Horizon mode provides self-levelling when the sticks are centered and the quad is close to being flat, but flies like acro at higher stick angles or when the quad is steeply angled.  The 'self-levelling' strength, when the sticks are in the center region and the quad is nearly flat, can be as strong, or as gentle, as the pilot likes.  The angle of the frame at which there is no self-levelling can als be adjusted.  With the default settings, flips and rolls to be performed, and with a bit of tweaking, inverted hangs are possible.
+
+For more information, and sample configuration snippets, see [PR 12231] (https://github.com/betaflight/betaflight/pull/12231)
+
+Thanks @ChrisRosser and @ctzsnooze
+
+## 7. Failsafe changes
+
+Failsafe indicators at the time on Rx loss are slightly different, and some safety related issues have been fixed.
+
+If `RXLOSS` is triggered by 100ms of no valid data, the message will appear in the OSD for a minimum period of 1.0s, instead of clearing immediately.  This is consistent with the arming block after Rx loss, which persists for 1.0s by default, even a brief loss of signal.  
+
+The change prevents a potentially dangerous arming conditions which could arise if GPS Rescue was active and the Rx signal at arm time was unreliable, or the user armed then quickly disarmed.  
+
+Additionally, on restoration of signal, the `failsafe_recovery_delay` period is now 500ms, recovering twice as fast as before after signal is restored.
+
+Finally, the `BADRX` OSD message now says `NOT_DISARMED`.  This occurs when the Rx signal has recovered, or has just been detected, wbut the arming switch has been left in the Armed position.  The new message provides a better explanation to the user that they must Disarm before attempting to re-arm after signal loss.
+
+thanks @ctzsnooze
+
+## 8. Dimmable RPM Harmonics
+
+The user can set how much 'strength' is applied by each of the three RPM filters.
+
+In many tri-blade situations, the second RPM harmonic can be relatively low in amplitude.  With this PR, it's possible to disable it selectively, or to any desired amount.  For example, `set rpm_filter_weights = 100, 0, 80` effectively disables the second harmonic and only attenuates the third harmonic by 20%.  
+
+The main benefit is lag reduction on clean builds.  Attenuating a notch filter reduces filter-associated lag, which, in turn, can improve propwash.  This is an advanced tuning option.
+
+thanks @karatebrot
+
+## 9. Customisable initial Dynamic Idle percentage
+
+After arming, but before airmode activates, the motors receive a fixed idle value.  
+
+This value can now be customised in the CLI, instead of being always 5%.  Use the `dyn_idle_start_increase` value, which defaults to 50, meaning 5%.  
+
+A higher value can be useful if the motors need a higher idle value to spin properly on arming when Dynamic Idle is active, and conversely if large motors spin well at low idle percentage, it can be reduced.
+
+thanks @tbolin
+
+## 10. Quick OSD Menu build option
+
+This is a custom build option which adds a 'quick menu' to the OSD.  It is particularly useful for spec racers who need to easily configure and display throttle and RPM limits.
+
+Include `USE_OSD_QUICK_MENU` when building, and enter `set osd_use_quick_menu = ON` in the CLI
+
+For more information see [PR 12977](https://github.com/betaflight/betaflight/pull/12977)
+
+thanks @Limonspb
+
+## 11. RC Stats OSD build option
+
+This is a custom build option which adds flight throttle statistics, such as time on 100% throttle and average throttle, to the post-flight stats pages.
+
+Include `USE_RC_STATS` when building.
+
+For more information, see [PR 12978](https://github.com/betaflight/betaflight/pull/12978)
+
+## 12. Blackbox and logging updates
+
+Blackbox now supports 8 channels of data per debug.  Not all debugs have been updated to take advantage of this, but it is extremely helpful when developing.
+
+All eight values can be seen in Sensors
+
+A number of new debugs have been added, and their display in Blackbox should be correct.
+
+thanks @bw1129, @ctzsnooze, @karatebrot, @mcgivergim
+
+## 13. Configurator updates
+
+Many improvements, big and small
+
+thanks @haslinghuis
+
+## 14. Hardware support
+
+As a result of our improving engagement with manufacturers, we were able to respond to user feedback and improve the target configs for many boards.  We are actively encouraging good design principles and working to ensure that new configurations will work reliably.
+
+Support for the following hardware has been added:
+- AT32 CPU
+- ICM4268x IMU
+- LSM6DSV16X IMU
+- LPS22DF Baro
+- H725 CPU (test carefully)
+
+A number of H7 improvements and fixes were implemented.
+
+thanks @SteveCEvans, @blckmn, @karatebrot, @sugark
+
+## Other Changes and fixes
+
+- Launch Control is now a standard option
+- an issue where a sensor that was not enabled on power was incorrectly saved as not being enabled by the user
+- DShot Telemetry now independent of RPM Filtering, fixing minor related issues including dynamic idle
+- DShot code stability improvements
+- improved support for higher ESC telemetry voltage readings
+- less likely to have issues where a connected radio Tx could affect DFU
+- stops softSerial adversely affecting USB on F411
+- target defines updated for many boards
+- best of 3 laps in the GPS lap timer fixed
+- OSD VTx band/channel info fix when direct frequency is used
+- Accelerometer scaling in MSP could sometimes be incorrect
+- improved F7 UART behavior on boot, LED Strip fixes, 
+- improved F4xx UART enable/disable
+- ESC Serial fixes for HAL targets
+- Improved USART pull-down behaviour
+- Fix for sag compensation when RPM limiting is active
+- Improved at32 support: UARTs, i2c code, SITL port number, SRAM configuration, camera control, evaluation order. additional timers
+- fix for USB comp port failures on some hosts
+- RPM limiter bugfixes
+- sending commands to motors improved
+- improved handling of invalid baro readings
+- Ghost Rx code fixed on F4xx
+- fixes to many board config files
+- improved filter code efficiency
+- refactoring of feedforward and RC smoothing to improve efficiency
+- fixes for DShot beacon, ensuring DSHot 0 between beacon commands
+- default the F411 to DShot300 and 4k if DShot Telemetry is enabled
+- multiple cloud build fixes
+- improved FF smoothing for 1000Hz Rx rates
+- cleaner MPU6000 reset
+- dynamic idle won't now fail if RPM filtering is turned off
+- RPM Limiter fixes
+- many other bugfixes, target updates, driver updates and fixes
+
+Wow!