Great news everyone. We were working on this for several months and are finally ready to announce a new firmware update subsystem. You can now update firmware and databases on the SD card via Bluetooth using our mobile app! Download the mobile app for Android and iOS. The new firmware update subsystem will be added to the qFlipper desktop application as well.

In this post we will talk about why the Over-the-Air update was so hard to implement on Flipper Zero, how memory is arranged inside our STM32WB55 microcontroller, and will look at the firmware update process before and after.

Download the Flipper Mobile App

The Problem of Classic OTA Update

All modern devices provide Over-the-Air (OTA) firmware updates. You don't need to connect your phone to a PC to update the firmware, it updates over the internet. We've all gotten used to it and it seems totally normal now, but that wasn't always the case. Updating firmware over the air is in no way a trivial process. It took Apple 4 years to develop OTA since the release of the iPhone. The first iPhone was released in 2007, but you could only update it over the air in 2011 with the release of iOS version 5.0 for iPhone 3Gs.

The hard part of OTA is that at any given time the device has to run some kind of firmware to supervise the update process. In theory, our microcontroller supports OTA updates. It needs the old firmware running during the update process to control data transfer over Bluetooth while the new firmware is being uploaded next to the old one.

According to the manufacturer, it should work like this:

1. The old firmware is running and manages data transfer over Bluetooth
2. The new firmware is transferred to the available space on MCU's Flash
3. When rebooting the old firmware is replaced by the new one

What's inside the Flipper Zero processor

Flipper Zero's firmware is stored in Flash memory on the STM32WB55RG microcontroller, the heart of the whole device. There are several hardware modules placed inside one chip:

1. The main compute core, 64 MHz ARM Cortex-M4 — this core runs our main firmware, the source code is available in the Flipper Zero Firmware Sources repository.
2. The secondary core, 32 MHz Cortex-m0 + radio modem — this core runs the proprietary firmware provided by ST which implements the Bluetooth LE or Zigbee radio stack. This core's firmware is completely closed-source and we have no control over it. ST provides pre-compiled binaries in their  STM32WB Co-Processor Wireless Binaries repository. The radio stack firmware plus proprietary Firmware Upgrade Services (FUS) takes about 300Kb of space on Flash in summary.
3. 256Kb of RAM — shared among the main and the secondary core.
4. Flash memory sized at 1MB — this is the non-volatile random-access memory which stores both our firmware and the co-processor binaries.

Data layout in Flipper Zero's Flash memory

The microcontroller's Flash memory is where the code is stored. Our STM32WB55RG processor has 1MB of Flash memory. This may seem like a very small amount and that's certainly true, that is why all user data, libraries, dolphin's graphics, dictionaries and keys are stored separately on the SD card.  

Flipper Zero MCU's Flash is separated into several sections:

• The main firmware — about 670-700KB in size. All the device's functions are here along with the UI menu, protocols, various drivers, the FreeRTOS operating system etc. We're approaching the limit of our available Flash memory, so we're fighting tooth and nail for each kilobyte of compiled binary firmware.
• Little File System — this memory area is used for the LittleFS embedded filesystem. Every time the firmware is updated everything between the main firmware and the radio stack is given (allocated) to LittleFS. All system files, user settings and bluetooth pairing keys are stored here. When using Flipper Zero without an SD card, user keys will also be saved here. However we don't recommend this since without an SD card half of Flipper Zero's functions won't work. You can view the contents of the filesystem using qFlipper's file manager.
• Radio Stack — the propriatery close-sourced firmware from ST, available from the Co-Processor Wireless Binaries repository. This firmware works with the radio modem and implements the radio protocol in software on the 2.4GHz frequency. You can choose firmware that implements Bluetooth LE, ZigBee or 802.15.4 protocols. We're using stm32wb5x_BLE_Stack_light_fw.bin. Only one protocol works at any given time, so if you want to use ZigBee on Flipper Zero you will need to re-flash the radio stack losing the Bluetooth LE in the process. ST doesn't allow installing arbitrary firmware for the Radio Stack, all firmware files are signed with a digital signature which is checked during the installation by FUS.
• FUS (Firmware Upgrade Services) — a little programm that checks the radio stack's digital signature and controls it's update process. Cryptographic protection of the second core is done through FUS.

As you can see, one third of Flipper Zero's Flash memory is occupied by additional entities which are necessary for the device to work. We only have about 860KB of memory to work with. It's hard to believe that all Flipper Zero's funcions fit in such a tiny amount of storage space. Therefore, we simply don't have the space that can be used for the classic OTA update, which is why we had to invent our own Over-the-Air firmware update subsystem.

The Update Server

Flipper Zero firmware automatically compiles from source by Github CI scripts and the binaries are uploaded to the update server update.flipperzero.one. All compiled firmware versions are listed in the directory.json file, this file is used to get information about available updates. You can download all binary files of the available firmwares here update.flipperzero.one/builds/firmware/.

