How to install/Flash Betaflight Firmware (GUI or DFU Mode)

How to install/Flash Betaflight Firmware (GUI or DFU Mode)

This is a quick guide that will walk you through the process of flashing betaflight firmware onto your flight controller




What is a "Firmware Target" or "HEX File" in this context?

Betaflight firmware is made to run on many different boards. So, it is essential that Betaflight and the manufacturers are able to communicate to let one another know which pin on the board does what action in the firmware. This is where Firmware Targets come in - a manufacturer can provide a file which essentially tells the Betaflight firmware "We've chosen this pin for this action",  and that means the Betaflight developers don't have to do as much additional work to make sure the board will be supported by Betaflight. It's like a translation layer between the hardware (the components on the board) and the firmware (Betaflight).

A HEX file is just the name commonly used to refer to the firmware file itself. Once you've selected a firmware target and version, you have the option to "load online" in Betaflight. What this actually does is uses the target you've selected and the version you've selected to pick out the specific firmware file for your board from a large online library of firmware files for all versions and targets, so you don't have to do it yourself. Sometimes, though, manufacturers will provide you with a HEX file rather than a firmware target to select. This might be because they use a modified version of Betaflight and the typical releases won't work, for example, though this is rare.

In other words, it is very, very important that you choose the correct firmware target or HEX file for your board. If you don't, then the software running on the board won't know what to do with the hardware on the board, and ultimately the board won't work.

Which Firmware target do I select, or which HEX file do I need to flash my Flight Controller Firmware?

The best way is to check the flight controller product page or manual as both locations will typically say what target you need to use. You're looking for something like in the image below; 

It might be labelled as "Target", "Firmware", or similar.
If it is not clear, it's best to ask your retailer or the manufacturer who will be able to provide details to avoid installing the wrong firmware and bricking your board. Alternatively, if the FC is already working fine and you just wish to upgrade the firmware, you can find the target yourself by checking out this guide.

How to Flash Firmware using Betaflight GUI

Firmware Flasher Tab

This tab is used to update the flight controller's Firmware.

For Betaflight 4.4 and above, firmware updating uses an online build process. The user selects their flight controller, the code version to flash, and enables the features they want. A custom firmware 'hex' file is then built online, downloaded, and installed onto the flight controller.

Firmware Flasher tab

Preparation​

  • Upgrade to the latest Betaflight Configurator.
  • Before upgrading a flight controller, choose either save backup from the Presets Tab, or save a diff file via the CLI. This will store the configuration as used by your old firmware, in case you have to revert back to the old firmware. The CLI status command provides info about the hardware currently being used.
note

To revert to previous firmware, the same online process would apply, but you would choose the original firmware version, and then restore your saved diff file.

Configurator only supports Betaflight version 4.0 and newer. Older versions of Configurator may be needed to flash older firmware.

Basic Flashing Procedure​

caution

This will ALWAYS erase all previous configuration data from the flight controller!

To flash a final release version of the firmware:

  • leave Enable Expert Mode OFF
  • leave Show Release candidates OFF
  • Click 'auto-detect' and ensure the correct board name appears in the list
  • Choose the firmware version to flash

The Build Configuration area then appears:

  • Choose the Radio Protocol... include telemetry if not automatically included
  • Enable other hardware options, eg OSD, VTX, GPS, LEDStrip etc

The screen should look something like this, for a JHEF411 with ELRS, GPS, LEDstrip, Mag, OSD (SD) and VTx included:

Firmware Flasher basic

If you're happy that everything is OK, click Load Firmware [Online], and wait for the firmware to build and download.

Then click Flash Firmware.

A dialog to save the current configuration as a diff file is provided in case you didn't do this already.

Once the firmware is flashed, re-connect, calibrate your accelerometer, and re-configure your settings.

Generally, we recommend full manual re-configuration. When the flash is from the same point version, usually it's OK to import a saved Preset, or paste a Diff. Parts of a diff can also be selectively pasted into the CLI, eg the VTX Table, or the modes and aux settings. Do not copy and paste data from the profiles or master sections of a dump unless you know what you are doing.

