A simple way to configure your Betaflight Flight Controller Firmware settings.
- Introduction
- Applying and using Presets
- Providing feedback
- Creating new presets
- Modifying existing presets
- Preset specifications
- Credits
The Betaflight Preset system makes it easy for a user to find and apply CLI 'snippets' to configure or modify their firmware settings.
All Presets go through a checking and approval process before being made publicly available.
WARNING: When a Preset is saved, the configuration settings are permanently changed! Users MUST make a backup of their previous settings, and know how to restore their settings from the backup.
- Make a backup of your current settings (go to CLI, type
dump all
, and save that data to a safe place)` - Go to the Preset tab in Configurator
- Search for the Preset that you want to apply, and click on it
- Read the description, and optionally review the changes that will be made by clicking
Open Online
- Select from the available
options
using the checkboxes - Click
Apply
- this writes the settings to the CLI - Click
Save
to permanently write the changes to the firmware. There is no undo function.
If a Preset changes things that you don't want to change, make a note of those changes before applying the preset, and change them manually, later, in the CLI. For example, if a complex Preset includes a Rates change that you don't want, make a note of your existing Rates, apply and save the Preset, then give it a try with the new rates. If you don't like the new rates, manually restore your original settings.
More than one Preset can be applied, sequentially, before saving. If the same field is changed by multiple presets, the last applied Preset takes precedence.
It is normal to need to reconnect to the Flight Controller after leaving the Presets tab. This is because the Presets system involves interactions with the CLI, and on leaving CLI we must reconnect.
Currently, the best way to provide feedback is by adding a comment to the Pull Request that generated the preset. Use the Discussion
button in the Apply Preset window to go to the Pull Request.
Alternatively, search the Firmware Presets Pull Request page.
Submissions for new presets must be made with a GitHub Firmware Preset Pull Request (PR):
- A separate PR is required for each Preset.
- Every PR will be carefully assessed by Betaflight developers.
- Approval is not automatic, and may take some time.
- Since CLI names and preset values will change from version to version, it's usually best to make separate presets for 4.2 or 4.3
- The Preset must comply with the specifications and must include a concise description of what will be changed
When making a Preset, the changes to be made to the existing configuration can be applied in four fundamentally different ways:
- Replace or force overwrite one or more values with new values that actively achieve something, eg change a PID value, or a parameter set to a higher than default value.
- Force some values to off, or to default, so that regardless of the user's prior configuration, these settings will no longer be active, or will be at default values. This requires lines in the Preset that set the parameters to off, or to their default values, or by
including
a defaults file before applying the active changes. 'Including' a defaults file before your changes can provide a 'clean slate' over which active changes are written. It can, howeever, make more changes than are needed. Always check that an included defaults file only makes the changes you really need, and doesn't mess with settings that a user would likely want to keep, or are irrelevant to your Preset. - Ignore some values, or not change values that don't matter to your Preset, at whatever value the user the user has in their configuration, by not mentioning those parameters in the Preset.
- Provide checkboxes so that the user can choose between alternative or optional groups of values, eg to provide alternate filter settings to suit noisy or clean setups, or let the user choose to have Thrust Linear active on their quad. This can be done with
regions
.
A Preset should therefore overwrite any value that must be set to a specific value, disable or turn off values or settings that need to be off, and provide checkbox options (regions) to let the user choose, where appropriate, between alternative options.
Before final submission of the PR, check the preset by:
- installing
node.js
for your OS - running
node indexer/check.js
in a terminal window from your draft's working directory. The checker should returnOK
. If not, correct the errors and try again.
Remember to include the pull request URL in the Discussion
field.
After approval, the author:
- should be responsive to feedback from users via comments to the originating PR
- is responsible for maintaining compatibility with future Betaflight firmware releases
Presets may be modified, with or without permission of the author, by a subsequent pull request.
Any PR that modifies an existing Preset must be linked to the original PR, so that the author will receive notification of any proposed changes.
A Preset must include a field structure that complies with the specifications below, and one or more CLI 'snippets' as a payload.
Mandatory fields
Title, FirmwareVersion, Category, Official
Optional fields
Author, Description, Include, Keywords, Discussion, Nosearch
Field | Notes |
---|---|
File name | Unique, brief, descriptive, include author, underscores not spaces eg race_4in_ctzsnooze |
Title | Explanatory, clear, concise; include the main characteristics of the preset. |
FirmwareVersion | One line for each supported version. as many lines as requred. Ensure that all CLI commands are readable by the firmware versions listed. CLI commands that do not match will throw errors. If a Preset support two versions by including two versions of the same command, explain to the user that an error will be gene |
Official | True or False; true only for Betaflight developed Presets |
Category | See category list below. Only approved category names will be accepted. |
Keywords | Choose carefully. Make it easy for your intended user to find your preset with keywords that you expect they will use. Comma separate each entry. |
Author | Your Github name or nickname. |
Description | Clearly explain what will be changed, and, where relevant, what will not be changed. For example, if filter setup requires RPM filtering, be sure to state this. Each ``# Descriptionline results in a separate paragraph. A blank # Description` line results in a blank line between paragraphs. |
Include | Inserts data from one or more separate Presets ahead of the CLI commands of this Preset. Useful to enforce defaults ahead of your commands. See details below. |
Region | Commands within a region are optional. When a region is specified, the user is presented with a checkbox to apply, or not apply, the commands within the region. The default check-box behaviour can be specified. Each region must have a unique name. More info here |
Discussion | Field containing a URL that links to the feedback and discussion page for the preset. At present this must be set to the URL of the PR that generated the Preset. |
Nosearch | # Nosearch: true prevents a Preset from being indexed, and hence prevents it being found by a user search. Intended for 'invisible' Presets that are only included in other Presets. |
# Title: 7in long range cinematic by userx
# FirmwareVersion: 4.2
# FirmwareVersion: 4.3
# Category: TUNE
# Official: true
# Keywords: word1, word2, word3
# Author: Name Lastname / Pilotname
# Description: Description paragraph1
# Description: Description pagagraph2 (as many description paragraphs as needed)
# Discussion: https://github.com/betaflight/firmware-presets/pull/nn
# include: file/to/include1.txt
# include: file/to/include2.txt
<cli command 1>
<cli command 2>
....
<cli command n>
# region begin (checked) region1Name
<cli command n + 1>
<cli command n + 2>
...
<cli command m>
# region end
# region begin (unchecked) region2Name
<cli command m + 1>
<cli command m + 2>
...
<cli command k>
# region end
All presets must be assigned one of the following categories:
TUNE, RATES, FILTERS, RC_LINK, RC_SMOOTHING, OSD, VTX, LEDS, MODES, OTHER, BNF
Category | Notes |
---|---|
TUNE | PID parameters and sub-parameters like TPA, Antigravity, Thrust Linear, etc, including Filter parameters including RPM filtering. May include motor_output_limit, throttle curve / scale, feedforward_boost, feedforward_transition or feedforward_limit, vbat_sag_compensation, Throttle Boost, and the like. Should not include RC_lINK or RC_SMOOTHING settings unless provided in Regions that are set to unchecked by default. |
RATES | Rates type and the values that affect rates (rc_rate, expo and s_rate). Throttle curve settings, rate limits, or level expo settings are changed, they should be provided in separate presets. A Rates name may be provided in an optional default-off Region. TPA should not be included in a Rates preset, it is a TUNE parameter. |
FILTERS | Filter settings optimised to suit a particular type of build. Since filter optimisation depends greatly on whether or not RPM filtering is active, we must state the RPM filtering requirement be active in the name and in the description. A region may be provided with alternate settings for the situation where RPM filtering is not available. |
RC_LINK | The type of link (serial, PPM), the protocol used (SBus, CRSF, Spektrum etc), including telemetry settings, units, precision settings, etc, and the feedforward_averaging and feedforward_smoothing, and feedforward_jitter settings that must be configured to suit the link speed. Separate Presets, or Regions, may be used for RC links that can be set to different speeds. |
RC_SMOOTHING | RC smoothing settings vary how reactive the stick is to sudden stick changes. Auto configurations can provide anything from race to cinematic levels of smoothness, but the final amount of smoothness in an auto configuration also depends on the RC link speed. Manual rc_smoothing configurations can provide more consistent smoothing across a wider range of RC Link speeds. |
OSD | Any collection of OSD related parameters. May include report_cell_voltage, debug_mode or similar settings that affect what is shown on the OSD. |
VTX | A VTx table or related settings |
LEDS | LED configurations |
MODES | Mode switch and Adjustment configurations |
OTHER | Any Preset that includes settings from more than one category, or for settings that don't fall readily into other categories. Examples include: a complete configuration with rates, tune, link, and LED settings; or a set of GPS, Launch Control, Camera Control or similar values. |
BNF | A complete configuration for a pre-built machine. Regions may be used to provide alternatives options for RC_LINK, RC_SMOOTHING, or other settings. |
Optional paths to other Presets that are to be included in the current Preset.
- Works like the C/C++
#include
function. - Sequential
include
statements allow multiple Presets to be applied.. - recursion of
include
is not supported. - Metaproperties of
include
Presets are ignored.
Regions give the user control over some parts of a Preset with simple checkboxes.
The Preset author can decide if the checkbox should be checked or unchecked, by default, and defines the label next to the checkbox.
Regions mark a group of CLI commands into a named group, similar to the C# preprocessor directive #region
.
With regions, the user sees a list of options with checkboxes in the preset dialog, and can apply some, all or none of them.
One example of using regions is a BNF quad Preset. The manufacturer could add different regions for different radio protocols such as SBUS, Crossfire, Ghost, etc. The user can select the radio protocol when the preset is applied.
Another example could be to provide different RC_Smoothing settings, for example, to suit fast freestyle, HD freestyle or Cinematic usage within the same overall tune.
A region starts with # Region begin <region name>
directive. It can be extended with (checked)
or (unchecked)
to specify whether this region should be selected by default or not.
Every region must be closed with # Region end
. Put the CLI payload between # Region begin <region name>
and # Region end
.
Nested regions are not supported.
If an included Preset has regions, its regions will not be shown to the user, unless ‘dummy’ region/s have been pre-defined for each of the regions from the included Preset, like this:
# region begin <first_region_name_from_preset_x>
# region end
# region begin <second_region_name_from_preset_x>
# region end
(for however many regions in preset_x that you want to include)
# include path/preset_x
The Preset system was developed by @limonspb for Betaflight 4.3.