Similarly, all branches inside firmware repo get compiled and uploaded to the update server after every commit. You can find different folders with separate branch names there. It's convenient when the developer is working on a feature and asks users to test their code.

The update package consists of several different files:

# Flipper Zero Firmware Update files

flipper-z-any-core2_firmware-0.58.1.tgz # Radio firmware bundle from ST
flipper-z-any-resources-0.58.1.tgz      # Applications resources installed on SD card
flipper-z-any-scripts-0.58.1.tgz        # Supplementary scripts

# Main Firmware
flipper-z-f7-full-0.58.1.bin            # Image in binary format
flipper-z-f7-full-0.58.1.dfu            # Image in dfu format
flipper-z-f7-firmware-0.58.1.elf        # Image in elf format (can be used for debug)
flipper-z-f7-full-0.58.1.json           # Metadata manifest in json format

# Updater tiny firmware
flipper-z-f7-updater-0.58.1.bin         # Image in binary format
flipper-z-f7-updater-0.58.1.dfu         # Image in dfu format
flipper-z-f7-updater-0.58.1.elf         # Image in elf format (can be used for debug)
flipper-z-f7-updater-0.58.1.json        # Metadata manifest in json 

flipper-z-f7-update-0.58.1.tgz          # Full OTA package: contains updater image, main firmware, radio firmware, resources and update manifest (the only thing you need to update your flipper)

In addition to the firmware itself, the update package contains the radio stack with which this firmware version is compatible, databases for the SD card, tiny updater firmware, the current version of build and debug scripts, as well as metadata for the update programs.

Firmware Release Cycle

Flipper Zero firmware can be updated through the Flipper Mobile App and qFlipper desktop app. You can select one of the three firmware update channels in the settings: Dev, RC (Release Candidate) and Release.

The difference between firmware releases:

• Dev — the current development ongoing build. All the features from other branches are merged into dev when work on them is finished.  This version of firmware is compiled for every new commit, sometimes several times per day. Dev contains all the latest features, it's bleeding edge. But be aware that it may be unstable, freeze, corrupt your data, or not work at all.
• RC (Release Candidate) — the release version that is submitted for validation testing to the QA department. If bugs are found during the testing phase, the version is amended and a new RC is released. If the release candidate successfully passes all the tests, it becomes the release version without further changes.
• Release — the final and stable version of the firmware, which has gone through testing and is recommended for general use.

You can select the update channel in the updater settings:

We recommend installing the Release version for everyday usage of Flipper Zero. Choose the Dev and RC channels if you are a developer, or if want to test new features, find bugs, and debug them. It would help if you know how to collect debug logs, are good with git, and know how to read the firmware commits.

Old Firmware Update Process

Until recently, the only way to update firmware on Flipper Zero was by USB cable, computer and the qFlipper desktop app. This process consists of several steps, during which Flipper is rebooted several times and reconnected to the computer in different modes as different devices. After each reboot, Flipper disconnects at the logical level and is rediscovered by the computer and qFlipper over and over again.

Step 1 — Downloading backup to PC

In the first step, Flipper connects to qFlipper in COM Port mode and downloads all data from LittleFS — user settings and Bluetooth pairing key files, because all flash memory will be erased in the next steps and these files will be lost. After completing this step, Flipper reboots to DFU mode.

Step 2 (Optional) — Updating Radio Stack

Radio stack updates are released by ST. It is usually updated every few months. qFlipper checks the version of the installed Radio Stack on the Flipper, and if there is an update, it installs the new version. So this process happens quite rarely, relative to our update releases. The Radio Stack update is controlled by the FUS, so we don't have much power over the process.

Step 3 — Installing Main Firmware

The main firmware update is also installed in DFU mode. There are special system flags in memory that may be set to incorrect values after a radio stack update, they are called option bytes. If a radio stack upgrade has been performed, option bytes will be checked and overwritten if necessary.

Step 4 — Installing Databases on SD card

After the main firmware was installed, Flipper reboots to basic mode again and connects as a COM Port. It starts uploading databases to the SD card. The contents of the databases can be viewed in this repository: flipperzero-firmware/assets/resources/. The version of the databases is pinned to the firmware version and is located in the same folder on the update server. The archive with the databases is called flipper-z-any-resources-X.XX.X.tgz

Step 5 — Restoring the backup

The backup made in step 1 is loaded into the LittleFS area. User settings will not be applied until the final reboot.

Step 6 — Final reboot

After restoring the backup, the last reboot is performed and user settings are applied. In total, Flipper can reboot about 5 times during the entire update process and reconnects to PC over and over again as a different device. Sick!🤯

Flipper Zero USB Connection Modes

To understand the update process, it is important to distinguish between the modes that Flipper Zero can be in when connected to a computer:

• COM Port — basic USB serial device
• DFU mode— update & recover mode

In the process of updating, Flipper switches between these modes several times. In the pictures above, describing the old update process, the green arrow shows when COM Port mode is used and the red one shows when it's in DFU mode.

Normal mode — Serial Port

In this mode, Flipper Zero connects to the PC as a COM Port, while our firmware is running. The code responsible for the operation of CDC Serial can be found in the furi_hal_usb_cdc sources. Flipper in this mode has USB Product ID: 0x5740 and Vendor ID: 0x0483. These are ST's default serial port IDs, and many other devices have the same USB IDs. Maybe we'll get our own Vendor ID from USB.org in the future so that Flipper Zero won't interfere with other devices. But we are not sure if the $5,000/year price tag for a custom Vendor ID is really worth it. What do you think?

In this mode, all the functions of the device are operational, and most importantly, there is access to the SD card because our firmware is running. Therefore, databases can be loaded to the SD card, and all operations with files during an update occur in this mode.

DFU Mode

In DFU mode, the microcontroller's built-in bootloader is activated and Flipper is connected to the PC as a DFU device. The bootloader code is located outside the main flash memory zone and is protected from writing or erasing. It cannot be damaged when updating the firmware, the disadvantage of this is that we do not have the opportunity to modify it. In DFU mode, the Flipper has Product ID: 0xDF11, just like many other devices in this mode. There is no way to understand from the properties of the USB DFU device that it is actually Flipper Zero, because in this mode it doesn't differ in any way from other devices based on ST chips.

DFU mode is activated automatically when the firmware is updating, but it can also be activated manually, see Reboot modes. If Flipper's firmware is damaged, DFU mode can also be activated, but the dolphin image will not be displayed on the screen: How to restore a bricked Flipper Zero.

Additionally, DFU mode is complicated by the fact that on Windows you need to install drivers for it 🤮. And although no drivers are actually needed, Windows prevents programs from accessing the device until any driver is installed for it. On Windows qFlipper's setup wizard installs this DFU driver. This is where the most problems arise — we have made a separate Debug DFU Mode on Windows instruction. Everything would be much easier if ST added a USB OS Feature Descriptor to the built-in hardware DFU bootloader code, telling Windows that the device supports the standard WinUSB driver, then there would be no need to install the driver.

In DFU mode, the radio stack and the main Flipper Zero firmware are updated, as well as restored in case of firmware damage. From the very beginning of the Flipper Zero development, we have been looking for a way to update the firmware without switching to DFU, and finally, this work is finished!

The NEW Updating System 🎉️

Since we have almost no free space on Flash memory, the only possibility for OTA update in our case is to download the update files to the SD card and then install updates from there. We have made a separate tiny firmware that gets uploaded to RAM, runs directly from there and does not depend on Flash memory data to govern the update process. In fact, this is the same firmware of ours, only cut down so as to fit entirely in the RAM. All functions are removed from it except for the update feature, SD card drivers, screen drivers, etc.

Now the update procedure looks much simpler for the user: files are uploaded to the Flipper and then the magic happens — Flipper updates itself completely offline.

Step 1 — Uploading update package to the SD card

During the first step, the full update bundle packed into flipper-z-f7-update-0.XX.X.tgz archive is downloaded by the update application (qFlipper or Mobile App) from the update server and unpacked locally in the application. Then the contents of this file are transferred via Bluetooth LE or USB to Flipper's SD card.
The Bluetooth LE protocol is very slow compared to regular Bluetooth, so uploading a ~650KB update file takes about 2-3 minutes, which is quite acceptable in our opinion.

Step 2 — The Magic (Flipper updating itself autonomously)

When the update package is uploaded to the SD card, the updater sends an UpdateRequest command to the Flipper and the magic begins!

Flipper reboots and loads a tiny updater firmware into RAM, it is located in the file flipper-z-f7-updater-X.XX.X.bin In fact, this is the usual Flipper firmware but it's cut down as much as possible in terms of functions. Everything is removed from it, except for the necessary drivers and update functions. It is so small that it fits entirely in RAM. And this means that the firmware on the Flash memory is not active and the updater can overwrite data on the entire Flash memory without fear of breaking something.

Updater performs all the same steps as the old update process, the only difference being it happens completely locally — it updates the radio stack if necessary, installs new firmware, installs databases, uploads files to LittleFS, etc. In this approach, it's Flipper that performs all the steps within itself so it no longer depends on external connections and programs.

OTA Update Live Demo

This is what the new update process through a mobile application looks like. In total, it takes about 2-3 minutes, which, in our opinion, is a very good result.

New Process vs Old One

The new update process is more reliable than the old one because all the update steps are controlled by our firmware and not by the user's PC. Due to the fact that users' computers have different operating systems, drivers, and installed programs, unexpected problems could often come up during the update. Now there's a lower chance of problems occurring. But, the main benefit of this is you can now update the firmware through a mobile application! Hooray 🤩!

Since the new update process is still in beta it may have bugs 🐞, we ask you to report them: How to report bug in Mobile App

Shipping status

You can check all the shipping news on ship.flipp.dev, where we publish frequent updates daily.

Follow us

@flipper_zero

Flipper Discord

@flipperzero