caution

After flashing, always check that every setting is 'as it should be', before test flying. Your first test flights should be cautious and in a safe environment.

Flashing Release Candidate firmware builds​

Release Candidates are special firmware builds that are provided to test 'nearly completed' firmware. They are only available late in the development of a new firmware version, when we think it is almost ready. For example, 4.5.0-RC2 is the second RC version of Betaflight 4.5; it was released for testing on 08-Jan-2024. Usually these builds are stable. Developers really appreciate public testing of PR builds.

To see Release Candidates:

  • Enable Expert Mode
  • Enable 'Show release candidates'
  • Choose Release and Release Candidate from the new dropdown
  • Auto-detect to select the correct flight controller
  • Choose the Release Candidate version that you'd like to flash
  • Proceed as for basic flashing, above.

Flashing Development builds​

Development builds contain the most recent changes made to the firmware.

This option lets you test out a new feature, or try out a significant change to the code, as soon as it is added to the master branch. If, for example, Betaflight 4.5 is the current release version, the development versions available in the list will be 4.6, and the latest code for the most recent update branch for 4.5, e.g. 4.5.3.

To see Development versions:

  • Enable Expert Mode
  • Enable 'Show release candidates'
  • Choose Development from the new dropdown
  • Auto-detect to select the correct flight controller
  • Choose the Development version that you'd like to flash (RC's are there too)
  • Proceed as for basic flashing, above.

Other 'Expert Mode' options​

Setting Meaning
No Reboot sequence Use this if your board is already in DFU mode
Flash on connect (Hazardous) Immediately flashes the next board you plug in, without checking it's type or offering to make a backup
Full chip erase Default is ON, and for good reason. See notes below
Manual Baud Rate Default is good, but sometimes slower is more reliable
note

Full chip erase completely wipes the NVRAM, deleting all your saved configuration data, and replaces it with new default values and the new data structure for the new firmware.

Full chip erase should only be disabled when you are 100% certain that the configuration data structure has not changed since the last flash, otherwise incorrect configuration values may be retrieved by the new firmware, with potentially disastrous results.

Build Configuration​

In the Build Configuration section, the user selects the hardware support code that will be included in their firmware build.

There are four basic configuration groupings:

Radio Protocol​

Select the receiver protocol used. The most common are:

Protocol Receiver
CRSF TBS Crossfire or ExpressLRS
GHST Immersion RC Ghost
SBUS FrSky or Futaba
note

EXPRESSLRS SPI receivers use the CRSF protocol and the main version number must match (eg an ELRS SPI receiver in Betaflight 4.4 and 4.5 will only work with ELRS 3.x in the Transmitter).

FrSky SPI receivers use SBUS or FPORT protocol depending on the receiver firmware used.

SPI configuration details are resolved via software (part of the configuration data). Some of the required information may be included in the flash via the board definition file.

Telemetry Protocol​

Select the telemetry protocol you need. For CRSF, ELRS, FPORT or GHST protocols, this is included by default to simplify configuraton.

Other Options​

These are custom functions or features that you can add to the firmware.

Option Description
AKK (SA Fix) SmartAudio patch for AKK hardware
Acro Trainer Enable Acro Trainer support
Batt. Continue See #11084
Cam. Control Enable Camera Control
Dashboard Enable external i2c Oled Display device (to be deprecated)
EMFAT (AutoRun, Icon) Enable FAT emulation and icon for onboard flash or MSC
ESC Serial (SK) Inc. 4way Enable SimonK and ESC Serial support for flashing via 4way interface
Flash Storage 4.4 and earlier only. Enables Blackbox Flash Storage support. In 4.5, is auto-included via the FC config file. To manually add Flash to a 4.5 build, enter FLASH in Custom Defines
FrSky OSD Enables FrSky OSD support
GPS Enable GPS and GPS_PLUS_CODES
LED Strip Enable 32 LEDs
LED Strip 64 Enable 64 LEDs
Magnetometers Enable magnetometer (compass)
OSD (SD) Enable SD OSD (onboard MAX7456 required)
OSD (HD) Enable HD OSD (eg DJI, HDZero, Walksnail)
PIN IO Enable PINIO
RACE PRO see Betaflight 4.5 Release notes
Servos Enable Servo support
VTX Enable VTX

Motor Protocol​

Select the Motor control (ESC) protocol to use. DShot is default.

Custom Defines​

This field is only available in expert mode, and is intended for development and testing.

It allows the user to enter the coded 'name' for a 'hardware define', forcing that code to be included in the build. More than one define can be included, separated by spaces.

For example, the local build options -DUSE_RANGEFINDER -DUSE_ACCGYRO_LSM6DSO can be included as Custom Defines when making a cloud build with RANGEFINDER ACCGYRO_LSM6DSO.

For advanced users, the Defines page in our development section provides a list of Custom Define options available early 2024.

Select Pull Request or Commit​

This field is only available in expert mode, and is intended for development and testing of yet to be merged code that is in 'Pull Request' status. This happens when a developer has proposed a change to the code base, and has put it up for testing.

It defaults to the latest commit (master), meaning the most recent commit of the selected firmware branch. The dropdown includes some recent commits if you want to go back a bit.

Each GitHub pull request has a uniqe ID. The user can include a specific, yet to be merged, Pull Request, over the top of master, by typing the number of the pull request, preceded by the # character. For example, to include Pull Request #13605, just enter #13605 in the Custom Defines field.

It is also possible to make a build from any previous point in time by entering the sha of the commit.

Troubeshooting​

tip
  • Use a good quality data cable, not a power cable.
  • USB hubs or OTG cables are sometimes needed with recent computers and in other cases they can cause issues.
  • Try disconnecting all cables from your PC first, try rebooting, other ports, upgrade system drivers. Remove other USB connections.
  • Try DFU mode (use boot button on FC while plugging in, use Activate Boot Loader / DFU button in setup tab or use bl command in CLI.
  • Sometimes peripherals on the flight controller such as receivers or GPS devices can hijack port communication, preventing entering DFU mode. These may require de-soldering.
  • Linux needs configuration to allow flashing.
  • MacOS or Windows do not need any drivers.
  • If it still doesn't work try IRC Driver Fix or Zadig on Windows platform.
info

If your board pheriperals are not recognized after flashing, please help us add the required configuration details. Some boards have inadequate file definitions, or the manufacturer has changed something on the board.


Reach out to us on our Discord server or create an issue in the Betaflight unified targets repo.


To get the required information follow this procedure:

  1. Flash your board with the Core Only switch enabled
  2. Go to the CLI tab and click the Submit Support Data button.
  3. With this generated support ID we should have all the required information, but we would then need your help to confirm a fix..

Checking the Build​

The Show Log link will open the build log and show the defines being applied to the build, the code build outcome, and the file size details.

The log file incudes a full string for use when flashing the same build locally is provided, both for Docker and Make.

At any time after flashing, the log can be re-loaded using the log buttom at the lower right side of Configurator's SSetup page. A summary of the included build options can be displayed using the nearby Options button.

Local Flashing​

If you have a local build environment and can make hex files, or you just have a hex file to flash, it can be flashed directly.

For 4.4 and 4.5, the hex file must be custom-built or pre-built with all the hardware options already included. There is no need to choose a board in the drop-down, or set any options, because all the required defaults and options exists in the custom hex file. Note that the configuration file only contains the default configuration values; the user will have to check and update the settings before flying.

Hovering your mouse over 'Loaded Online Firmware' in the Flashing Tab, before actually flashing the code, allows downloading the firmware hex file to your computer for local flashing later on, if needed.

Previously an MPU-specific hex file was used, and the user had to ensure that the board was selected, so that the board-specific hardware details would be flashed after the hex.

To flash local development firmware with optional custom configuration use the Load Firmware local button to load board configuration or click Auto-detect or when in DFU mode select a board manually.

note

If, when flashing older MCU-generic firmware, and if you have a local configuration file, load it first, then use the same button again to load the local hex file.

Fixing driver issues & Other driver info

  1. There are (pretty much) two classes of USB devices used by all Flight Controllers (FCs):
    1. Type 1. Using a Silabs CP2103 USB interface chip (usually for older flight controllers).
      1.  Needs the Silabs CP210x driver. Used in both BootLoader mode for flashing and normal config mode. Shows up as a "COMx" device in BetaFlight Configurator.
      2. http://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers
    2. Type 2. Using the MCU integrated STM32 VCP USB interface (most F4, F7 based flight controllers use this).
      1.  Needs WinUSB driver when in BootLoader mode, for flashing. Installed by Zadig or ImpulseRC DF. Shows up as a "DFU" device in BetaFlight Configurator.
      2.  Needs STM VCP driver for connection and configuration with BFC Shows up as a "COMx" device in BFC.

The quick and easy method to fix drivers (works for most modern flight controllers):

An easy and quick hack is to run the ImpulseRC driver fixer which will usually pick up and install the required drivers for your, see  https://www.dronetrest.com/t/fix-any-stm32-dfu-drivers-issues-when-flashing-betaflight-cleanflight-firmware/3603

DFU flashing under Windows - USB DFU:

Make sure you have zadig if you're using Windows to enable the DFU driver. Instructions:

  1. Download Zadig: http://zadig.akeo.ie/
  2. Put device in DFU mode. If this is the first time to put Betaflight on you need to short the BL or BOOT pads (or press and hold the BOOT tactile button) while plugging the USB into the board.
  3. Open Zadig.
  4. Options > List All Devices
  5. Click on the drop bown box and click the device listed STM32 BOOTLOADER 
  6. In the box to the right of the green arrow, select WinUSB (v6.1.7600.16385)
  7. Click Install Driver
  8. After the install completes, restart your computer (you can cheat and ensure no browser is running - but it is not guaranteed to work). The board should stay in DFU mode - IF - usb power remains during the reboot. If not, execute step 2 again.
  9. Open up the Betaflight configurator.
  10. Go to firmware flasher, select "No reboot sequence"
  11. On F4 targets disable "Full Chip Erase". Use the config reset in Configurator later. (#200 reports the issue.)
  12. Load Firmware [Local]
  13. Browse to and select the proper hex file. (betaflight_REVO.hex for the revo, for example)
  14. Click flash firmware.
  15. The board should start flashing. First indicating an erase, then flash and finally verification.
  16. Once flashed your board will reboot, but you may need to install the STM VCP driver (see below) for Betaflight Configurator to connect to the board.

Installing STMicro Virtual Com Port (VCP) Driver under Windows:

Many of the F7, F4 (REVO, ALIENFLIGHTF4, BLUEJAYF4, etc), and some F3 boards (SPRacingF3EVO, STM32DISCOVERY) utilise the STM32 Virtual Com Port (VCP) - a CDC serial implementation. This allows the UARTs on board to be utilised whilst the USB is connected. This requires the STM VCP driver to be installed so that the VCP to be recognised as an additional comm port on the PC. NOTE: this is similar to installing a USB serial driver, e.g. FTDI or SiLabs

The STM32 VCP driver can be downloaded here --> http://www.st.com/web/en/catalog/tools/PF257938

NOTE: Once you download and run the installation it has not installed the driver, merely unpacked the choice of drivers. Locate the installation directory and then run the EXE file pertaining to your system.

e.g. C:\Program Files (x86)\STMicroelectronics\Software\Virtual comport driver\Win8\ <- will have two files present. One for 64 bit systems (dpinst_amd64.exe) and one for 32 bit systems (dpinst_x86.exe).

Windows 10

in many cases, the above might not work. installing Virtual COM port drivers from SiLabs will solve the issues: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers