unleashed-firmware Documentation

Technical Documentation: DarkFlippers/unleashed-firmware

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`ReadMe.md`) Copy Section

text Copy

</a>

Flipper Zero Unleashed Firmware

This firmware is a fork of the original (OFW) version of flipperdevices/flipperzero-firmware and represents the most stable custom build, incorporating new features and improvements to the original components while remaining fully compatible with the API and applications of the original firmware.

[!WARNING]
This software is intended solely for experimental purposes and is not meant for any illegal activities.
We do not condone unlawful behavior and strongly encourage you to use it only within the bounds of the law.

This project is developed independently and is not affiliated with Flipper Devices.

Also be aware, DarkFlippers/unleashed-firmware is the only official page of the project, there is no paid, premium or closed source versions and if someone contacts you and say they are from our team and try to offer something like that - they are scammers, block that user ASAP

🚀 Usage Copy Chapter

Before getting started:

• Review the Official Documentation: docs.flipper.net

• Installation Guide & Version Info:
  How to install the firmware by following the Installation Guide and check the version information (e, , c)

• FAQ:
  Find answers to common questions in the FAQ

• Web Installer:
  -> Unleashed FW Web Installer

📦 Releases Copy Chapter

Release builds (stable) Copy Section

• Telegram: t.me/unleashed_fw
• GitHub Releases

Dev builds (unstable) Copy Section

[!NOTE]
Built automatically from dev branch

• Web site: dev.unleashedflip.com
• Telegram: t.me/kotnehleb

🧰 Companion App & Web Tools Copy Chapter

• qUnleashed — app for mobile and PC:
  Companion app to manage your Flipper from your phone or computer — DarkFlippers/qUnleashed

• Sub-GHz & Coordinates Map:
  Online map to view your Sub-GHz wardriving files, and any other files with coordinates in them — map.unleashedflip.com

• Wi-Fi Wardriving Map:
  Combine and display multiple WiGLE-formatted captures from ESP32 Marauder and others — wdmap.unleashedflip.com

• ESP32 Web Flasher:
  Easy to use flasher for popular ESP32 modules, fully in your browser — espflasher.unleashedflip.com

🆕 What's New Copy Chapter

Sub‑GHz Library & HAL

• Many new protocols added
• Regional TX restrictions removed
• Extra Sub-GHz frequencies added
• Frequency range can be extended in settings file (warning: It can damage Flipper's hardware)
• Many rolling code protocols now have the ability to save & send captured signals
• FAAC SLH (Spa) & BFT Mitto (keeloq secure with seed) manual creation
• External CC1101 module support (by quen0n)

Sub‑GHz Main App

• Save last used settings (by derskythe)
• New frequency analyzer (by ClusterM)
• Press OK in frequency analyzer to use detected frequency in Read modes (by derskythe)
• Long press OK button in Sub-GHz Frequency analyzer to switch to Read menu (by derskythe)
• New option to use timestamps + protocol name when you saving file, instead of random name or timestamp only - Enable in Radio Settings -> Protocol Names = ON
• Read mode UI improvements (shows time when signal was received) (by @wosk)
• External CC1101 module support (Hardware SPI used)
• External CC1101 module amplifier control (or LED control) support (enabled by default)
• Hold right in received signal list to delete selected signal
• Custom buttons for Keeloq / Alutech AT4N / Nice Flor S / Somfy Telis / Security+ 2.0 / CAME Atomo - now you can use arrow buttons to send signal with different button code
• Add manually menu extended with new protocols
• FAAC SLH, BFT Mitto / Somfy Telis / Nice Flor S / CAME Atomo, etc. manual creation with programming new remote into receiver (use button 0xF for BFT Mitto, 0x8 (Prog) on Somfy Telis, (right arrow button for other protocols))
• Debug mode counter increase settings (+1 → +5, +10, default: +1)
• Debug PIN output settings for protocol development
• Ignore options - Alarms: Hollarm, GangQi | ReversRB2: Revers RB-2(M) protocol | Sensors: Magellan, Honeywell Sec, Honeywell WDB (doorbells), Legrand (doorbells), Doorbell32 (doorbells), KeyFinder, KeyFinder2 (key finder fobs), Feron (RGB lights) | NiceFlorS: Nice Flor-S protocol

Sub‑GHz Apps (by Unleashed Team)

• Sub-GHz Bruteforce - static code brute-force plugin
• Time delay (between signals) setting (hold Up in main screen (says Up to Save)) + configure repeats in protocols list by pressing right button on selected protocol
• Load your own file and select bytes you want to bruteforce or use preconfigured options in protocols list
• Sub-GHz Remote - remote control for 5 sub-ghz files | bind one file for each button
• use the built-in constructor or make config file by following this instruction

Infrared (IR)

• Recompiled IR TV Universal Remote for ALL buttons
• Universal remotes for Projectors, Fans, A/Cs and Audio(soundbars, etc.) → Also always updated and verified by our team
• Infrared → RCA Protocol
• Infrared → External IR modules support (with autodetect by OFW)

NFC/RFID/iButton

• LFRFID and iButton Fuzzer plugins
• Add DEZ 8 display form for EM4100 (by @korden32)
• Extra Mifare Classic keys in system dict
• EMV Protocol + Public data parser (by @Leptopt1los and @wosk)
• NFC Add manually → Mifare Classic with custom UID
• NFC parsers: Umarsh, Zolotaya Korona, Kazan, Metromoney, Moscow Social Card, Troika (reworked) and many others (by @Leptopt1los and @assasinfil)

Quality of Life & Other Features

• Customizable Flipper name Update! Now can be changed in Settings → Desktop (by @xMasterX and @Willy-JL)
• Text Input UI element → Cursor feature (by @Willy-JL)
• Byte Input Mini editor → Press UP multiple times until the nibble editor appears (by @gid9798)
• Clock on Desktop Settings -> Desktop -> Show Clock (by @gid9798)
• Battery percentage display with different styles Settings -> Desktop -> Battery View
• More games in Dummy Mode → click or hold any of arrow buttons
• Lock device with pin (or regular lock if pin not set) by holding UP button on main screen (by an4tur0r)
• BadKB (BadUSB) (by Willy-JL, ClaraCrazy, XFW contributors) - (Integrated into BadUSB app now!) - (aka BadUSB via Bluetooth)
• BadUSB → Keyboard layouts (by rien > dummy-decoy)
• Custom community plugins and games added + all known working apps can be downloaded in extra pack in every release
• Other small fixes and changes throughout
• See other changes in readme below

Also check the changelog in releases for latest updates!

Current modified and new Sub-GHz protocols list: Copy Section

Full list of supported protocols and their frequencies/modulations (to use in Read mode)

Thanks to Official team (to their SubGHz Developer, Skorp) for implementing support (decoder + encoder / or decode only) for most protocols in OFW.

And thanks to our contributors who took part in SubGHz improvements and making of new features:

@RocketGod-git, @zero-mega, @ashphx, @pkooiman, Vitaly, Carlos, @li0ard, @mishamyte, d82k, Steffen (bastelbudenbuben de), @assasinfil, @gid9798

❤️ Please support development of the project Copy Chapter

The majority of this project is developed and maintained by me, @xMasterX.
Our team is small and the guys are working on this project as much as they can solely based on the enthusiasm they have for this project and the community.

• @mishamyte - NFC, RFID, SubGHz and chats moderation
• @quen0n - Hardware, SubGHz and chats moderation
• @Drone1950 - Reverse Engineering, telegram bot and chats moderation
• @HackcatDev - Support and chats moderation
• @Leptopt1los - NFC, RFID, Plugins, chat moderation and many other things
• @gid9798 - SubGHz, Plugins, many other things - currently offline :(
• @assasinfil - SubGHz protocols, NFC parsers, chat moderation
• @Svaarich - UI design and animations
• @amec0e - Infrared assets
• Community moderators in Telegram, Discord, and Reddit
• And of course our GitHub community. Your PRs are a very important part of this firmware and open-source development.

The amount of work done on this project is huge and we need your support, no matter how large or small. Even if you just say, "Thank you Unleashed firmware developers!" somewhere. Doing so will help us continue our work and will help drive us to make the firmware better every time.
Also, regarding our releases, every build has and always will be free and open-source. There will be no paywall releases or closed-source apps within the firmware. As long as I am working on this project it will never happen.
You can support us by using links or addresses below:

📱 Community Apps Copy Chapter

Enhance your Flipper Zero with apps and plugins created by the community:

• Extra Plugins & Packs:
  Check out the latest extra plugins and plugin packs (Extra Pack and Base Pack) on GitHub.

• Source Code & Full List:
  Find the complete list and source code at xMasterX/all-the-plugins.

• Official Apps Catalog:
  Browse the official Flipper Zero Apps Catalog on the web or via the mobile app.

📁 Where I can find IR, Sub-GHz, ... files, DBs, and other stuff? Copy Chapter

• UberGuidoZ Playground - Large collection of files - Github
• Awesome Flipper Zero - Github
• IRDB - Infrared remotes database - Github

📘 Instructions Copy Chapter

![Tools Icon Badge] Firmware & main Apps feature Copy Section

• System: How to change Flipper name
• BadUSB: How to add new keyboard layouts
• Infrared: How to make captures to add them into Universal IR remotes

![SubGhz Icon Badge] Sub-GHz Copy Section

• Full list of supported protocols and their frequencies/modulations (to use in Read mode)
• How to use Flipper as rolling code remote (Doorhan, Nice FlorS, BFT Mitto, Somfy Telis, Aprimatic, AN-Motors, etc..)
• Experimental rolling code counter modes (avoid desync)
• External Radio: How to connect CC1101 module
• Transmission is blocked? How to extend Sub-GHz frequency range
• How to add extra Sub-GHz frequencies
• Configure Sub-GHz Remote App ⚠️ Not recommended, please use embedded configurator

![Plugins Icon Badge] Plugins Copy Section

• TOTP (Authenticator): config description
• Barcode Generator: How to use
• Multi Converter: How to use
• WAV Player: sample files & how to convert
• Sub-GHz playlist: generator script

![GPIO Icon Badge] GPIO - Plugins that works with external hardware Copy Section

• Unitemp - Temperature sensors reader: How to use & supported sensors
• [NMEA] GPS: How to use
• i2c Tools How to use
• [NRF24] plugins: How to use
• [WiFi] Scanner: How to use | Web Flasher
• [ESP8266] Deauther: How to use | Web Flasher
• [ESP32] WiFi Marauder: How to use _{docs by UberGuidoZ} | Marauder repo
• [ESP32-CAM] Camera Suite: How to use
• How to Upload .bin to ESP32/ESP8266: Windows | FAP "ESP flasher"
• [GPIO] SentrySafe plugin: How to use

👨‍💻 Firmware & Development Copy Chapter

• Developer Documentation - developer.flipper.net
• How to build | Project-structure
• Build apps on Android with Termux - compile .fap files on your phone, no PC needed _{by @CamsShaft}
• CLion IDE - How to setup workspace for flipper firmware development by Savely Krasovsky
• "Hello world!" - plugin tutorial English _{by DroomOne} | Russian _{by Pavel Yakovlev}
• How to write your own app.

Project structure Copy Section

• applications - Applications and services used in firmware
• assets - Assets used by applications and services
• furi - Furi Core: OS-level primitives and helpers
• debug - Debug tool: GDB-plugins, SVD-file and etc
• documentation - Documentation generation system configs and input files
• firmware - Firmware source code
• lib - Our and 3rd party libraries, drivers and etc...
• site_scons - Build helpers
• scripts - Supplementary scripts and python libraries home

Also, pay attention to the ReadMe.md files inside those directories.

🔗 Links Copy Chapter

• Unleashed web page: flipperunleashed.com

• Unleashed FW Web Installer: web.unleashedflip.com

• Unleashed domain used for direct .tgz update links for web updater or direct download: unleashedflip.com

• Unleashed directory json for ufbt builds: up.unleashedflip.com/directory.json

• Official Docs: docs.flipper.net

• Official Forum: forum.flipperzero.one

• Update! Official Developer Documentation developer.flipper.net

Overview (`.vscode/ReadMe.md`) Copy Section

Visual Studio Code workspace for Flipper Zero {#vscode}

Setup Copy Chapter

• To start developing with VSCode, run ./fbt vscode_dist in project root. That should only be done once
• After that, open firmware folder in VSCode: "File" > "Open folder"

For more details on fbt, see fbt docs.

Workflow Copy Chapter

Commands for building firmware are invoked through Build menu: Ctrl+Shift+B.

To attach a debugging session, first build and flash firmware, then choose your debug probe in Debug menu (Ctrl+Shift+D).

Note that you have to detach debugging session before rebuilding and re-flashing firmware.

Overview (`applications/ReadMe.md`) Copy Section

Structure

debug Copy Chapter

Applications for factory testing the Flipper.

• accessor - Wiegand server
• battery_test_app - Battery debug app
• blink_test - LED blinker
• bt_debug_app - BT test app. Requires full BT stack installed
• display_test - Various display tests & tweaks
• file_browser_test - Test UI for file picker
• keypad_test - Keypad test
• lfrfid_debug - LF RFID debug tool
• text_box_test - UI tests
• uart_echo - UART mode test
• unit_tests - Unit tests
• usb_mouse - USB HID test
• usb_test - Other USB tests
• vibro_test - Vibro test

main Copy Chapter

Applications for main Flipper menu.

• archive - Archive and file manager
• bad_usb - Bad USB application
• gpio - GPIO application: includes USART bridge and GPIO control
• ibutton - iButton application, onewire keys and more
• infrared - Infrared application, controls your IR devices
• lfrfid - LF RFID application
• nfc - NFC application, HF rfid, EMV and etc
• subghz - SubGhz application, 433 fobs and etc
• u2f - U2F Application

services Copy Chapter

Background services providing system APIs to applications.

• applications.h - Firmware application list header
• bt - BLE service and application
• cli - Console service and API
• crypto - Crypto cli tools
• desktop - Desktop service
• dialogs - Dialogs service: GUI Dialogs for your app
• dolphin - Dolphin service and supplementary apps
• gui - GUI service and API
• input - Input service
• loader - Application loader service
• notification - Notification service
• power - Power service
• rpc - RPC service and API
• storage - Storage service, internal + sdcard

settings Copy Chapter

Small applications providing configuration for basic firmware and its services.

• about - Small About application that shows flipper info
• bt_settings_app - Bluetooth options
• desktop_settings - Desktop configuration
• dolphin_passport - Dolphin passport app
• notification_settings - LCD brightness, sound volume, etc configuration
• power_settings_app - Basic power options
• storage_settings - Storage settings app
• system - System settings
• input_settings_app - Basic input options

system Copy Chapter

Utility apps not visible in other menus, plus few external apps pre-packaged with the firmware.

• hid_app - BLE & USB HID remote
• js_app - JS engine runner
• snake_game - Snake game
• storage_move_to_sd - Data migration tool for internal storage
• updater - Update service & application

Overview (`assets/ReadMe.md`) Copy Section

Firmware Assets {#firmware_assets}

Compiling Copy Chapter

./fbt icons proto dolphin_internal dolphin_blocking dolphin_ext resources

Asset naming rules Copy Chapter

Images and Animations Copy Section

NAME_VARIANT_SIZE

• NAME - mandatory - Asset name in CamelCase. [A-Za-z0-9], special symbols not allowed
• VARIANT - optional - icon variant: can relate to state or rendering conditions. Examples: active, inactive, inverted.
• SIZE - mandatory - size in px. Example square 10, 20, 24, etc. Example rectangular: 10x8, 19x5, etc.

Image names will be automatically prefixed with I_, animation names with A_.
Icons and Animations will be gathered into icon.h and icon.c.

Dolphin and Games assets Copy Section

Rules are same as for Images and Animations plus assets are grouped by level and level prepends NAME.
Good starting point: https://docs.unrealengine.com/4.27/en-US/ProductionPipelines/AssetNaming/

Important notes Copy Chapter

Don't include assets that you are not using, compiler is not going to strip unused assets.

Structure Copy Chapter

• dolphin - Dolphin game assets sources. Goes to compiled and resources folders in build directory.
• icons - Icons sources. Goes to compiled folder in build directory.
• protobuf - Protobuf sources. Goes to compiled folder in build directory.
• slideshow - One-time slideshows for desktop

Overview (`lib/ReadMe.md`) Copy Section

Structure

• app-scened-template - C++ app library
• bit_lib - library for working with bits/bytes directly
• ble_profile - BLE Profiles source code
• cmsis_core - CMSIS Core package, contain cortex-m core headers
• cxxheaderparser - C++ headers parser, used by SDK bundler
• datetime - DateTime library
• digital_signal - Digital signal library: used by NFC for software implemented protocols
• drivers - Various flipper drivers
• fatfs - FatFS file system driver
• flipper_application - Flipper application library, used for FAPs
• flipper_format - Flipper File Format library
• FreeRTOS-glue - Extra glue to hold together FreeRTOS kernel and flipper firmware
• FreeRTOS-Kernel - FreeRTOS kernel source code
• heatshrink - Heatshrink compression library
• ibutton - ibutton library, used by iButton application
• infrared - Infrared library, used by Infrared application
• lfrfid - LF-RFID library, used by LF RFID application
• libusb_stm32 - LibUSB for STM32 series MCU
• mbedtls - MbedTLS cryptography library
• microtar - MicroTAR library
• mjs - MJs, javascript engine library
• mlib - M-Lib C containers library
• music_worker - MusicWorker library for playing midi and RTTTL files
• nanopb - NanoPB library, protobuf implementation for MCU
• nfc - NFC library, used by NFC application
• one_wire - OneWire library, used by iButton application
• print - Tiny printf implementation
• digital_signal - Digital Signal library used by NFC for software implemented protocols
• pulse_reader - Pulse Reader library used by NFC for software implemented protocols
• stm32wb_cmsis - STM32WB series CMSIS headers, extends CMSIS Core
• stm32wb_copro - STM32WB Copro library: contains WPAN and radio co-processor firmware
• stm32wb_hal - STM32WB HAL library, extends STM32WB CMSIS and provides HAL
• subghz - Subghz library, used by SubGhz application
• toolbox - Toolbox library, contains various things that is used by Flipper firmware
• u8g2 - u8g2 graphics library, used by GUI subsystem
• update_util - update utilities library, used by updater

Overview (`scripts/ReadMe.md`) Copy Section

About

This folder contains supplementary scripts that automates routine actions.
Flashing scripts are based on cli version of STM32CubeProgrammer.
You will need to add STM32_Programmer_CLI to your path to use them.

Flashing empty MCU/Flipper

Always flash your device in the following sequence:

• OTP (Only on empty MCU)
• Core1 and Core2 firmware flashing
• Option Bytes

Otp flashing Copy Chapter

!!! Flashing incorrect OTP may permanently brick your device !!!

Normally OTP data generated and flashed at the factory.
In case if MCU was replaced you'll need correct OTP data to be able to use companion applications.
Use otp.py to generate and flash OTP data.
You will need exact main board revision to generate OTP data. It can be found on main PCB.
Also display type, region and etc...

!!! Flashing incorrect OTP may permanently brick your device !!!

Core1 and Core2 firmware flashing Copy Chapter

Core2 goes first, then Core1.
Never flash FUS or you will lose your job, girlfriend and keys in secure enclave.

Option Bytes Copy Chapter

!!! Setting incorrect Option Bytes may brick your MCU !!!

Defaults are mostly OK, but there are couple things that we'd like to tune.
Also, OB may be damaged, so we've made couple scripts to check and set option bytes.

!!! Setting incorrect Option Bytes may brick your MCU !!!

Checking option bytes:

ob.py check

Setting option bytes:

ob.py set

Assets delivery

Build the firmware and run in the root folder of the repo:

python scripts/storage.py -p <flipper_cli_port> send build/latest/resources /ext

Slideshow creation

Put fullscreen slideshow frames in .png format into assets/slideshow/my_show folder, named frame_xx.png, where xx is zero-padded frame number, starting with #0.

Then run

python scripts/slideshow.py -i assets/slideshow/my_show/ -o assets/slideshow/my_show/.slideshow

Upload generated .slideshow file to Flipper's internal storage and restart it.

Overview (`targets/ReadMe.md`) Copy Section

Targets

• f18 - Not Flipper Zero
• f7 - Flipper Zero
• furi_hal_include - Global Furi HAL includes, common for all targets

Overview (`assets/dolphin/ReadMe.md`) Copy Section

Dolphin assets {#dolphin_assets}

Dolphin assets are split into 3 parts:

• blocking - Essential animations that are used for blocking system notifications. They are packed to assets_dolphin_blocking.[h,c].
• internal - Internal animations that are used for idle dolphin animation. Converted to assets_dolphin_internal.[h,c].
• external - External animations that are used for idle dolphin animation. Packed to resource folder and placed on SD card.

Files

• manifest.txt - contains animations enumeration that is used for random animation selection. Starting point for Dolphin.
• meta.txt - contains data that describes how animation is drawn.
• frame_X.png - animation frame.

File manifest.txt Copy Chapter

Flipper Format File with ordered keys.

Header:

Filetype: Flipper Animation Manifest
Version: 1

• Name - name of animation. Must be exact animation directory name.
• Min butthurt, Max butthurt - range of dolphin's butthurt for this animation.
• Min level, Max level - range of dolphin's level for this animation. If 0, this animation doesn't participate in random idle animation selection and can only be selected by exact name.
• Weight - chance of this animation to be chosen at random animation selection.

Some animations can be excluded from participation in random animation selection, such as L1_NoSd_128x49.

File meta.txt Copy Chapter

Flipper Format File with ordered keys.

Header:

Filetype: Flipper Animation
Version: 1

• Width - animation width in px (<= 128)

• Height - animation height in px (<= 64)

• Passive frames - number of bitmap frames for passive animation state

• Active frames - number of bitmap frames for active animation state (can be 0)

• Frames order - order of bitmap frames where first N frames are passive and following M are active. Each X number in order refers to bitmap frame, with name frame_X.bm. This file must exist. Any X number can be repeated to refer same frame in animation.

• Active cycles - cycles to repeat of N active frames for full active period. E.g. if frames for active cycles are 6 and 7, and active cycles is 3, so full active period plays 6 7 6 7 6 7. Full period of passive + active period are called total period.

• Frame rate - number of frames to play for 1 second.

• Duration - total amount of seconds to play 1 animation.

• Active cooldown - amount of seconds (after passive mode) to pass before entering next active mode.

• Bubble slots - amount of bubble sequences.

• Any bubble sequence plays whole sequence during active mode. There can be many bubble sequences and bubbles inside it. Bubbles in 1 bubble sequence have to reside in 1 slot. Bubbles order in 1 bubble sequence is determined by occurrence in file. As soon as frame index goes out of EndFrame index of bubble - next animation bubble is chosen. There can also be free of bubbles frames between 2 bubbles.

• Slot - number to unite bubbles for same sequence.

• X, Y - are coordinates of left top corner of bubble.

• Text - text in bubble. New line is \n

• AlignH - horizontal place of bubble corner (Left, Center, Right)

• AlignV - vertical place of bubble corner (Top, Center, Bottom)

• StartFrame, EndFrame - frame index range inside whole period to show bubble.

Understanding of frame indexes Copy Section

For example we have

Passive frames: 6
Active frames: 2
Frames order: 0 1 2 3 4 5 6 7
Active cycles: 4

Then we have indexes

passive(6)            active (2 * 4)
Real frames order:   0  1  2  3  4  5     6  7  6  7  6  7  6  7
Frames indexes:      0  1  2  3  4  5     6  7  8  9  10 11 12 13

Overview (`scripts/debug/README.md`) Copy Section

Installing udev rules Copy Chapter

On Linux, unprivileged users need to be in the dialout group to access serial ports and other USB devices.

To add your user to the dialout group, run the following command:

sudo usermod -a -G dialout $USER

To install the udev rules needed for debugging & CLI access to Flipper, run the following command:

sudo cp 41-flipper.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

Note that not all possible debug interfaces are listed the 41-flipper.rules file. If your interface is not supported out of the box, you may need to add a a rule for it. You can do so by adding a new line to the file according to udev rules syntax. Use lsusb -v to find the vendor and product IDs of your device.

Overview (`applications/examples/example_apps_assets/README.md`) Copy Section

Apps Assets folder Example {#example_app_assets}

This example shows how to use the Apps Assets folder to store data that is not part of the application itself, but is required for its operation, and that data is provided with the application.

Source code Copy Chapter

Source code for this example can be found here.

What is the Apps Assets Folder? Copy Chapter

The Apps Assets folder is a folder where external applications unpack their assets.

The path to the current application folder is related to the appid of the app. The appid is used to identify the app in the app store and is stored in the application.fam file.
The Apps Assets folder is located only on the external storage, the SD card.

For example, if the appid of the app is snake_game, the path to the Apps Assets folder will be /ext/apps_assets/snake_game. But using raw paths is not recommended, because the path to the Apps Assets folder can change in the future. Use the /assets alias instead.

How to get the path to the Apps Assets folder? Copy Chapter

You can use /assets alias to get the path to the current application data folder. For example, if you want to open a file database.txt in the Apps Assets folder, you can use the next path: /data/database.txt. But this way is not recommended, because even the /assets alias can change in the future.

We recommend to use the APP_ASSETS_PATH macro to get the path to the Apps Assets folder. For example, if you want to open a file database.txt in the Apps Assets folder, you can use the next path: APP_ASSETS_PATH("database.txt").

What is the difference between the Apps Assets folder and the Apps Data folder? Copy Chapter

The Apps Assets folder is used to store the data provided with the application. For example, if you want to create a game, you can store game levels (content data) in the Apps Assets folder.

The Apps Data folder is used to store data generated by the application. For example, if you want to create a game, you can save the progress of the game (user-generated data) in the Apps Data folder.

How to provide the data with the app? Copy Chapter

To provide data with an application, you need to create a folder inside your application folder (eg "files") and place the data in it. After that, you need to add fap_file_assets="files" to your application.fam file.

For example, if you want to provide game levels with the application, you need to create a "levels" folder inside the "files" folder and put the game levels in it. After that, you need to add fap_file_assets="files" to your application.fam file. The final application folder structure will look like this:

snake_game
├── application.fam
├── snake_game.c
└── files
    └── levels
        ├── level1.txt
        ├── level2.txt
        └── level3.txt

When app is launched, the files folder will be unpacked to the Apps Assets folder. The final structure of the Apps Assets folder will look like this:

/assets
├── .assets.signature
└── levels
    ├── level1.txt
    ├── level2.txt
    └── level3.txt

When will the data be unpacked? Copy Chapter

The data is unpacked when the application starts, if the application is launched for the first time, or if the data within the application is updated.

When an application is compiled, the contents of the "files" folder are hashed and stored within the application itself. When the application starts, this hash is compared to the hash stored in the .assets.signature file. If the hashes differ or the .assets.signature file does not exist, the application folder is deleted and the new data is unpacked.

Overview (`applications/examples/example_apps_data/README.md`) Copy Section

Apps Data folder Example {#example_app_data}

This example demonstrates how to utilize the Apps Data folder to store data that is not part of the app itself, such as user data, configuration files, and so forth.

Source code Copy Chapter

Source code for this example can be found here.

What is the Apps Data Folder? Copy Chapter

The Apps Data folder is a folder used to store data for external apps that are not part of the main firmware.

The path to the current application folder is related to the appid of the app. The appid is used to identify the app in the app store and is stored in the application.fam file.
The Apps Data folder is located only on the external storage, the SD card.

For example, if the appid of the app is snake_game, the path to the Apps Data folder will be /ext/apps_data/snake_game. But using raw paths is not recommended, because the path to the Apps Data folder can change in the future. Use the /data alias instead.

How to get the path to the Apps Data folder? Copy Chapter

You can use /data alias to get the path to the current application data folder. For example, if you want to open a file config.txt in the Apps Data folder, you can use the next path: /data/config.txt. But this way is not recommended, because even the /data alias can change in the future.

We recommend to use the APP_DATA_PATH macro to get the path to the Apps Data folder. For example, if you want to open a file config.txt in the Apps Data folder, you can use the next path: APP_DATA_PATH("config.txt").

What is the difference between the Apps Assets folder and the Apps Data folder? Copy Chapter

The Apps Assets folder is used to store the data provided with the application. For example, if you want to create a game, you can store game levels (content data) in the Apps Assets folder.

The Apps Data folder is used to store data generated by the application. For example, if you want to create a game, you can save the progress of the game (user-generated data) in the Apps Data folder.

Overview (`applications/examples/example_canvas_buffer/README.md`) Copy Section

Canvas Buffer Example

Demonstrates canvas_get_buffer() — direct read and write access to the raw
canvas framebuffer from a regular external application (FAP).

A wireframe cube flies across the screen, bouncing off the screen borders and
off the text. Its spin is pure collision physics: every impact applies a torque
(r × F for each vertex that hit), the inertia is slightly different per axis,
and the spin axis slowly precesses like an asymmetric top — so the tumble stays
truly three-dimensional instead of settling into a flat, 2D-looking rotation. The text is rendered by the regular canvas API
(canvas_draw_str()), and the collision works by reading the glyph pixels back
from the framebuffer — which is exactly what makes this example impossible to
reproduce without canvas_get_buffer().

What it shows Copy Chapter

• canvas_get_buffer() — pointer to the live framebuffer of the canvas.
• Buffer layout: one byte covers a vertical 8-pixel strip;
  byte = (y / 8) * width + x, bit = y % 8, LSB on top.
• Write path: Bresenham line rasterizer that puts pixels straight into the
  buffer, bypassing the per-primitive canvas calls.
• Read path: per-pixel collision test against glyphs that the canvas API
  itself rendered a moment earlier in the same frame.

Why this cannot be done without buffer access Copy Chapter

The public canvas API is strictly write-only: there is no canvas_get_pixel().
Fonts are rasterized inside u8g2, which is private to the firmware — an
external app cannot obtain glyph bitmaps any other way. So "bounce off the
letters" requires reading the framebuffer, and the only sanctioned way to read
it is canvas_get_buffer().

History: how full-framebuffer rendering was done before this API Copy Chapter

Approaches used in real projects over the years, in the order they were tried.
FPS numbers are the author's measurements of full-screen animation on real
hardware.

1. Canvas primitives only. Often simply not enough: no pixel read-back,
   and full-screen software rendering through per-primitive calls is slow.

2. Own framebuffer + canvas_draw_xbm(). Keep a private buffer in XBM
   layout and blit it every frame. Works, fully official, but the bitmap path
   tops out at about 8 FPS for full-screen animation. This method (along
   with an even older one) is preserved in the history of
   FlipperCatacombs —
   the author's oldest game.

3. gui_add_framebuffer_callback(). Writing into the framebuffer from the
   GUI commit callback. Fast — 67+ FPS measured — but fundamentally wrong:
   the hook is a post-send capture intended for RPC screen streaming. Inside
   canvas_commit() it fires after u8g2_SendBuffer(), so writes are one
   frame late and get wiped by canvas_reset() on the next redraw. Worse, the
   app never owns GUI focus: input events are not captured, and view ports and
   the desktop keep fighting for the screen. The historical implementation
   lives in ardulib. See
   the anti-example below.

4. gui_direct_draw_acquire() / gui_direct_draw_release(). Also part of
   the same historical code. Solves the takeover problem legitimately — the GUI
   suspends view-port composition and hands the canvas over, input is taken via
   the RECORD_INPUT_EVENTS pubsub — but it still exposes only the write-only
   drawing primitives, not the raw buffer.

5. u8g2_GetBufferPtr(&canvas->fb) hack. Reaching into canvas internals
   through the u8g2 struct. It compiled locally, but a FAP release was
   impossible: the API check rejects the symbol — it is only reachable when
   building in-tree with ./fbt. Preserved in
   ardulib as the
   semi-final variant that immediately preceded the public API.

6. canvas_get_buffer() / canvas_get_buffer_size() public API — this
   example. Full-speed read/write access from a regular FAP, with normal
   ViewPort input handling and compositing. The newest project built on top of
   it is Flipcraft.

Historical anti-example (kept for reference — do not use) Copy Section

void rt_framebuffer_commit_callback(
    uint8_t* data,
    size_t size,
    CanvasOrientation orientation,
    void* context) {
    ArduboyRuntimeState* state = (ArduboyRuntimeState*)context;
    if(!state || !data) return;
    if(size < RuntimeBufferSize) return;
    (void)orientation;

    const uint8_t* src = state->screen_buffer;
    bool inverted = __atomic_load_n((bool*)&state->screen_inverted, __ATOMIC_ACQUIRE);

    for(size_t i = 0; i < RuntimeBufferSize; i++) {
        if(inverted) {
            data[i] = src[i];
        } else {
            data[i] = (uint8_t)(src[i] ^ 0xFF);
        }
    }

    if(state->pending_clear) {
        memset(state->screen_buffer, 0x00, RuntimeBufferSize);
        state->pending_clear = false;
    }
}

This shipped in early Arduboy runtime builds and reached 67+ FPS on the GUI
internals of that era. On current firmware it cannot work correctly: the
callback runs after the frame has already been sent to the display, the app
receives no input, and view ports break. It is documented here as historically
working but not correct.

Building Copy Chapter

./fbt fap_example_canvas_buffer

Overview (`applications/examples/example_date_time_input/ReadMe.md`) Copy Section

Date/Time Input {#example_date_time_input}

Simple view that allows the user to adjust a date and/or time.

Source code Copy Chapter

Source code for this example can be found here.

General principle Copy Chapter

Callbacks can be defined for every time a value is edited (useful for application-specific bounds checking or validation) and for when the user is done editing (back button is pressed). The provided DateTime object is used both as the initial value and as the place where the result is stored.

The fields which the user is allowed to edit can be defined using date_time_input_set_editable_fields(). Disabled fields are shown but aren't able to be selected and don't have an outer box. If all fields are disabled, the view is read-only and no cursor will be shown.

Overview (`applications/examples/example_images/ReadMe.md`) Copy Section

Application icons {#example_app_images}

Source code Copy Chapter

Source code for this example can be found here.

General principle Copy Chapter

To use icons, do the following:

• Add a line to the application manifest: fap_icon_assets="folder", where folder points to the folder where your icons are located
• Add #include "application_id_icons.h" to the application code, where application_id is the appid from the manifest
• Every icon in the folder will be available as a I_icon_name variable, where icon_name is the name of the icon file without the extension

Example Copy Chapter

We have an application with the following manifest:

App(
    appid="example_images",
    ...
    fap_icon_assets="images",
)

So the icons are in the images folder and will be available in the generated example_images_icons.h file.

The example code is located in example_images_main.c and contains the following line:

#include "example_images_icons.h"

Image dolphin_71x25.png is available as I_dolphin_71x25.

Overview (`applications/examples/example_number_input/ReadMe.md`) Copy Section

Number Input {#example_number_input}

Simple keyboard that limits user inputs to a full number (integer). Useful to enforce correct entries without the need for intense validations after a user input.

Source code Copy Chapter

Source code for this example can be found here.

General principle Copy Chapter

Definition of min/max values is required. Numbers are of type int32_t. If negative numbers are allowed within min - max, an additional button is displayed to switch the sign between + and -.

It is also possible to define a header text, as shown in this example app with the 3 different input options.

Overview (`applications/examples/example_thermo/README.md`) Copy Section

1-Wire Thermometer {#example_thermo}

This example application demonstrates the use of the 1-Wire library with a DS18B20 thermometer.
It also covers basic GUI, input handling, threads and localisation.

Source code Copy Chapter

Source code for this example can be found here.

Electrical connections Copy Chapter

Before launching the application, connect the sensor to Flipper's external GPIO according to the table below:

NOTE 1: GND is also available on pins 8 and 11.

NOTE 2: For any other pin than 17, connect an external 4.7k pull-up resistor to pin 9.

Launching the application Copy Chapter

In order to launch this demo, follow the steps below:

1. Make sure your Flipper has an SD card installed.
2. Connect your Flipper to the computer via a USB cable.
3. Run ./fbt launch APPSRC=example_thermo in your terminal emulator of choice.

Changing the data pin Copy Chapter

It is possible to use other GPIO pin as a 1-Wire data pin. In order to change it, set the THERMO_GPIO_PIN macro to any of the options listed below:

/* Possible GPIO pin choices:
 - gpio_ext_pc0
 - gpio_ext_pc1
 - gpio_ext_pc3
 - gpio_ext_pb2
 - gpio_ext_pb3
 - gpio_ext_pa4
 - gpio_ext_pa6
 - gpio_ext_pa7
 - gpio_ibutton
*/

#define THERMO_GPIO_PIN (gpio_ibutton)

Do not forget about the external pull-up resistor as these pins do not have one built-in.

With the changes been made, recompile and launch the application again.
The on-screen text should reflect it by asking to connect the thermometer to another pin.

Overview (`applications/system/find_my_flipper/README.md`) Copy Section

FindMy Flipper - FindMy SmartTag Emulator

This app extends the functionality of the FlipperZero's bluetooth capabilities, enabling it to act as an Apple AirTag or Samsung SmartTag, or even both simultaneously. It utilizes the FlipperZero's BLE beacon to broadcast a SmartTag signal to be picked up by the FindMy Network. I made this to serve as a versatile tool for tracking purposes, offering the ability to clone existing tags, generate OpenHaystack key pairs for integration with Apple's FindMy network, and tune the device's beacon broadcast settings.

Features Copy Chapter

1. Tag Emulation: Clone your existing Apple AirTag or Samsung SmartTag to the FlipperZero, or generate a key pair for use with the FindMy network without owning an actual AirTag.
2. Customization: Users can adjust the interval between beacon broadcasts and modify the transmit power to suit their needs, optimizing for both visibility and battery life.
3. Efficient Background Operation: The app is optimized to run in the background, ensuring that your FlipperZero can still be tracked with minimal battery usage and without stopping normal use.

Usage Guide Copy Chapter

Step 1: Installation Copy Section

• Option A: Use the released/precompiled firmware appropriate (FAP) for your device.
• Option B: Build the firmware yourself using fbt/ufbt.
• Both Installation options require you to be running a dev build of firmware. When release gets access to the extra BLE beacon this will change, thank you!
• All firmware should now work with main branch, including icons

Step 2: Obtaining SmartTag Data Copy Section

Option A: Cloning Existing Tag (Preferred and allows you to track without additional setup)

1. Pair a Tag: First, pair an AirTag or Samsung SmartTag with your device.
2. Enter 'Lost' Mode: Keep the tag away from the device it's registered to for approximately 15 minutes.
3. Download nrfConnect: Install nrfConnect from the Google Play Store. (Apple version doesn't reveal the needed Raw data, looking for a workaround)
4. Filter and Scan:
   • Open the app, click on filters, and exclude all except for the brand of your tag (Apple/Samsung).
   • Adjust the RSSI to the lowest setting (-40 dBm).
   • Initiate a scan. Wait for your SmartTag to appear as a "FindMy" device.
5. Capture Data: Click Raw or View Raw to capture your payload and note your tag's MAC Address. Immediately remove the tag's battery to prevent key/MAC rotation.
6. Enter Data in FlipperZero App: Input the captured payload and MAC Address into the FlipperZero app.

Option B: Open Haystack Method

1. Generate a Tag: Download the generate_keys.py file and execute it in your terminal. (You will need cryptography python3 -m pip install cryptography)
2. Follow Prompts: During execution, you'll be prompted for inputs. By the end, you'll obtain a Private Key, Public Key, Payload, and MAC Address.
   • Private Key is necessary to receive location reports from Apple.
   • MAC Address should be registered in the FlipperZero app:
     1. Open the app and navigate to the config menu.
     2. Choose "register tag" and enter the MAC Address when prompted.
     3. A payload dialog will appear next. Enter your Payload here.
     4. Click save.
3. Configuration Completion: With this setup, your device is ready for Open Haystack. Proceed with the specific steps for Open Haystack or MaclessHaystack based on your setup.
   • Don't Own a Mac: https://github.com/dchristl/macless-haystack or https://github.com/Chapoly1305/FindMy
   • Own a Mac: https://github.com/seemoo-lab/openhaystack

To use OpenHayStack for tracking, you must use MacOS lower than version 14 (Mail Plug-in Incompetiablity of MacOS 14+ seemoo-lab/openhaystack#224). If you do own a device, I believe a convertor script can be provided without much of effort. If you do not own a Mac device or the system has been upgraded to 14 and beyond. The alternative solution includes,

https://github.com/dchristl/macless-haystack (recommended in README)
https://github.com/Chapoly1305/FindMy (a project uses python and docker to provide location lookup as a backend service)

Setting Up on Mac with OpenHayStack (OHS) App -- If you own a Mac instructions Copy Chapter

Follow these steps to get everything working on a Mac using the latest version of the OpenHayStack app.
Thanks to Wr3nch for the help

Step 1: Create a New Device Copy Section

• Start by creating a new device in the OpenHayStack app, but do not deploy it immediately after creation.

Step 2: Export Configuration Copy Section

• Choose to EXPORT the configuration by selecting "all accessories as file." To simplify, ensure you only have one entry in the list before exporting.
• It is crucial that the export format is in JSON.

Step 3: Modify the JSON File Copy Section

Open the exported JSON file in a text editor and make the following changes:

• Left OHS, Right keys from my generate_keys.py script:
  • symmetricKey should be set to the Hashed adv key.
  • privateKey should be replaced with your Private Key.
  • oldestRelevantSymmetricKey should also use the Hashed adv key.
• Additionally, update the following attributes to true:
  • "isDeployed": true
  • "isActive": true

Step 4: Re-import the Configuration Copy Section

• After saving your changes to the JSON file, re-import it back into OpenHayStack.

Step 5: Adjust Settings in OHS App Copy Section

• In the OpenHayStack Mac App, navigate to the top bar and change the time setting from 1 Day to 30min.
• Give it some time to process and apply the new settings.

By following these steps, you should have your device set up and ready to go with OpenHayStack on a Mac.

Step 3: Configuration on the FlipperZero Copy Section

• Upon launching the app, open the config menu and either click Import Tag From File or Register Tag Manually. Put your generated .keys file onto the FlipperZero SD card inside the AppsData/FindMyFlipper folder to import from file. Or you can manually enter the tag information. When using the cloning method, you can export a .txt file from nrfConnect (click save button) amd place that in the same folder in order to import.

Step 4: Tracking Copy Section

• Once the app is configured, your FlipperZero can be tracked using the relevant platform's tracking service (FindMy app for Apple devices, SmartThings for Samsung devices, and respective web browsers). If using generated keys and OpenHaystack then you can track on the OHS app or via the Macless Haystack setup. Links to both are above

Customization

• Beacon Interval: Adjust how frequently your FlipperZero broadcasts its presence.
• Transmit Power: Increase or decrease the signal strength to balance between tracking range and battery life.

Background Use

The app is designed to have a negligible impact on battery life, even when running in the background. This allows for continuous tracking without the need for frequent recharging.

Compatibility

• Apple devices for AirTag tracking via the FindMy network.
• Any device that supports Samsung SmartTag tracking, including web browsers (previously FindMyMobile).

Thanks

• Huge thanks to all the people that contributed to the OpenHaystack project, supporting projects, and guides on the subject. This wouldn't be a thing without any of you! Special thanks to WillyJL for helping get the app input working and overall overhaul of the apps functions!

Legal and Privacy

This app is intended for personal and educational use. Users are responsible for complying with local privacy laws and regulations regarding tracking devices. The cloning and emulation of tracking tags should be done responsibly and with respect to the ownership of the original devices.

Disclaimer

This project is not affiliated with Apple Inc. or Samsung. All product names, logos, and brands are property of their respective owners. Use this app responsibly and ethically.

Overview (`scripts/debug/FreeRTOS/README.md`) Copy Section

FreeRTOS-GDB

Python API Library for inspecting FreeRTOS Objects in GDB

Basically, the FreeRTOS internal state is kind of hard to inspect
when working with GDB. This project provides some scripts for GDB's
Python API that make accessing some of these internals a little easier
to inspect.

##Requirements:

1. You need to have the python API enabled in your version of GDB. This is a
   compile time option when building GDB. You should be able to do something
   like this:

gdb> python print "Hello World"

and get predictable results. If it throws an error - then you don't have
python compiled in your version of GDB.

2. Need to be using FreeRTOS 8.0+. This code could probably be used with FreeRTOS
   version 7.0 or previous versions, but the current code doesn't support it.

3. You need to use the Handle Registry for Queue info to be any use.
   Note that this only works for Queue based objects and not
   for EventGroups

4. You need to put the FreeRTOS-GDB/src directory on your python path:

$> export PYTHONPATH=~/src/FreeRTOS-GDB/src/

How To Use:

/* Detailed source-code truncated for AI context efficiency. */

@note - the NONE's above may just be empty strings.

This code adds the following custom GDB commands:

• show List-Handle (symbol|address) [CastType]
  CastType is an optional argument that will cast all of the
  handles in a list to a particular type.
• show Task-List
• show Handle-Registry
• show Handle-Name (symbole|address)
• show Queue-Info [filter]
  filter can be "queue","mutex","semaphore", "counting", "recursive"

@TODO

• With GDB's Python API - it doesn't seem to handle code is separate
  files very well.

• Currently, the EventGroup objects don't have an inspector.
  Work in progress - ideal solution would likely modify the struct
  of the Event Group to provide a similar piece of info that the
  Queue handle does so that we could use the same registry.

Overview (`scripts/debug/PyCortexMDebug/README.md`) Copy Section

PyCortexMDebug

SVD Copy Chapter

ARM defines an SVD (System View Description) file format in its CMSIS standard as a means for Cortex-M-based chip manufacturers to provide a common description of peripherals, registers, and register fields. You can download SVD files for different manufacturers here.

The implementation consists of two components -- An lxml-based parser module (pysvd) and a GDB file (gdb_svd). I haven't yet worked out a perfect workflow for this, though it's quite easy to use when you already tend to have a GDB initialization file for starting up OpenOCD and the like. However your workflow works, just make sure to, in GDB:

source gdb_svd.py
svd_load [your_svd_file].svd

These files can be huge so it might take a second or two. Anyways, after that, you can do

svd

to list available peripherals with descriptions. Or you can do

svd [some_peripheral_name]

to see all of the registers (with their values) for a given peripheral. For more details, run

svd [some_peripheral_name] [some_register_name]

to see all of the field values with descriptions.

You can add format modifiers like:

• svd/x will display values in hex
• svd/o will display values in octal
• svd/t or svd/b will display values in binary
• svd/a will display values in hex and try to resolve symbols from the values

All field values are displayed at the correct lengths as provided by the SVD files.
Also, tab completion exists for nearly everything! When in doubt, run svd help.

Overview (`applications/system/js_app/modules/js_vgm/README.md`) Copy Section

The files imu.c, imu.h, and ICM42688P are from https://github.com/flipperdevices/flipperzero-game-engine.git

Please see that file for the license.

Overview (`applications/system/js_app/packages/create-fz-app/README.md`) Copy Section

Flipper Unleashed Firmware JavaScript SDK Wizard

This package contains an interactive wizard that lets you scaffold a JavaScript
application for Flipper Zero using the Custom Unleashed Firmware JS SDK.

This is a fork of the Official Flipper Zero JS SDK Wizard,
configured to use the Unleashed FW JavaScript SDK instead.
No other changes are included.

Getting started Copy Chapter

Create your application using the interactive wizard:

npx @darkflippers/create-fz-app-ul@latest

Then, enter the directory with your application and launch it:

cd my-flip-app
npm start

You are free to use pnpm or yarn instead of npm.

Documentation Copy Chapter

Check out the JavaScript section in the Developer Documentation

Overview (`applications/system/js_app/packages/fz-sdk/README.md`) Copy Section

Flipper Unleashed FW JavaScript SDK

This package contains tooling and typings for developing Flipper Zero
applications in JavaScript for Unleashed Custom Firmware (based on official SDK).

This is a fork of the Official Flipper Zero JS SDK,
with added types for the extra features provided by the Unleashed firmware JavaScript API.

Scripts made for Official Flipper Zero JS SDK will work on Unleashed Firmware too.
If you use extra features provided by Unleashed FW JS SDK, you are encouraged to use syntax like
if (doesSdkSupport(["feature-name"])) { ... } so that your JS app can work on Official
Firmware too, aswell as all other compliant Custom Firmwares. If some of those extra
features are essential to the functionality of your app, you can use checkSdkFeatures(["feature1", "feature2"])
near the beginning of your script, which will show a warning to the user that these features
are not available in their firmware distribution.

Getting started Copy Chapter

Create your application using the interactive wizard:

npx @darkflippers/create-fz-app-ul@latest

Then, enter the directory with your application and launch it:

cd my-flip-app
npm start

You are free to use pnpm or yarn instead of npm.

Versioning Copy Chapter

For each version of this package, the major and minor components match those of
the Flipper Zero JS SDK version that that package version targets. This version
follows semver. For example, apps compiled with SDK version 0.1.0 will be
compatible with SDK versions 0.1...1.0 (not including 1.0).

Every API has a version history reflected in its JSDoc comment. It is heavily
recommended to check SDK compatibility using a combination of
sdkCompatibilityStatus, isSdkCompatible, assertSdkCompatibility depending
on your use case.

Documentation Copy Chapter

Check out the JavaScript section in the Developer Documentation

Documentation AppManifests (`documentation/AppManifests.md`) Copy Section

FAM (Flipper App Manifests) {#app_manifests}

All components of Flipper Zero firmware — services, user applications, and system settings — are developed independently. Each component has a build system manifest file named application.fam, which defines the basic properties of that component and its relations to other parts of the system.

When building firmware, fbt collects all app manifests and processes their dependencies. Then it builds only those components referenced in the current build configuration. See FBT docs for details on build configurations.

App definition Copy Chapter

A firmware component's properties are declared in a Python code snippet, forming a call to the App() function with various parameters.

Only two parameters are mandatory: appid and apptype. Others are optional and may only be meaningful for certain app types.

Parameters Copy Section

• appid: string, app ID within the build system. It is used to specify which app to include in the build configuration and resolve dependencies and conflicts.

• apptype: member of FlipperAppType.* enumeration. Valid values are:

• name: name displayed in menus.
• entry_point: C function to be used as the app's entry point. Note that C++ function names are mangled, so you need to wrap them in extern "C" to use them as entry points.
• flags: internal flags for system apps. Do not use.
• cdefines: C preprocessor definitions to declare globally for other apps when the current app is included in the active build configuration. For external apps: specified definitions are used when building the app itself.
• requires: list of app IDs to include in the build configuration when the current app is referenced in the list of apps to build.
• conflicts: list of app IDs with which the current app conflicts. If any of them is found in the constructed app list, fbt will abort the firmware build process.
• provides: functionally identical to requires field.
• stack_size: stack size in bytes to allocate for an app on its startup. Note that allocating a stack too small for an app to run will cause a system crash due to stack overflow, and allocating too much stack space will reduce usable heap memory size for apps to process data. Note: you can use top and free CLI commands to profile your app's memory usage.
• icon: animated icon name from built-in assets to be used when building the app as a part of the firmware.
• order: order of an app within its group when sorting entries in it. The lower the order is, the closer to the start of the list the item is placed. Used for ordering startup hooks and menu entries.
• sdk_headers: list of C header files from this app's code to include in API definitions for external apps.
• targets: list of strings and target names with which this app is compatible. If not specified, the app is built for all targets. The default value is ["all"].
• resources: name of a folder within the app's source folder to be used for packacking SD card resources for this app. They will only be used if app is included in build configuration. The default value is "", meaning no resources are packaged.

Parameters for external apps

The following parameters are used only for FAPs:

• sources: list of strings, file name masks used for gathering sources within the app folder. The default value of ["*.c*"] includes C and C++ source files. Apps cannot use the "lib" folder for their own source code, as it is reserved for fap_private_libs. Paths starting with "!" are excluded from the list of sources. They can also include wildcard characters and directory names. For example, a value of ["*.c*", "!plugins"] will include all C and C++ source files in the app folder except those in the plugins (and lib) folders. Paths with no wildcards (*, ?) are treated as full literal paths for both inclusion and exclusion.
• fap_version: string, app version. The default value is "0.1". You can also use a tuple of 2 numbers in the form of (x,y) to specify the version. It is also possible to add more dot-separated parts to the version, like patch number, but only major and minor version numbers are stored in the built .fap.
• fap_icon: name of a .png file, 1-bit color depth, 10x10px, to be embedded within .fap file.
• fap_libs: list of extra libraries to link the app against. Provides access to extra functions that are not exported as a part of main firmware at the expense of increased .fap file size and RAM consumption.
• fap_category: string, may be empty. App subcategory, also determines the path of the FAP within the apps folder in the file system.
• fap_description: string, may be empty. Short app description.
• fap_author: string, may be empty. App's author.
• fap_weburl: string, may be empty. App's homepage.
• fap_icon_assets: string. If present, it defines a folder name to be used for gathering image assets for this app. These images will be preprocessed and built alongside the app. See FAP assets for details.
• fap_extbuild: provides support for parts of app sources to be built by external tools. Contains a list of ExtFile(path="file name", command="shell command") definitions. fbt will run the specified command for each file in the list.
• fal_embedded: boolean, default False. Applies only to PLUGIN type. If True, the plugin will be embedded into host app's .fap file as a resource and extracted to apps_assets/APPID folder on its start. This allows plugins to be distributed as a part of the host app.

Note that commands are executed at the firmware root folder, and all intermediate files must be placed in an app's temporary build folder. For that, you can use pattern expansion by fbt: ${FAP_WORK_DIR} will be replaced with the path to the app's temporary build folder, and ${FAP_SRC_DIR} will be replaced with the path to the app's source folder. You can also use other variables defined internally by fbt.

Example for building an app from Rust sources:

sources=["target/thumbv7em-none-eabihf/release/libhello_rust.a"],
    fap_extbuild=(
        ExtFile(
            path="${FAP_WORK_DIR}/target/thumbv7em-none-eabihf/release/libhello_rust.a",
            command="cargo build --release --verbose --target thumbv7em-none-eabihf --target-dir ${FAP_WORK_DIR}/target --manifest-path ${FAP_SRC_DIR}/Cargo.toml",
        ),
    ),

• fap_private_libs: list of additional libraries distributed as sources alongside the app. These libraries will be built as a part of the app build process.
  Library sources must be placed in a subfolder of the lib folder within the app's source folder.
  Each library is defined as a call to the Lib() function, accepting the following parameters:

  • name: name of the library's folder. Required.
  • fap_include_paths: list of the library's relative paths to add to the parent fap's include path list. The default value is ["."], meaning the library's source root.
  • sources: list of filename masks to be used for gathering include files for this library. Paths are relative to the library's source root. The default value is ["*.c*"].
  • cflags: list of additional compiler flags to be used for building this library. The default value is [].
  • cdefines: list of additional preprocessor definitions to be used for building this library. The default value is [].
  • cincludes: list of additional include paths to be used for building this library. Paths are relative to the app's root. This can be used for providing external search paths for this library's code — for configuration headers. The default value is [].

Example for building an app with a private library:

fap_private_libs=[
            Lib(
                name="mbedtls",
                fap_include_paths=["include"],
                sources=[
                    "library/des.c",
                    "library/sha1.c",
                    "library/platform_util.c",
                ],
                cdefines=["MBEDTLS_ERROR_C"],
            ),
            Lib(
                name="loclass",
                cflags=["-Wno-error"],
            ),
        ],

For that snippet, fbt will build 2 libraries: one from sources in lib/mbedtls folder and another from sources in the lib/loclass folder. For the mbedtls library, fbt will add lib/mbedtls/include to the list of include paths for the app and compile only the files specified in the sources list. Additionally, fbt will enable MBEDTLS_ERROR_C preprocessor definition for mbedtls sources.
For the loclass library, fbt will add lib/loclass to the list of the included paths for the app and build all sources in that folder. Also, fbt will disable treating compiler warnings as errors for the loclass library, which can be useful when compiling large 3rd-party codebases.

Both libraries will be linked with the app.

.fam file contents Copy Chapter

The .fam file contains one or more app definitions. For example, here's a part of applications/service/bt/application.fam:

App(
    appid="bt_start",
    apptype=FlipperAppType.STARTUP,
    entry_point="bt_on_system_start",
    order=70,
)

App(
    appid="bt_settings",
    name="Bluetooth",
    apptype=FlipperAppType.SETTINGS,
    entry_point="bt_settings_app",
    stack_size=1 * 1024,
    requires=[
        "bt",
        "gui",
    ],
    order=10,
)

For more examples, see .fam files from various firmware parts.

Documentation AppsOnSDCard (`documentation/AppsOnSDCard.md`) Copy Section

FAP (Flipper App Package) {#apps_on_sd_card}

fbt supports building apps as FAP files. FAPs are essentially .elf executables with extra metadata and resources bundled in.

FAPs are built with the faps target. They can also be deployed to the dist folder with the fap_dist target.

FAPs do not depend on being run on a specific firmware version. Compatibility is determined by the FAP's metadata, which includes the required API version.

How to set up an app to be built as a FAP {#fap-howto} Copy Chapter

FAPs are created and developed the same way as internal apps that are part of the firmware.

To build your app as a FAP, create a folder with your app's source code in applications_user, then write its code the way you'd do when creating a regular built-in app. Then configure its application.fam manifest, and set its apptype to FlipperAppType.EXTERNAL. See Flipper App Manifests for more details.

• To build your app, run ./fbt fap_{APPID}, where APPID is your app's ID in its manifest.
• To build your app and upload it over USB to run on Flipper, use ./fbt launch APPSRC=applications_user/path/to/app. This command is configured in the default VS Code profile as a "Launch App on Flipper" build action (Ctrl+Shift+B menu).
• To build an app without uploading it to Flipper, use ./fbt build APPSRC=applications_user/path/to/app. This command is also available in VSCode configuration as "Build App".
• To build all FAPs, run ./fbt faps or ./fbt fap_dist.

FAP assets Copy Chapter

FAPs can include static and animated images as private assets. They will be automatically compiled alongside app sources and can be referenced the same way as assets from the main firmware.

To use that feature, put your images in a subfolder inside your app's folder, then reference that folder in your app's manifest in the fap_icon_assets field. See Flipper App Manifests for more details.

To use these assets in your app, put #include "{APPID}_icons.h" in your app's source code, where {APPID} is the appid value field from your app's manifest. Then you can use all icons from your app's assets the same way as if they were a part of assets_icons.h of the main firmware.

Images and animated icons should follow the same naming convention as those from the main firmware.

Debugging FAPs Copy Chapter

fbt includes a script for gdb-py to provide debugging support for FAPs, debug/flipperapps.py. It is loaded in default debugging configurations by fbt and stock VS Code configurations.

With it, you can debug FAPs as if they were a part of the main firmware — inspect variables, set breakpoints, step through the code, etc.

If debugging session is active, firmware will trigger a breakpoint after loading a FAP into memory, but before running any code from it. This allows you to set breakpoints in the FAP's code. Note that any breakpoints set before the FAP is loaded may need re-setting after the FAP is actually loaded, since the debugger cannot know the exact address of the FAP's code before loading the FAP.

Setting up debugging environment Copy Section

The debugging support script looks up debugging information in the latest firmware build directory (build/latest). That directory is symlinked by fbt to the latest firmware configuration (Debug or Release) build directory when you run ./fbt for the chosen configuration. See fbt docs for details.

To debug FAPs, do the following:

1. Build firmware with ./fbt
2. Flash it with ./fbt flash
3. Build your FAP and run it on Flipper

After that, you can attach the debugger to the target MCU with ./fbt debug or VS Code and use all debug features.

It is important that firmware and app build type (debug/release) match and that the matching firmware folder is linked as build/latest. Otherwise, debugging will not work.

How Flipper runs an app from an SD card Copy Chapter

Flipper's MCU cannot run code directly from external storage, so it needs to be copied to RAM first. That is done by the App Loader responsible for loading the FAP from the SD card, verifying its integrity and compatibility, copying it to RAM, and adjusting it for its new location.

Since the FAP has to be loaded to RAM to be executed, the amount of RAM available for allocations from heap is reduced compared to running the same app from flash, as a part of the firmware. Note that the amount of occupied RAM is less than the total FAP file size since only code and data sections are allocated, while the FAP file includes extra information only used at app load time.

Apps are built for a specific API version. It is a part of the hardware target's definition and contains a major and minor version number. The App Loader checks if the app's major API version matches the firmware's major API version.

The App Loader allocates memory for the app and copies it to RAM, processing relocations and providing concrete addresses for imported symbols using the symbol table. Then it starts the app.

API versioning {#api-versioning} Copy Chapter

Not all parts of firmware are available for external apps. A subset of available functions and variables is defined in the "api_symbols.csv" file, which is a part of the firmware target definition in the targets/ directory.

fbt uses semantic versioning for the API. The major version is incremented when there are breaking changes in the API. The minor version is incremented when new features are added.

Breaking changes include:

• Removing a function or a global variable
• Changing the signature of a function

API versioning is mostly automated by fbt. When rebuilding the firmware, fbt checks if there are any changes in the API exposed by headers gathered from SDK_HEADERS. If so, it stops the build, adjusts the API version, and asks the user to go through the changes in the .csv file. New entries are marked with a "?" mark, and the user is supposed to change the mark to "+" for the entry to be exposed for FAPs, or to "-" for it to be unavailable.

fbt will not allow building a firmware until all "?" entries are changed to "+" or "-".

NB: fbt automatically manages the API version. The only case where manually incrementing the major API version is allowed (and required) is when existing "+" entries are to be changed to "-".

Symbol table {#symbol-table} Copy Section

The symbol table is a list of symbols exported by firmware and available for external apps. It is generated by fbt from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the fap_loader app.

fbt also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The app won't be able to run on the device until all required symbols are provided in the symbol table.

Documentation BarcodeGenerator (`documentation/BarcodeGenerator.md`) Copy Section

This is a UPC-A Barcode Generator for the Flipper Zero hardware.

Author: McAzzaMan

It will eventually be expanded into other barcode types. It currently only generates UPC-A type barcodes.

Controls Copy Chapter

Hitting the centre button on the Flipper toggles edit mode.
When in edit mode, Left and Right will change the digit to be changed, and up and down will adjust the digit value.

Documentation BuildingFapsOnAndroid (`documentation/BuildingFapsOnAndroid.md`) Copy Section

Building FAPs on Android with Termux

Contributed by @CamsShaft, adapted from
BUILD-FLIPPER-FAPS-IN-TERMUX (MIT).

Set up ufbt (micro Flipper Build Tool) inside Termux on a stock Android phone and
compile Flipper Zero applications (.fap) on-device. No PC, no proot, no virtual machine.

Scope: this builds applications, not the firmware. Building the firmware itself with fbt is not
covered here — see HowToBuild.md.

Originally worked out on a Samsung Galaxy S22 (SM-S901W, aarch64). The paths below assume an aarch64
device and the default Termux prefix ($PREFIX = /data/data/com.termux/files/usr). Nothing here is
guaranteed to match your device exactly, but the failure modes are documented in
Troubleshooting.

Why this needs extra work Copy Chapter

ufbt downloads a prebuilt arm-none-eabi-gcc cross-toolchain built for ordinary Linux against glibc.
Termux runs on Android's Bionic libc with a non-standard filesystem layout, and every ELF binary in that
toolchain asks for /lib/ld-linux-aarch64.so.1 as its dynamic linker — which does not exist on Android.

The fix is to install Termux's glibc compatibility layer, then run each toolchain binary through glibc's
own linker via a small wrapper script.

Do not run patchelf on the toolchain binaries. It corrupts their ELF segment layout and you get
segfaults out of cc1. The wrappers below leave the binaries byte-for-byte untouched.

Prerequisites Copy Chapter

• An aarch64 Android device
• Termux installed from F-Droid — the Google Play build
  is obsolete and will not work
• An internet connection and a couple of GB free for the toolchain, SDK and glibc

1. Base packages Copy Chapter

pkg update && pkg upgrade -y
pkg install python python-pip git file -y

file is not optional — the wrapper loop in step 6 uses it to tell ELF binaries apart from everything else.

2. glibc compatibility layer Copy Chapter

pkg install glibc-repo -y
pkg install glibc-runner -y

These have to be two separate commands: glibc-repo is what adds the glibc repository that
glibc-runner is served from. Together they install a full glibc under $PREFIX/glibc/, including the
dynamic linker we need. Verify it:

ls $PREFIX/glibc/lib/ld-linux-aarch64.so.1

Never set LD_PRELOAD to glibc's libc.so.6 globally. It poisons Termux's own Bionic binaries,
Python included, and the breakage is not obvious. The wrappers in step 6 remove any need for it.

3. Install ufbt and the Python build dependencies Copy Chapter

pip install ufbt colorlog heatshrink2 pyelftools scons pillow

If the pillow wheel fails to build, use the Termux package instead: pkg install python-pillow.

4. Point ufbt at the Unleashed SDK Copy Chapter

ufbt defaults to the official firmware SDK. To build against Unleashed, pass this repository's update
index:

ufbt update --index-url=https://up.unleashedflip.com/directory.json --channel=dev

Channels are dev and release. The index URL is also listed in the ReadMe.
Every later ufbt update needs the same flags, otherwise you silently fall back to the official SDK
and your app is built against the wrong API.

If ~/.ufbt/toolchain/ is still empty after that, any ufbt invocation bootstraps the toolchain:

ufbt -h

An error mentioning python3 at this point is expected — step 5 fixes it. Check that the toolchain landed:

ls ~/.ufbt/toolchain/aarch64-linux/bin/arm-none-eabi-gcc
ls ~/.ufbt/toolchain/aarch64-linux/arm-none-eabi/bin/as
ls ~/.ufbt/toolchain/aarch64-linux/libexec/gcc/arm-none-eabi/*/cc1

5. Repoint the toolchain's Python Copy Chapter

The toolchain ships its own glibc-linked Python, which cannot run here. Point every python3* entry at
Termux's Python instead:

TOOLCHAIN="$HOME/.ufbt/toolchain/aarch64-linux"

for py in "$TOOLCHAIN"/bin/python3*; do
    [ -e "$py" ] || [ -L "$py" ] || continue
    ln -sf "$PREFIX/bin/python3" "$py"
done

6. Wrap the toolchain binaries Copy Chapter

This is the step everything else depends on. Each wrapper invokes the real binary through glibc's dynamic
linker with an explicit --library-path, so the binary itself is never modified.

TOOLCHAIN="$HOME/.ufbt/toolchain/aarch64-linux"
GLIBC_LIB="$PREFIX/glibc/lib"

wrap() {
    for f in "$@"; do
        [ -f "$f" ] || continue
        case "$f" in *.real | *.so | *.so.*) continue ;; esac
        [ -e "$f.real" ] && continue
        file -b "$f" | grep -q '^ELF' || continue

        mv "$f" "$f.real"
        cat > "$f" <<WRAPPER
#!$PREFIX/bin/bash
exec "$GLIBC_LIB/ld-linux-aarch64.so.1" --library-path "$GLIBC_LIB:$TOOLCHAIN/lib" "$f.real" "\$@"
WRAPPER
        chmod +x "$f"
        echo "wrapped $f"
    done
}

wrap "$TOOLCHAIN"/bin/arm-none-eabi-*
wrap "$TOOLCHAIN"/arm-none-eabi/bin/*
wrap "$TOOLCHAIN"/libexec/gcc/arm-none-eabi/*/*

Those three globs are three separate directories of ELF binaries. Missing one gives a different failure:

The guards matter, especially if you re-run this later:

• *.so is skipped because liblto_plugin.so lives in libexec/ and is a shared library, not an
  executable. Wrapping it gives invalid ELF header.
• *.real and the $f.real check keep the function idempotent, so re-running it after a toolchain update
  cannot wrap a wrapper.
• In bin/ only arm-none-eabi-* is wrapped, deliberately: bin/python3 now points at Termux's Bionic
  Python and must not go through glibc's linker.

ufbt update can replace the toolchain — re-run steps 5 and 6 after every update.

7. Build Copy Chapter

git clone https://github.com/<owner>/<some-flipper-app>.git
cd <some-flipper-app>
ufbt

A successful build ends like this:

scons: Entering directory '...'
        CC      ...
        LINK    ...
        FAP     ...
        FASTFAP ...
        APPCHK  dist/some_app.fap
                Target: 7, API: 88.2

The .fap is in dist/. Check the reported API against the firmware on your Flipper — a mismatch means
the app will refuse to load.

8. Getting the .fap onto the Flipper Copy Chapter

ufbt launch and ufbt flash_usb need a serial connection to the Flipper (/dev/ttyACM*).
On a stock, non-rooted Android this does not work — Android does not expose USB CDC-ACM device nodes
to Termux, so there is nothing for ufbt to talk to. Only a rooted device with a working CDC-ACM driver can
use those commands.

Copy the file out instead. FAPs live in /ext/apps/<Category>/ on the microSD card
(see AppsOnSDCard.md):

termux-setup-storage                        # one-time: grants Termux access to shared storage
cp dist/some_app.fap ~/storage/downloads/

From Downloads the file is visible to every other app on the phone, so you can move it to the Flipper
the way you normally would — the Flipper Mobile App, or a USB-C microSD card reader.

Troubleshooting Copy Chapter

`cannot execute cc1` / `cannot execute as` Copy Section

One of the three directories in step 6 was not wrapped. Re-run the wrap calls — they are safe to repeat.

`liblto_plugin.so: invalid ELF header` Copy Section

A shared library got wrapped. Restore it:

LIBEXEC="$(echo "$HOME"/.ufbt/toolchain/aarch64-linux/libexec/gcc/arm-none-eabi/*)"
mv "$LIBEXEC/liblto_plugin.so.real" "$LIBEXEC/liblto_plugin.so"

`Segmentation fault` from cc1 Copy Section

The binary was corrupted, almost always by patchelf. Re-download the toolchain and re-apply the wrappers:

rm -rf ~/.ufbt/toolchain
ufbt -h

Then redo steps 5 and 6. Never use patchelf on these binaries.

`No module named 'colorlog'` / `'heatshrink2'` / `'elftools'` Copy Section

pip install colorlog heatshrink2 pyelftools

`convert: No such file or directory` Copy Section

pillow is missing: pip install pillow, or pkg install python-pillow.

`python3: No such file or directory` Copy Section

The toolchain's Python symlink is broken or was restored by an update. Re-run step 5.

`CANNOT LINK EXECUTABLE "python3": library "ld-linux-aarch64.so.1" not found` Copy Section

LD_PRELOAD is pointed at glibc's libc.so.6, which breaks Termux's own Bionic binaries. Clear it:

unset LD_PRELOAD
unset -f ufbt          # in case a shell function is shadowing ufbt

Then check your shell startup files for leftovers:

grep -r "glibc\|LD_PRELOAD" ~/.bashrc ~/.profile ~/.bash_profile ~/.zshrc 2>/dev/null

`ufbt update` says the SDK is up to date, but the toolchain is missing Copy Section

ufbt tracks the SDK and the toolchain separately. Force both:

rm -rf ~/.ufbt/current ~/.ufbt/toolchain
ufbt update --index-url=https://up.unleashedflip.com/directory.json --channel=dev
ufbt -h

Then redo steps 5 and 6.

The app builds but reports the wrong API version Copy Section

An ufbt update was run without --index-url, so ufbt switched back to the official SDK. Re-run the
command from step 4.

The wrappers disappeared after an update Copy Section

Expected — ufbt update can replace the whole toolchain directory. Re-run steps 5 and 6.

What actually happens Copy Chapter

Each wrapper invokes its real binary through glibc's dynamic linker with an explicit --library-path
pointing at glibc's libraries. When arm-none-eabi-gcc execs cc1, it hits a shell script that chains
through the linker to the untouched .real binary. The cross-compiled output is unaffected — it targets
bare-metal Cortex-M, not Linux.

ufbt (Python, Bionic)
  └─ arm-none-eabi-gcc (wrapper)
       └─ ld-linux-aarch64.so.1 → arm-none-eabi-gcc.real (glibc)
            ├─ cc1 (wrapper)      → ld-linux-aarch64.so.1 → cc1.real
            ├─ as (wrapper)       → ld-linux-aarch64.so.1 → as.real
            └─ collect2 → ld (wrapper) → ld-linux-aarch64.so.1 → ld.real
                 └─ output: some_app.fap (ARM Cortex-M4, for the Flipper Zero)

Credits Copy Chapter

Worked out and written up by @CamsShaft through extensive trial and error
on a Samsung Galaxy S22 running Termux — no PC, no proot, no virtual machines. Original guide and its MIT
license: BUILD-FLIPPER-FAPS-IN-TERMUX.

Documentation CustomFlipperName (`documentation/CustomFlipperName.md`) Copy Section

How to change Flipper name:

Instruction Copy Chapter

1. Go to Settings -> Desktop -> Change Flipper Name
2. Enter your new custom name for your flipper and click Save, name will be saved on microSD card, and will stay same after firmware updates
3. You will see a message Name is set! and when you exit from settings -> flipper will automatically reboot!
4. After reboot you will see your new custom name in device info and right screen passport
5. Done!

To reset device name to default - do same steps but do not enter any characters, leave it empty and click Save

Documentation DangerousSettings (`documentation/DangerousSettings.md`) Copy Section

How to extend SubGHz supported frequency range Copy Chapter

CC1101 Frequency range specs: 300-348 MHz, 386-464 MHz, and 778-928 MHz (+ 350MHz and 467MHz was added to default range)

This setting will extend to: 281-361 MHz, 378-481 MHz, and 749-962 MHz

1. Please do not do that unless you know what exactly you are doing
2. You don't need extended range for almost all use cases
3. Extending frequency range and transmitting on frequencies that outside of hardware specs can damage your hardware!
4. Flipper Devices team and/or unleashed fw developers is not responsible of any damage that can be caused by using CFW or extending frequency ranges!!!

If you really sure you need that change, find subghz/assets/dangerous_settings file on your microSD, read comments on first lines
and change false to true

Documentation ExpansionModules (`documentation/ExpansionModules.md`) Copy Section

Expansion Module Protocol {#expansion_protocol}

Terms and definitions Copy Chapter

• Expansion Module: A third-party hardware unit meant for use with Flipper Zero by connecting it to its GPIO header.
• Expansion Module Protocol: A serial-based, byte-oriented, synchronous communication protocol described in this document.
• Host: Hardware unit tasked with serving requests. Used interchangeably with Flipper, Server, Host etc. throughout this document.
• Device: Used interchangeably with Expansion Module, Module, Client, etc.
• RPC: Remote Procedure Call, a protobuf-based communication protocol widely used by Flipper Zero companion applications.
• Timeout Interval: Period of inactivity to be treated as a loss of connection, also denoted as Tto. Equals to 250 ms.
• Baud Rate Switch Dead Time: Period of time after baud rate change during which no communication is allowed, also denoted Tdt. Equals to 25 ms.

Features Copy Chapter

• Automatic expansion module detection
• Baud rate negotiation
• Basic error detection
• Request-response communication flow
• Integration with Flipper RPC protocol

Hardware Copy Chapter

Depending on the UART selected for communication, the following pins area available for the expansion modules to connect to:

Frame structure Copy Chapter

Each frame consists of a header (1 byte), contents (size depends on frame type) and checksum (1 byte) fields:

Heartbeat frame Copy Section

HEARTBEAT frames are used to maintain an idle connection. In the event of not receiving any frames within Tto, either side must cease all communications and be ready to initiate the connection again.

Note that the contents field is not present (0 bytes length).

Status frame Copy Section

STATUS frames are used to report the status of a transaction. Every received frame MUST be confirmed by a matching STATUS response.

The Error code field SHALL have one of the following values:

Baud rate frame Copy Section

BAUD RATE frames are used to negotiate communication speed. The initial connection SHALL always happen at 9600 baud. The first message sent by the module MUST be a BAUD RATE frame, even if a different speed is not required.

If the requested baud rate is supported by the host, it SHALL respond with a STATUS frame with an OK error code, otherwise the error code SHALL be 0x02 (Baud rate not supported). Until the negotiation succeeds, the speed SHALL remain at 9600 baud. The module MAY send additional BAUD RATE frames with alternative speeds in case the initial request was refused. No other frames are allowed until the speed negotiation succeeds.

Control frame Copy Section

CONTROL frames are used to control various aspects of the communication and enable/disable various device features.

The Command field SHALL have one of the following values:

Notes:

1. Must only be used while the RPC session NOT active.
2. Must only be used while the RPC session IS active.
3. See 1, otherwise OTG is to be controlled via RPC messages.

Data frame Copy Section

DATA frames are used to transmit arbitrary data in either direction. Each DATA frame can hold up to 64 bytes. If an RPC session is currently open, all received bytes are forwarded to it.

The Data field SHALL have the following structure:

Communication flow Copy Chapter

In order for the host to be able to detect the module, the respective feature must be enabled first. This can be done via the GUI by going to Settings → Expansion Modules and selecting the required Listen UART or programmatically by calling expansion_enable(). Likewise, disabling this feature via the same GUI or by calling expansion_disable() will result in ceasing all communications and not being able to detect any connected modules.

The communication is always initiated by the module by the means of shortly pulling the RX pin down. The host SHALL respond with a HEARTBEAT frame indicating that it is ready to receive requests. The module then MUST issue a BAUDRATE request within Tto. Failure to do so will result in the host dropping the connection and returning to its initial state.

/* Detailed source-code truncated for AI context efficiency. */

Error detection Copy Chapter

Error detection is implemented via adding an extra checksum byte to every frame (see above).

The checksum is calculated by bitwise XOR-ing every byte in the frame (excluding the checksum byte itself), with an initial value of 0.

Error recovery behaviour Copy Section

In the event of a detected error, the concerned side MUST cease all communications and reset to initial state. The other side will then experience
a communication timeout and the connection will be re-established automatically.

Documentation FAQ (`documentation/FAQ.md`) Copy Section

FAQ

I bought Flipper Zero, and I don't know what I can do with it, please help! Copy Chapter

• Start with reading official main page
• Then check out official docs where you can find answers to most questions

How do I install Unleashed Firmware? Copy Chapter

See this

What version should I install? What do the letters `e`, `c`... mean? Copy Chapter

Follow this link for details.

I installed Unleashed and now the backlight doesn't work Copy Chapter

You’ve enabled RGB backlight mod in settings made for custom RGB modded flippers.

Please, do not use that version if your flipper isn’t modded!
Disable in Settings -> LCD & Notifications -> RGB mod settings

If you have RGB backlight mod do the same but enable the mod instead

What apps (plugins) are included with Unleashed Firmware? Copy Chapter

See default pack and extra pack (for e build) list here.

Where can I find differences between the original (official) firmware and Unleashed Firmware? Copy Chapter

Right here

How to use the SubGHz Remote app? Copy Chapter

1. Open the app, press the Back button, and select New map file
2. Configure signal files and their names for every button (also you can only add one signal and make other buttons empty - just don't select any files for them in config)
3. Save the new map file
4. Open the map file and select your previously created file
5. Use buttons to send the subghz signal files that you selected in map config at step 2

Where can I find what SubGHz protocols (manufacturers) are supported and what frequency and modulation to use with them? Copy Chapter

Here - link.

I want to request or make new SubGHz protocol, my remote (is not car keyfob) and is not supported, how to record RAW signal properly? Copy Chapter

1. Open SubGHz app, (if you know the frequency skip that step and go to Read) select Frequency analyzer, press and hold button on your remote and place it near IR window on flipper
   You will find a approx. frequency that remote uses, release button on the remote and wait until frequency will be placed in history list
   Hold OK on flipper to jump into Read mode, now try pressing your remote couple times holding it for at least 2 seconds
   Try different modulations, AM650/FM238/FM476/FM12K - nothing works? Lets make RAW recording for analysis
2. Knowing the frequency open Read RAW and set it here in config page
   Make sure RSSI Threshold is set to (----)
   You need to make 1 RAW for each modulation AM650/FM238/FM476/FM12K
   Press REC and on your remote press 1 button 5 times holding it for 1-2 seconds - then 5 times holding it for 5 seconds each time
   If your remote has more than 1 button - record each button in similar way
   Label each raw - what button you recorded
3. Copy all that RAW files to PC and create issue in firmware repo, attach raw's in archive
   Provide high quality photos of the remote, if possible - photos of disassembled remote too
   Its model, manufacturer, any known information
   If you have access to receiver board, add a photo too
   Done! If your remote appears not to be encrypted and very unique, it might be added soon
   In case if you want to help us or analyze that signals youself there's a great online tool - https://lab.flipper.net/pulse-plotter

How to build (compile) the firmware? Copy Chapter

Follow this link.

I installed Unleashed firmware, and now my mobile app doesn't connect to flipper ( OR I changed flipper device name, and my mobile app now doesn't connect to flipper ) Copy Chapter

1. Click Forget flipper in the mobile app
2. Open Phone Settings - Bluetooth, find the flipper - if it present here - open its options and click forget device
3. On the flipper itself open Settings -> Bluetooth -> Forget all devices and confirm
4. Make sure your flipper has bluetooth ON then open the mobile app and pair it to the flipper

My desktop (pin, favourites, etc..) (or other) settings were reset to default after an update, what do I do? Copy Chapter

Just configure those settings again, and make sure you view the changelogs for the releases that came out after your previous version, when settings struct is changed, the settings file is reset after an update, this happens only when struct changes are required, so don't assume that settings will be reset in every release, this will only happen in specific ones

Why is my flipper not connecting to Chrome? Copy Chapter

The most common cause of the flipper not connecting to google chrome is having qFlipper open while trying to connect your flipper.

Or having second flipper lab page open at same time.

You must close qFlipper (or other flipper lab web pages) before attempting to connect your flipper to Chrome.

Flipper doesn't work! How to restore firmware? Copy Chapter

Follow this guide

Useful links and files Copy Chapter

Flipper Awesome - place where you can find almost all links that you might need:

• Awesome-FlipperZero
• Dict files for iButton Fuzzer and RFID Fuzzer:
  • https://t.me/flipperzero_unofficial_ru/37058
  • https://t.me/flipperzero_unofficial_ru/37072
• UL Releases in Telegram
• UL Dev Builds in Telegram
• Our Discord

How do I change my flipper's name? Copy Chapter

It's easy:

1. Open Settings -> Desktop -> Change Flipper Name
2. Enter new name and click Save
3. Exit from settings - flipper will automatically reboot
4. Done, you now have a custom name which will stay until you reset it or replace it with a new one

How to reset the name to default? Copy Chapter

1. Open Settings -> Desktop -> Change Flipper Name
2. Do not enter anything, just click Save
3. Exit from settings - Flipper will automatically reboot
4. Done, name is reset to its original form.

How do I copy files from GitHub to my Flipper Zero? Copy Chapter

Follow this detailed guide.

Where can I find “This file” or “That file” for my flipper? Copy Chapter

These 2 repos will cover (99.9%) of your needs:

• https://github.com/UberGuidoZ/Flipper/tree/main
• https://github.com/UberGuidoZ/Flipper-IRDB/tree/main

How can I support the Unleashed firmware project? Copy Chapter

Please follow this link.

What are the dev builds? Where I can get the latest build for dev branch? Copy Chapter

This is an automatic assembly of the latest commits from this repository that have not yet been released. The previous build is deleted when a new one is uploaded, and the old one remains only as a file in the telegram channel

[!CAUTION]

Be wary - these are not release ready builds!

They may have bugs and issues!
If you are using the dev build and find issues:
Report it! GitHub issues

Dev builds are available in Discord, in channel - unleashed-development
Builds can also be found here.
And here

What is the update server? Copy Chapter

We have our own update server https://up.unleashedflip.com/directory.json
It is identical to the official one; it is impossible to change it in applications without rebuilding the application
If you want to use it, you need to patch or build your own build of the application you are interested in

Also you can use it with uFBT to build apps for UL SDK - uFBT will accept that link as one of args

The server will remain active and will be automatically updated

External Radio: How to connect the CC1101 module Copy Chapter

Guide

How to add extra Sub-GHz frequencies Copy Chapter

Guide

How to use Flipper as new SubGHz remote (Nice FlorS, BFT Mitto, Somfy Telis, Aprimatic, AN-Motors, etc..) Copy Chapter

Guide

How Can I Unlock / Remove SubGHz restriction? Copy Chapter

[!TIP]

If you are using Unleashed Firmware - all region locks are removed by default!

Also, there is a way to go outside of frequencies stated in CC1101 datasheet, but transmission on those frequencies may cause chip damage, make sure you know what you are doing!

Do not edit these settings to bypass region lock since there is no region locks in unleashed, all chip supported frequencies will work without any extra steps.

But, if you know that you need to bypass subghz chip safety restrictions - you can unlock the safety restriction which will allow you to go outside the chips supported frequency.
This covers how to do it and information regarding the risks of damage to the flipper by doing so.

Please read this before.

Can I clone a car key fob for my own car to use my flipper as a key? Copy Chapter

No, and trying to do so with Read RAW will lead to key desync or unpair with blacklist which means re-pair is very hard to do and requires service tools

How to clean .DS_Store and other dot files left from macOS Copy Chapter

sudo dot_clean -mn /Volumes/Flipper\ SD -> Flipper\ SD may be named differently for you, replace it with your microSD card name

How to sort files on flipper microSD on macOS / Linux? Copy Chapter

Will make sorting faster, and will work for OFW:

1. brew install fatsort -> Install fatsort using brew.sh (only on macOS)
2. diskutil list -> Find your disk name for flipper microSD
3. diskutil unmount /Volumes/Flipper\ SD
4. sudo fatsort -n /dev/disk4s1 -> Replace disk4s1 with your microSD id found on step 2

My flipper feels slow and unresponsive? Copy Chapter

1. Make sure you are using a good microSD card from a known brand. Flipper works with microSD via SPI meaning not all microSDs will work well even if they are compatible with other devices.
2. Go into Settings -> System and make sure that you have
   text Copy

   Log Level = None
   Debug = OFF
   Heap Trace = None

3. If some settings are set to something different - change them to None / OFF
4. Make sure your battery is charged, that can affect performance too

Flipper crashed, stuck, frozen? Copy Chapter

Reboot it by holding Left + Back buttons

How to reset a forgotten Flipper pin code? Copy Chapter

Disconnect USB Cable if it was connected

1. Turn off the device - hold back button -> Turn Off
   If you can't turn it off, try the next step but hold the buttons for 30-40 seconds)
2. Hold Up + Back for ~5 sec -> You will see a reset screen -> Hold Right to reset (and Down arrow to exit if you don't want to reset your pin code)
3. Done, user config (some settings, pin code) is erased to default factory setup, user files on microSD will stay

What are the differences between x, y, and z firmware? Copy Chapter

If you just got your flipper and not sure what will work better for you, start with original official firmware, if you think you need more features or want to remove subghz region locks then:

• Try installing Unleashed firmware, which is fork of official firmware with many new features and preinstalled apps (check out e build).
• In other case, If you want to experiment more with UI and other things look for existing forks of Unleashed Firmware.
• Or, create your own fork with your own customisations
• Also, before reporting any found issues, make sure you are in correct repo, if you are not using Unleashed, but a different fork or the original firmware, do not report issue in Unleashed firmware repo or UL communities (Telegram, Discord, etc..)

Is there a correct way to capture Infrared signals? Copy Chapter

There is indeed, especially with AC units - a new documentation has been released with some notes and steps on capturing infrared signals correctly along with some example data so you visually able to understand the difference between the two.

More info

NFC / RFID FAQ Copy Chapter

From our good friends @Equip and @np0

MIFARE Ultralight Copy Section

Scan the card, hold the Flipper Zero up to the reader to get the password to unlock the rest of the sectors, then scan the card again.

MIFARE DESFire / MIFARE Ultralight C Copy Section

The Flipper Zero has no available attacks for this card currently.

Bank cards Copy Section

• You cannot clone bank cards
• The Flipper Zero cannot emulate bank cards
• The Flipper Zero cannot pretend to be a point of sale machine

Amiibos Copy Section

• NTAG215. That's it. It's not going on a MIFARE Classic.
• Currently, you cannot write Amiibos to new physical tags.

HID / iClass Copy Section

• Picopass iClass can be read using the Picopass reader plugin
• 26bit Picopass can be downgraded to H10301 RFID credentials (note, it is not guaranteed to work if the reader is not configured to read low frequency)
• Readers will need to be configured and have an LF RFID antenna in order to be read. Certain iClass readers are HF only, and do not have the ability to have LF configured.
• Emulation for Picopass was added on July 26th, and the updated version can be found in latest releases of Unleashed Firmware with apps preinstalled, or in official Apps Hub via Flipper Mobile app
• Write support for personalization mode cards is doable with the app
• The Seader app and a SAM expansion board will allow you to read more secure HID cards, which may be helpful in downgrade attacks

LF-RFID Copy Section

If you want to make clones of low frequency RFID chips you need to write to T5577's. Blanks do not exist. All of the chips the Flipper Zero can interact with are read-only and cannot be overwritten or purchased blank.

T5577s are multi-emulator chips that the Flipper Zero can program to be other tags

Unknown Card / Fob Copy Section

If you have exhausted all options of scanning via NFC / RFID / PICOPASS then take a photo of:

• The front and back of your credential
• The reader you use with the credential
• If your credential is a card, hold it up to a very bright light source e.g. a lightbulb and take a photo of the exposed antenna. This is useful for identification, post it for us to identify!

How do I access the CLI / Logs? Copy Chapter

To access the Serial CLI, click one of the following based on your platform.

Desktop web browser*
**Chromium browsers only, such as: Google Chrome, Microsoft Edge, Opera / Opera GX, Brave, and Vivaldi.*

  <li>Connect your Flipper via USB.</li>
  <li>Ensure qFlipper and any other serial terminals are closed.</li>
  <li>Open [lab.flipper.net/cli](https://lab.flipper.net/cli) in one of the aforementioned browsers.</li>
  <li>Click <kbd>CONNECT</kbd> and select <kbd>USB Serial Device</kbd> from the list.</li>
  <li>Wait until you can see your device details on screen.</li>
  <li>Select the 💻 CLI item from the left sidebar.</li>
  <li>**Done!**</li>





Windows

  <li>Install [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) if it isn't already.</li>
  <li>Connect your Flipper via USB.</li>
  <li>Open qFlipper and look for the COM port next to the Flipper's name. * (Should say COM followed by a number, like <kbd>COM1</kbd>)*</li>
  <li>Take note of the COM port number.</li>
  <li>**CLOSE qFlipper**, otherwise the next steps won't work.</li>
  <li>Open PuTTY and ensure you're on the Session screen.</li>
  <li>Select <kbd>Serial</kbd> under connection type.</li>
  <li>Set serial line to the COM port. * (Just COM followed by the number, like <kbd>COM1</kbd>)*</li>
  <li>Set speed to `115200`</li>
  <li>*Optional: Save the session settings for easy connection later.*</li>
  <li>Finally, click <kbd>Open</kbd> to enter the CLI.</li>
  <li>**Done!**</li>
  <li>If you get an "Access Denied" error, make sure qFlipper isn't running!</li>





MacOS/Linux
*Note: I'm a filthy Windows user without any way to verify this procedure. Let me know if it's wrong!*

  <li>Install [GNU Screen](https://www.gnu.org/software/screen/) if it isn't already.</li>
  <li>Connect your Flipper via USB.</li>
  <li>Open qFlipper and look for the device path next to the Flipper's name. *(Starts with /dev/tty)*</li>
  <li>*Alternatively: Run `ls /dev/tty.*` in a terminal.*</li>
  <li>Take note of the full device path.</li>
  <li>**CLOSE qFlipper**, otherwise the next steps won't work.</li>
  <li>Open a terminal.</li>
  <li>Run `screen PATH 115200`, replacing PATH with the device path from earlier.</li>
  <li>**Done!**</li>





Android

  <li>Install [Serial USB Terminal](https://play.google.com/store/apps/details?id=de.kai_morich.serial_usb_terminal) if it isn't already.</li>
  <li>Open the app and go to the Connections screen in the hamburger menu *(3 bars icon)*</li>
  <li>Connect your Flipper via USB.</li>
  <li>Click the refresh icon if it doesn't automatically show up.</li>
  <li>Allow Serial USB Terminal to access Flipper if prompted.</li>
  <li>If it doesn't automatically connect, click the connect icon in the upper right. *(2 plugs icon)*</li>
  <li>**Done!**</li>
  <li>*Note: To exit log mode, you'll have to disconnect and reconnect using the icon.*</li>





iPhone
Unfortunately, iOS is incapable of accessing a serial terminal over USB; try one of the other methods

CLI FAQ Source + Check out this FAQ for more info:
https://github.com/djsime1/awesome-flipperzero/blob/main/FAQ.md

Documentation FuriCheck (`documentation/FuriCheck.md`) Copy Section

Run time checks and forced system crash {#furi_check}

The best way to protect system integrity is to reduce amount cases that we must handle and crash the system as early as possible.
For that purpose, we have a bunch of helpers located in Furi Core check.h.

Couple notes before start Copy Chapter

• Definition of Crash — log event, save crash information in RTC and reboot the system.
• Definition of Halt — log event, stall the system.
• Debug and production builds behave differently: debug build will never reset system in order to preserve state for debugging.
• If you have debugger connected we will stop before reboot automatically.
• All helpers accept optional MESSAGE_CSTR: it can be in RAM or Flash memory, but only messages from Flash will be shown after system reboot.
• MESSAGE_CSTR can be NULL, but macros magic already doing it for you, so just don't.

`furi_assert(CONDITION)` or `furi_assert(CONDITION, MESSAGE_CSTR)` Copy Chapter

Assert condition in development environment and crash the system if CONDITION is false.

• Should be used at development stage in apps and services.
• Keep in mind that release never contains this check.
• Keep in mind that libraries never contain this check by default, use LIB_DEBUG=1 if you need it.
• Avoid putting function calls into CONDITION, since it may be omitted in some builds.

`furi_check(CONDITION)` or `furi_check(CONDITION, MESSAGE_CSTR)` Copy Chapter

Always assert condition and crash the system if CONDITION is false.

• Use it if you always need to check conditions

`furi_crash()` or `furi_crash(MESSAGE_CSTR)` Copy Chapter

Crash the system.

• Use it to crash the system. For example, if an abnormal condition is detected.

`furi_halt()` or `furi_halt(MESSAGE_CSTR)` Copy Chapter

Halt the system.

• We use it internally to shutdown Flipper if poweroff is not possible.

Documentation FuriHalBus (`documentation/FuriHalBus.md`) Copy Section

Using FuriHalBus API {#furi_hal_bus}

Basic info Copy Chapter

On system startup, most of the peripheral devices are under reset and not clocked by default. This is done to reduce power consumption and to guarantee that the device will always be in the same state before use.

Some crucial peripherals are enabled right away by the system, others must be explicitly enabled by the user code.

NOTE: Here and afterwards, the word "system" refers to any code belonging to the operating system, hardware drivers or built-in apps.

To ENABLE a peripheral, call furi_hal_bus_enable(). At the time of the call, the peripheral in question MUST be disabled;
otherwise a crash will occur to indicate improper use. This means that any given peripheral cannot be enabled twice or more without disabling it first.

To DISABLE a peripheral, call furi_hal_bus_disable(). Likewise, the peripheral in question MUST be enabled, otherwise a crash will occur.

To RESET a peripheral, call furi_hal_bus_reset(). The peripheral in question MUST be enabled, otherwise a crash will occur.
This method is used whenever it is necessary to reset all the peripheral's registers to their initial states without disabling it.

Peripherals Copy Chapter

Built-in peripherals are divided into three categories:

• Enabled by the system on startup, never disabled;
• Enabled and disabled by the system on demand;
• Enabled and disabled by the user code.

Always-on peripherals Copy Section

Below is the list of peripherals that are enabled by the system. The user code must NEVER attempt to disable them.

Table 1 — Peripherals enabled by the system

On-demand system peripherals Copy Section

Below is the list of peripherals that are enabled and disabled by the system. The user code must avoid using them directly, preferring the respective APIs instead.

When not using the API, these peripherals MUST be enabled by the user code and then disabled when not needed anymore.

Table 2 — Peripherals enabled and disabled by the system

On-demand shared peripherals Copy Section

Below is the list of peripherals that are not enabled by default and MUST be enabled by the user code each time it accesses them.

Note that some of these peripherals may also be used by the system to implement its certain features.

The system will take over any given peripheral only when the respective feature is in use.

Table 3 — Peripherals enabled and disabled by user

DMA Copy Chapter

The DMA1, DMA2 peripherals are a special case in that they have multiple independent channels.
Some channels may be in use by the system.

Below is the list of DMA channels and their usage by the system.

Table 4 — DMA channels

Documentation FuriHalDebugging (`documentation/FuriHalDebugging.md`) Copy Section

Furi HAL Debugging {#furi_hal_debugging}

Some Furi subsystems have additional debugging features that can be enabled by adding additional defines to firmware compilation.
Usually, they are used for low level tracing and profiling or signal redirection/duplication.

FuriHalOs Copy Chapter

--extra-define=FURI_HAL_OS_DEBUG enables tick, tick suppression, idle and time flow.

There are 3 signals that will be exposed to external GPIO pins:

• AWAKE — PA7 — High when system is busy with computations, low when sleeping. Can be used to track transitions to sleep mode.
• TICK — PA6 — Flipped on system tick, only flips when no tick suppression in progress. Can be used to track tick skew and abnormal task scheduling.
• SECOND — PA4 — Flipped each second. Can be used for tracing RT issue: time flow disturbance means system doesn't conform Hard RT.

FuriHalPower Copy Chapter

--extra-define=FURI_HAL_POWER_DEBUG enables power subsystem mode transitions tracing.

There are 2 signals that will be exposed to external GPIO pins:

• WFI — PB2 — Light sleep (wait for interrupt) used. Basically, this is the lightest and most non-breaking things power save mode. All functions and debug should work correctly in this mode.
• STOP — PC3 — STOP mode used. Platform deep sleep mode. Extremely fragile mode where most of the silicon is disabled or in unusable state. Debugging MCU in this mode is nearly impossible.

FuriHalSD Copy Chapter

--extra-define=FURI_HAL_SD_SPI_DEBUG enables SD card SPI bus logging.

Documentation HardwareTargets (`documentation/HardwareTargets.md`) Copy Section

What a Firmware Target is {#hardware_targets} Copy Chapter

Flipper's firmware is modular and supports different hardware configurations in a common code base. It encapsulates hardware-specific differences in furi_hal, board initialization code, linker files, SDK data and other information in a target definition.

Target-specific files are placed in a single sub-folder in targets. It must contain a target definition file, target.json, and may contain other files if they are referenced by current target's definition. By default, fbt gathers all source files in target folder, unless they are explicitly excluded.

Targets can inherit most code parts from other targets, to reduce common code duplication.

Target Definition File Copy Chapter

A target definition file, target.json, is a JSON file that can contain the following fields:

• include_paths: list of strings, folder paths relative to current target folder to add to global C/C++ header path lookup list.
• sdk_header_paths: list of strings, folder paths relative to current target folder to gather headers from for including in SDK.
• startup_script: filename of a startup script, performing initial hardware initialization.
• linker_script_flash: filename of a linker script for creating the main firmware image.
• linker_script_ram: filename of a linker script to use in "updater" build configuration.
• linker_script_app: filename of a linker script to use for linking .fap files.
• sdk_symbols: filename of a .csv file containing current SDK configuration for this target.
• linker_dependencies: list of libraries to link the firmware with. Note that those not in the list won't be built by fbt. Also several link passes might be needed, in such case you may need to specify same library name twice.
• inherit: string, specifies hardware target to borrow main configuration from. Current configuration may specify additional values for parameters that are lists of strings, or override values that are not lists.
• excluded_sources: list of filenames from the inherited configuration(s) NOT to be built.
• excluded_headers: list of headers from the inherited configuration(s) NOT to be included in generated SDK.
• excluded_modules: list of strings specifying fbt library (module) names to exclude from being used to configure build environment.

Apps & Hardware Copy Chapter

Not all apps are available on different hardware targets.

• For apps built into the firmware, you have to specify a compatible app set using FIRMWARE_APP_SET=... fbt option. See fbt docs for details on build configurations.

• For apps built as external FAPs, you have to explicitly specify compatible targets in the app's manifest, application.fam. For example, to limit the app to a single target, add targets=["f7"], to the manifest. It won't be built for other targets.

For details on app manifests, check out their docs page.

Building Firmware for a Specific Target Copy Chapter

You have to specify TARGET_HW (and, optionally, FIRMWARE_APP_SET) for fbt to build firmware for a non-default target. For example, building and flashing debug firmware for f18 can be done with

./fbt TARGET_HW=18 flash_usb_full

Documentation HowToBuild (`documentation/HowToBuild.md`) Copy Section

How to Build by yourself:

Install required software Copy Chapter

• Git - Download for Windows, on Linux/Mac install via package manager (brew, apt, ...)

For development:

• Git
• VSCode

Clone the Repository Copy Chapter

You should clone with

$ git clone --recursive https://github.com/DarkFlippers/unleashed-firmware.git

VSCode integration Copy Chapter

fbt includes basic development environment configuration for VSCode. Run ./fbt vscode_dist to deploy it. That will copy the initial environment configuration to the .vscode folder. After that, you can use that configuration by starting VSCode and choosing the firmware root folder in the File > Open Folder menu.

Build on Linux/macOS

Check out documentation/fbt.md for details on building and flashing firmware.

Compile plugin and run it on connected flipper Copy Section

./fbt COMPACT=1 DEBUG=0 launch_app APPSRC=applications_user/yourplugin

Compile everything + get updater package to update from microSD card Copy Section

./fbt COMPACT=1 DEBUG=0 updater_package

Check dist/ for build outputs.

Use flipper-z-{target}-update-{suffix}.tgz to flash your device.

Build on Windows

Check out documentation/fbt.md for details on building and flashing firmware.

Compile everything + get updater package to update from microSD card Copy Section

./fbt.cmd COMPACT=1 DEBUG=0 updater_package

You may need to change / to \ in front of fbt command (Only for Windows)!

Check dist/ for build outputs.

Use flipper-z-{target}-update-{suffix}.tgz to flash your device.

If compilation fails, make sure all submodules are all initialized. Either clone with --recursive or use git submodule update --init --recursive.

Build apps on Android (no PC)

Applications (.fap) can also be built on an Android phone with ufbt running inside Termux — see Building FAPs on Android with Termux. This covers apps only, not the firmware.

Documentation HowToInstall (`documentation/HowToInstall.md`) Copy Section

Update firmware

[Get Latest Firmware from GitHub Releases](https://github.com/DarkFlippers/unleashed-firmware/releases) Copy Chapter

**If installing for first time - Update to the latest official firmware before proceeding** Copy Section

**If you are already using unleashed - no need to install any other FW or version before installing update, just install latest version on top of your current one, all will be fine** Copy Section

With Unleashed FW Web Installer Copy Chapter

• Be sure you updated to latest official release before(only if installing for the first time), and verify that microSD card is installed

• Open -> Unleashed FW Web Installer

• Connect your device and press Connect button - Select your device in popup window (be sure to use Chromium based browser)

• Select Release or Dev branch

• Press Install button

• And wait, if all flashed
  successfully - you will have all needed assets pre installed

• Done

With Flipper Lab - Web Updater Copy Chapter

• Be sure you updated to latest official release before(only if installing for the first time), and verify that microSD card is installed

• Open latest release page - Releases

• Connect your device and follow link - Install via Web Updater
  after that on web updater page - press Connect button

• Press Install button

• And wait, if all flashed
  successfully - you will have all needed assets pre installed

• Done

With iOS mobile app Copy Chapter

• Be sure you updated to latest official release before(only if installing for the first time), and verify that microSD card is installed
• Open latest release page - Releases
• Download flipper-z-f7-update-(version).tgz
• Open downloads in ios Files app, select downloaded .tgz file, click Share, select Flipper App
• In flipper app click green Update button, be sure it shows Custom flipper-z-f7-update... in Update Channel
• Wait until update is finished
• Error in ios app will show up, but flipper will be updated successfully
• And if all flashed successfully - you will have all needed assets pre installed
• Done

With Android mobile app (with .tgz download) Copy Chapter

• Be sure you updated to latest official release before(only if installing for the first time), and verify that microSD card is installed
• Open latest release page - Releases
• Download flipper-z-f7-update-(version).tgz
• In flipper app click Update channel button, select Custom
• Select downloaded .tgz file
• Click Update
• Wait until update is finished
• And if all flashed successfully - you will have all needed assets pre installed
• Done

With Android mobile app (via web updater link) Copy Chapter

• Be sure you updated to latest official release before(only if installing for the first time), and verify that microSD card is installed
• Open latest release page - Releases
• Click Install via Web Updater
• It will ask to open with browser or Flipper app, select Flipper App
• Continue to install
• Wait until update is finished
• And if all flashed successfully - you will have all needed assets pre installed
• Done

With qFlipper (1.2.0+) Copy Chapter

• Download qFlipper that allows .tgz installation Download qFlipper (official link)
• Be sure you updated to latest official release before(only if installing for the first time), and verify that microSD card is installed
• Open latest release page - Releases
• Download flipper-z-f7-update-(version).tgz
• Launch qFlipper
• Connect your device and select Install from file
• Select flipper-z-f7-update-(version).tgz that you downloaded
• Update will start
• And wait, if all flashed successfully - you will have all needed assets pre installed
• Done

With offline update on flipper Copy Chapter

**Replace (CURRENT VERSION) with version that you downloaded from releases** Copy Section

• Unpack flipper-z-f7-update-(CURRENT VERSION).tgz (or .zip) into any free folder on your PC or smartphone
• You should find folder named f7-update-(CURRENT VERSION) that contains files like update.fuf, resources.tar and etc..
• Remove microSD card from flipper and insert it into PC or smartphone (you can skip this step and upload all files using qFlipper)
• Create new folder update on the root of the microSD card and move folder that you previously extracted from archive - f7-update-(CURRENT VERSION) into update on microSD card
• So result should look like update/f7-update-(CURRENT VERSION)/ with all files in this folder on microSD card, remember iOS default Files app doesn't show all files properly (3 instead of 6), so you need to use another app for unpacking or use PC or Android
• Verify that all files are present on your microSD card
• After all you need to insert microSD card back into flipper, navigate into filebrowser, open this file
  update/f7-update-(CURRENT VERSION)/update.fuf
• Update will start, wait for all stages
• Done

After install:

• [Read instructions how to use plugins and more](https://github.com/DarkFlippers/unleashed-firmware#instructions) Copy Chapter

• [How To: Configure Sub-GHz Remote App](https://github.com/DarkFlippers/unleashed-firmware/blob/dev/documentation/SubGHzRemotePlugin.md) Copy Chapter

Documentation InfraredCaptures (`documentation/InfraredCaptures.md`) Copy Section

Infrared Captures

Credits go to @gsurkov, @skotopes, @knrn-ai, @DrZlo13 and @ahumeniy for making and contributing to the original UniversalRemotes.md Documentation located Here.

slightly adapted by @amec0e

Televisions, Fans, Audio and Projectors Copy Chapter

Each signal is recorded using the following process:

1. Get the remote and point it to Flipper's IR receiver.
2. Start learning a new remote if it's the first button or press + to add a new button otherwise.
3. Do a Quick Press of a remote button and save it under a corresponding name. (NOTE: Don't hold the remote button down, this will result in long captures and long playbacks ultimately slowing down the universal remotes performance)
4. Repeat steps 2-3 until all required signals are saved.

The signal names are self-explanatory. Remember to make sure that every recorded signal does what it's supposed to.

NOTE: It's possible some devices around you will cause interference and may force your capture into raw data instead of a parsed code.
If you notice you get a parsed code when capturing it's best to click "Retry" a few times on the flipper when capturing to ensure the device is not suffering from any interference, and that the cleanest capture is possible.

Types of data Copy Chapter

Parsed data

This is the cleanest type of data because it means it is a recognized code.

name: EXAMPLE
type: parsed
protocol: NEC
address: 07 00 00 00
command: 02 00 00 00

Raw Data

With raw data its important not to hold the remotes button down when capturing on your flipper as this increases not only the size of the capture but the repeats and also how long it takes to send the signal back. Below is an ideal button capture.

# 
name: EXAMPLE
type: raw
frequency: 38000
duty_cycle: 0.330000
data: 2410 597 1189 599 592 600 1186 602 589 603 1183 606 595 597 593 598 1208 605 596 596 594 597 593 599 592 25604 2403 604 1182 606 595 597 1189 599 591 601 1185 603 618 573 617 575 1211 602 588 603 588 605 596 596 594 25605 2402 604 1192 596 594 597 1189 599 592 601 1185 628 593 598 593 600 1186 602 589 603 588 604 597 595 596

Capturing Raw Data:

If you are sure your remote is using raw data the best way to capture it will be to do a quick button press (don't hold the remotes button down) and look at how many samples you get, the general idea here is to get the lowest amount of raw data samples captured (around 100 samples is about right) while making sure that the playback on the device is still working. This is usually accomplished by doing a quick button press on the remote when capturing.

Air Conditioners Copy Chapter

Air conditioners differ from most other infrared-controlled devices because their state is tracked by the remote.
The majority of A/C remotes have a small display that shows the current mode, temperature, and other settings.
When the user presses a button, a whole set of parameters is transmitted to the device, which must be recorded and used as a whole.

In order to capture a particular air conditioner, there is a particular process require to capturing and this is done using the following process:

1. Get the remote and press the Power Button so that the display shows that A/C is ON.
2. Set the A/C to the corresponding mode (see table below), leaving other parameters such as fan speed or vane on AUTO (if applicable).
3. Press the POWER button to switch the A/C off.
4. Start learning a new remote on Flipper if it's the first button or press + to add a new button otherwise.
5. Point the remote to Flipper's IR receiver as directed and press POWER button once again.
6. Save the resulting signal under the specified name.
7. Repeat steps 2-6 for each signal from the table below.

Finally, record the Off signal:

1. Make sure the display shows that the A/C is ON.
2. Start learning a new signal on Flipper and point the remote towards the IR receiver.
3. Press the POWER button so that the remote shows the OFF state.
4. Save the resulting signal under the name Off.

Test the file against the actual device. Make sure that every signal does what it's supposed to.

Documentation KeyCombo (`documentation/KeyCombo.md`) Copy Section

Key Combos {#key_combos}

There are times when your Flipper feels blue and doesn't respond to any of your commands due to a software issue. This guide will help you solve this problem.

Basic combos Copy Chapter

Hardware reset Copy Section

• Press LEFT and BACK and hold for a couple of seconds
• Release LEFT and BACK

This combo performs a hardware reset by pulling the MCU reset line down.
Main components involved: Keys → DD8(NC7SZ32M5X, OR-gate) → DD1(STM32WB55, MCU).

It won't work only in one case:

• The MCU debug block is active and holding the reset line from inside.

Hardware Power Reset Copy Section

• Disconnect the USB cable and any external power supplies
• Disconnect the USB once again
• Make sure you've disconnected the USB and any external power supplies
• Press BACK and hold for 30 seconds (this will only work with the USB disconnected)
• If you haven't disconnected the USB, then disconnect it and repeat the previous step
• Release the BACK key

This combo performs a reset by switching SYS power line off and then on.
Main components involved: Keys → DD6(bq25896, charger).

It won't work only in one case:

• Power supply is connected to USB or 5V_ext

Software DFU Copy Section

• Press LEFT on boot to enter DFU with Flipper boot-loader

It won't work only in one case:

• Flipper boot-loader is damaged or absent

Hardware DFU Copy Section

• Press OK on boot to enter DFU with ST boot-loader

It won't work only in one case:

• Option Bytes are damaged or set to ignore the OK key

DFU combos Copy Chapter

Hardware Reset + Software DFU Copy Section

• Press LEFT and BACK and hold for a couple of seconds
• Release BACK
• Device will enter DFU with an indication (Blue LED + DFU Screen)
• Release LEFT

This combo performs a hardware reset by pulling the MCU reset line down. Then, the LEFT key indicates to the boot-loader that DFU mode is requested.

It won't work in two cases:

• The MCU debug block is active and holding the reset line from inside
• Flipper boot-loader is damaged or absent

Hardware Reset + Hardware DFU Copy Section

• Press LEFT, BACK and OK and hold for a couple of seconds
• Release BACK and LEFT
• The device will enter DFU without an indication

This combo performs a hardware reset by pulling the MCU reset line down. Then, the OK key forces MCU to load the internal boot-loader.

It won't work in two cases:

• The MCU debug block is active and holding the reset line from inside
• Option Bytes are damaged or set to ignore the OK key

Hardware Power Reset + Software DFU Copy Section

• Disconnect the USB and any external power supplies
• Press BACK and LEFT for 30 seconds
• Release BACK
• The device will enter DFU with an indication (Blue LED + DFU Screen)
• Release LEFT
• Plug in the USB

This combo performs a reset by switching the SYS power line off and then on. Next, the LEFT key indicates to the boot-loader that DFU mode is requested.

It won't work in two cases:

• Power supply is connected to USB or 5V_ext
• Flipper boot-loader is damaged or absent

Hardware Power Reset + Hardware DFU Copy Section

• Disconnect the USB and any external power supplies
• Press BACK and OK and hold for 30 seconds
• Release BACK and OK
• The device will enter DFU without indication
• Plug in the USB

This combo performs a reset by switching the SYS power line off and then on. Next, the OK key forces MCU to load the internal boot-loader.

It won't work in two cases:

• Power supply is connected to USB or 5V_ext
• Option Bytes are damaged or set to ignore the OK key

Alternative ways to recover your device

If none of the described methods helped you:

• Make sure the battery charged
• Disconnect the battery and connect again (requires disassembly)
• Try to flash the device with ST-Link or another programmer that supports SWD

If you're still here and your device is not working: it's not a software issue.

Documentation LFRFIDRaw (`documentation/LFRFIDRaw.md`) Copy Section

Reading RAW RFID data {#lfrfid_raw}

Flipper Zero has the option to read RAW data from 125 kHz cards that allows you to record the card's data and save it, similar to how a dictaphone records sound.

To use this function, you need to activate the Debug mode on your Flipper Zero by doing the following:

1. Go to Main Menu → Settings → System.

2. Set Debug to ON.

Once the Debug mode is activated on your Flipper Zero, you can read RAW data from 125 kHz RFID cards:

1. Go to Main Menu → 125 kHz RFID → Extra Actions.

2. Select RAW RFID data and name the raw file.

3. Read instructions and press OK.

4. Apply the card to Flipper Zero's back.

5. Once the reading is finished, press OK.

Two files with data (with ASK and PSK modulations) will be saved in the lfrfid folder on the microSD card. Now, you can share it and the card's photo with developers by creating an issue on GitHub.

Documentation MifareUltralightAES QA (`documentation/MifareUltralightAES_QA.md`) Copy Section

MIFARE Ultralight AES (MF0AES20) — full-feature QA validation plan

End-to-end hardware validation for the whole UL-AES feature (identity, originality signature,
AES 3-pass auth + protected read, dictionary attack / manual unlock, key management, write-back,
emulation, one-way counters, config decode, Random ID, and secure messaging).

The secure-messaging (CMAC) slice has its own deep-dive — see
MifareUltralightAES_SecureMessaging_QA.md. It is the
one part with no reference implementation (PM3 only detects the SEC_MSG_ACT bit), so it is the
critical merge gate; this document covers everything else and hands off to it at Phase 10.

Your equipment (this plan is scoped to it) Copy Chapter

• One genuine MF0AES20 ("OG card"). As shipped it is factory-default: DataProtKey and
  UIDRetrKey both all-zero, SEC_MSG off, RID off, fully open (AUTH0 protects nothing),
  AUTH_LIM unlimited, config unlocked (CFGLCK = 0), key pages unlocked. Confirmed via
  hf mfu info.
• Proxmark3 (Iceman) — three roles: (a) capture ground-truth dumps, (b) personalize the card
  into each test configuration, (c) act as the external reader for emulation tests. It cannot
  speak secure messaging.
• One Flipper running this firmware (device under test). Enable Debug logging
  (Settings → System → Log Level → Debug) so the per-feature markers are visible.

What this kit can and cannot cover Copy Section

The two ❌ CMAC items are the only feature paths this kit leaves unvalidated. Note them at sign-off.

Memory / config map (authoritative — from this firmware's own decoder + datasheet) Copy Chapter

⚠️ PM3's hf mfu info config decode uses a legacy Ultralight template for MF0AES20 (it labels
pages 0x34–0x37, actually the UIDRetrKey, as cfg0/cfg1/PWD/PACK). Trust this table, not
PM3's labels, for where the config bits live.

Safety & reversibility rules (read before any PM3 write) Copy Chapter

1. Never write AUTH_LIM (0x2A bytes 2–3), CFGLCK (0x2A bit6), LOCK_KEYS (0x2D), or
   the static lock bytes. A wrong value there can permanently lock or brick the card.
2. Every personalization in this plan is reversible because the card stays open (AUTH0 off
   for reads / plain writes allowed). Once you set AUTH0/PROT, plain writes to config need auth;
   always restore AUTH0/PROT to open first, then any other change.
3. Read-modify-write only. Before setting a bit in a page, read the page's current 4 bytes,
   change only the target bit, keep the other three bytes. Page 0x29 byte 3 is AUTH0 — never
   clobber it.
4. Keep the Phase 0 pristine dump as ground truth for every diff.
5. PM3 command syntax for MF0AES20 is recent/build-dependent — confirm with hf mfu --help /
   hf mfu wrbl -h. On the open card, hf mfu rdbl -b / hf mfu wrbl -b -d <8 hex>
   need no key. Paste the current page bytes and the exact -d value will be computed for you
   so AUTH0 is never clobbered.

Phase 0 — Baseline capture (PM3, no change) Copy Chapter

1. hf mfu info → record UID, version, all three counters, config, and the Known UL-AES keys
   (expect Data + UID key = all-zero, ( ok )).
2. Dump raw memory (with the all-zero key) and save it — this is the ground truth every later phase
   diffs against.
3. Note the raw bytes of pages 0x29, 0x2A, 0x2D — you'll read-modify-write these later.

Test matrix Copy Chapter

Record Pass/Fail + notes per row. Restore the card to open/factory (Phase 0 state) between phases
that personalize it.

P1 — Identity & read (open card, no change) Copy Section

• Flipper: NFC → Read.
• Expect: type Mifare Ultralight AES, UID 04 7B A2 C2 45 13 90, ATQA 0044, SAK 00,
  60/60 pages, counters 0/0/0. Full info → config decode matches PM3 (Auth off, unlimited, user
  cfg open, RID off, SEC_MSG off, key lock N).

P2 — Originality signature (capture + PM3-verified emulation, no change) Copy Section

• Flipper: Read → Save → inspect the .nfc for an AES signature: line (= the 48 bytes
  PM3 showed). Then Emulate that dump.
• PM3: hf mfu info against the emulation.
• Expect: the saved .nfc carries the 48-byte signature; PM3 prints the Tag Signature block
  and Signature verification: successful (not the old READ-SIGNATURE timeout).

P3 — AES auth + protected read (PM3 creates a protected region) Copy Section

• PM3 (record 0x29/0x2A first): set AUTH0 (0x29 byte 3) to the first data page you want
  protected (e.g. 0x10) and PROT (0x2A byte 0 bit7 = OR 0x80) so reads of the protected
  region require auth. Leave AUTH_LIM/CFGLCK alone.
• Flipper: Read → open pages read, protected pages need auth → Unlock → Run Dictionary
  Attack (finds all-zero) or Enter Key Manually 00…00 → protected pages now read.
• Expect: all pages match the Phase 0 ground truth; recovered key shown + saved with the dump.
• Restore: PROT = 0, AUTH0 back to its open value.

P4 — Dictionary attack, manual unlock, wrong key (+ non-standard-key give-up) Copy Section

UL-AES has no one-shot "enter password" box. Manual key entry = adding the key to the User
dictionary (Extra Actions → MIFARE Ultralight AES Keys → Add). On an incomplete read the AES
dictionary attack auto-launches and tries the User dict, then the System dict.

• Dict: with the card protected (P3's AUTH0=0x10), Read → the AES dict attack auto-runs →
  recovers the all-zero key from the System dict → full 60/60 read.
• Manual (correct key): AES Keys → Add the key → Read → the header shows "MFUL AES User
  Dictionary" and succeeds. Proves the manual-entry path feeds the poller.
• Wrong key → clean fall-over: put only a bogus key in the User dict → Read → User dict fails
  cleanly (no hang, no infinite re-select), auto-advances to the System dict, succeeds with all-zero.
  AUTH_LIM unlimited → no lock-out.

P4c — non-standard DataProtKey → terminal give-up (all-plain, fail-safe)

The rows above never show the all-keys-exhausted state, because the System dict's all-zero key
always wins on a factory card. Force it by giving the card a key that is in no dictionary.
Safety design: protect from 0x2A (not 0x10) so the config page 0x29 stays below AUTH0
and remains plain-writable — then every write is plain and the throwaway key never has to be
authenticated against (sidesteps the byte-order / partial-key traps entirely).

Throwaway key A0A1A2A3A4A5A6A7A8A9AAABACADAEAF. Blocks: 0x29 = 41, 0x30–0x33 = 48–51.

1. Set the key (card open → plain writes): wrbl -b 48 -d A0A1A2A3, -b 49 -d A4A5A6A7,
   -b 50 -d A8A9AAAB, -b 51 -d ACADAEAF.
2. Verify it changed: hf mfu info → Known UL-AES keys no longer lists the all-zero Data
   key as ( ok ) (only the UID key stays ( ok )). This is the fail-safe checkpoint — the card
   is still open, so if a write didn't take you've lost nothing.
3. Protect: wrbl -b 41 -d 0000002A.
4. Flipper Read → the AES dict attack exhausts User + System dicts, none authenticate →
   semi-success, partial pages (~42/60), no key recovered, no hang, no lock-out.
5. Restore (reopen first, then zero the key — all plain): wrbl -b 41 -d 0000003C, then
   -b 48 -d 00000000 … -b 51 -d 00000000.
6. Confirm: hf mfu info → all-zero Data key ( ok ), AUTH0 open.

Hardware-learned safety notes. Key pages are plain-writable only while the card is open
(AUTH0 > 0x3B); a plain key-page write on a still-protected card times out — the card mutes
it, nothing is written, no harm. If that happens, reopen with an authenticated write
(wrbl -b 41 -d 0000003C -k <AES key>) and retry. Never touch AUTH_LIM / CFGLCK / LOCK.

DataProtKey byte order (validated gotcha)

Raw wrbl writes bytes in tag-memory order; the AES engine — and both the Flipper's manual
entry and PM3 hf mfu aesauth --key — use the reverse. A card whose pages 0x30–0x33 read
A0A1A2A3 A4A5A6A7 A8A9AAAB ACADAEAF therefore authenticates with key
AFAEADACABAAA9A8A7A6A5A4A3A2A1A0. Cross-validated on hardware: that reversed value unlocks on
the Flipper and returns Authentication with DataProtKey … ( ok ) on PM3. This is the datasheet
§8.6.3 / PM3 SwapEndian16 convention; our dumps store the key reversed so they write back to tag
memory verbatim (mf_ultralight.c:802, mf_ultralight_poller.c:820). Enter a manually-recovered key
in AES order (reversed from what raw wrbl shows), not tag-memory order.

P5 — Key management (UI, no card) Copy Section

• Flipper: Extra Actions → MIFARE Ultralight AES Keys → add a site key.
• Expect: it persists and is offered on subsequent Unlock/dict attempts.

P6 — Write-back to the OG card (PM3-verified) Copy Section

Write behavior (from the poller). Offered only on a fully-read UL-AES dump, as two items
Write (Keep Key) / Write (Copy Key). The write authenticates the target first with a
dictionary key (so the target's current key must be in a dict — all-zero is), then writes.
Scope is safe: data pages 0x04–0x27 always; config/lock 0x28–0x2F are never written;
Keep Key stops before the key; Copy Key additionally writes DataProtKey 0x30–0x33 (UIDRetrKey
0x34–0x37 never written). Match gate is by type, not UID. Key pages are written verbatim
from the dump (tag-memory/reversed order) → PM3 verifies with the reversed key. Enable Debug
logging to see UL write: key kept… / key overwrite with source.

• Keep Key (no file edit needed): Read + Save the factory card → dump A (all-zero). PM3 drops a
  marker on a data page (wrbl -b 10 -d DEADBEEF, card open). Flipper: load A → Write (Keep Key).
  PM3 re-dump: page 10 back to 00000000 (data pages are written), pages 48–51 still
  all-zero, 0x29/0x2A/0x2D unchanged, hf mfu info → all-zero Data key ( ok ).
• Copy Key (one .nfc edit — byte-order proof): the .nfc is plain-text; the DataProtKey lives
  in the page lines Page 48–51 (the DataProtKey: on-screen is a render, not a save field).
  Edit them to a non-zero key in tag-memory order (e.g. 00 11 22 33 / 44 55 66 77 / 88 99 AA BB / CC DD EE FF), load → Write (Copy Key) (auths with the card's current all-zero key, then writes
  data + new key). PM3: dump shows pages 48–51 = that value verbatim; the all-zero Data key is no
  longer ( ok ); hf mfu aesauth --key FFEEDDCCBBAA99887766554433221100 → ( ok ) — the
  reversed key authenticates, proving the write path's byte order end-to-end. Config/lock untouched.
• Restore: card stays open (Copy Key never touches AUTH0), so PM3 plain-writes pages 48–51 back
  to 00000000, then hf mfu info → all-zero Data key ( ok ).
• (W2 clone-to-blank needs a 2nd blank UL-AES card — skip with a single OG card.)

P7 — Emulation to an external reader (PM3 is the reader) Copy Section

The listener-side counterpart to P3 — the Flipper emulates, PM3 reads. Reuse P6's dumps (A =
factory/all-zero key, B = key 00112233…FF).

• P7a — auth + field fidelity (dump A): Emulate A → PM3 hf mfu info (identity/version/counters/
  config/signature verifies) matches the real card, and hf mfu aesauth --key 000…0 →
  ( ok ). That ( ok ) proves the listener completes the 3-pass AES challenge-response as a card.
• P7b — listener byte order + wrong-key (dump B): Emulate B → hf mfu aesauth --key FFEEDDCCBBAA99887766554433221100 (the reversed key) → ( ok ); --key 000…0 (wrong) →
  fails. Confirms the listener extracts the AES key as reverse(pages 0x30–0x33) and rejects bad
  keys.
• P7c — AUTH0 enforcement (optional): edit a copy of A, Page 41 → 00 00 00 10, emulate; PM3
  hf mfu dump without a key vs -k 000…0 reads the 0x10+ region differently. Caveat: the listener
  rolls over restricted reads (returns early-page data) rather than NAKing, so the unauth signal
  is rolled data, not a clean error — the definitive proof stays the aesauth result above.
• Result (HW): P7a/b/c all pass — emulation is indistinguishable from the real card and the
  listener AES auth path (auth grant, byte order, wrong-key reject, AUTH0 gate) is validated.

P8 — Random ID detection & display (PM3 sets `RID_ACT`) — PASSED Copy Section

• PM3: set RID_ACT (0x29 byte 0 bit0 = OR 0x01, keeping AUTH0): hf mfu wrbl -b 41 -d 0100003C. Re-select — the card now presents a random 4-byte anticollision UID (ISO14443-3
  single-size, first byte 0x08); the real 7-byte UID is hidden until an authenticated read.
• Flipper: Read → shows the random UID + Random ID: on.
• HW result (PASS): detected as UL-AES, the random UID is read, and the info view decodes
  Random ID: on.
• UID length note: the Flipper's 4-byte display is the literal random anticollision UID
  (08 …); PM3's 7-byte with 00 00 00 trailing is the same value zero-padded to the normal
  Ultralight UID width. Neither is the real UID.
• Restore: hf mfu wrbl -b 41 -d 0000003C.
• Scope: retrieving/showing the real static UID behind a random one is a separate planned
  capability, tracked as P12 (below) — out of P8's scope.

P9 — Config-decoder cross-check (PM3 sets, Flipper decodes) — PASSED Copy Section

One bit at a time (plain, reversible writes on the open card): PM3 write → Flipper Read + full info →
confirm the one decoded line → restore → next. Baseline 0x29 = 00 00 00 3C, 0x2A = 8C 05 00 00
(keep 0x2A byte 1 = 05 VCTID, bytes 2-3 = 00).

• ⚠️ Never test CFGLCK (0x2A bit 6 = 0x40, permanent config lock) or AUTH_LIM (0x2A
  bytes 2-3, arms a failed-auth lock-out) — every 0x2A write above is 0x8*/0x0C, no bit 6.
• HW result (PASS): each decoded line flips exactly as expected.

P10 — Secure messaging (CMAC) → the critical gate Copy Section

The one part with no reference implementation (PM3 detects the SEC_MSG_ACT bit but cannot
speak CMAC). Full row detail: MifareUltralightAES_SecureMessaging_QA.md.
With this kit (1 Flipper + PM3 + 1 card) run the reader-side rows R1/R2/W1/R4; the X-group
(2nd Flipper), E-group (CMAC reader) and W2 (blank card) are out of scope.

⚠️ CRITICAL recoverability rule. Once SEC_MSG_ACT is on, any config write in a protected
region needs a CMAC-authenticated write — which PM3 can't do and the Flipper's Write
skips config pages. So never set AUTH0 ≤ 0x29 while SEC_MSG_ACT is on, or you may be
unable to clear it. Use AUTH0 = 0x2A: it keeps 0x29 below AUTH0 (PM3 can plain-restore it)
yet still forces the Flipper to authenticate — which is what triggers the CMAC session.

Setup: hf mfu wrbl -b 41 -d 0200002A (SEC_MSG_ACT + AUTH0=0x2A). Confirm hf mfu rdbl -b 41 →
02 00 00 2A. Enable Debug logging.

Why this triggers CMAC even though data pages stay open: the Flipper enters an authenticated
session via the dictionary attack (an incomplete plain read triggers it) for reads, and
unconditionally for writes. On a SEC_MSG card, once authenticated every command must be CMAC'd,
so the first post-auth plain READ/WRITE fails at pages_read == 0 → the poller switches to CMAC.

HW FINDING + FIX (2026-08-13, commit ce541e129). On real silicon the card mutes that first
plain command — the reader reports a frame-wait timeout (MfUltralightErrorTimeout), not the
4-bit Protocol NAK the detection gate originally required — so CMAC never engaged and read/write of
a SEC_MSG card failed at 0/60 (and could hang on the first frame). Fixed by accepting Timeout as
well as Protocol in both the read gate (mf_ultralight_poller_handler_read_pages) and the write
adaptive switch (mf_ultralight_poller_write_page_auto), via a shared
mf_ultralight_is_secure_messaging_switch_error() predicate; reviewed clean (code-reviewer +
silent-failure-hunter + simplifier). This is exactly the silicon-behaviour gap P10 existed to catch —
without HW testing, secure messaging would have shipped fully non-functional.

• R1 — full CMAC read: Read → incomplete → Unlock with Dictionary → log shows UL-AES: plain read failed post-auth, switching to secure messaging → all 60 pages read over CMAC (~15 exchanges
  → validates the +2 counter step + MAC byte order), no MAC mismatch; data matches PM3.
• R2 — counters over CMAC: after R1, full info shows counters 0/0/0 (match PM3).
• W1 — CMAC write-back: Write (Keep Key) a saved dump → the write auths → log shows the CMAC
  switch on the first page write → data pages written MAC-wrapped, no MAC mismatch; verify via PM3
  re-read (data pages are below AUTH0, so PM3 reads them plain).
• R4 — key pages never leak: the saved dump's pages 0x30-0x37 read back as zero.
• HW result — PASS (post-fix): R1 read all 60/60 pages over CMAC with +2 counter progression
  across ~60 exchanges and zero MAC mismatches (data matched PM3, incl. config page
  0x29 = 02 00 00 2A); R2 read all 3 counters over CMAC; R4 confirmed key pages 0x30-0x37 masked to
  zero; W1 wrote data pages 0x04-0x27 MAC-wrapped with +2 write-counter progression (PM3 re-read
  confirmed the overwrite). The SV2 session key, CMAC byte order and counter step are all correct.

Restore: hf mfu wrbl -b 41 -d 0000003C (plain — 0x29 is below AUTH0=0x2A), then hf mfu info → Secure msg off, AUTH0 open, all-zero Data key ( ok ).

P11 — Regression (non-UL-AES must be unaffected) — PASSED Copy Section

• Timeout-fix blast radius (most important): a plain open UL-AES card reads a clean 60/60 with
  no CMAC; a protected non-SEC_MSG UL-AES card (AUTH0=0x10, SEC_MSG off) reads 60/60 via the dict
  attack with no false CMAC switch (post-auth reads succeed plainly, so the broadened
  Timeout||Protocol gate does not mis-fire).
• Shared-code: Read / emulate a Ultralight-C, an NTAG (e.g. NTAG215), and a plain
  Ultralight — unchanged behavior; the shared poller/listener changes and the new signature
  type-branch don't perturb these (their 32-byte signature path is untouched).
• HW result (PASS): all of the above confirmed on hardware.

P12 — Random ID real-UID retrieval (FUTURE — implement, then test in isolation) Copy Section

Planned capability, separate from P8 (which only detects/displays RID). Today the real static UID
behind a random one is not retrieved on an open RID card: the reveal (mf_ultralight_poller.c:837)
only fires after a successful auth, but a plain UL-AES read skips auth (mf_ultralight.c:140) and
Unlock is offered only on an incomplete read (mf_ultralight.c:233,259) — so an AUTH0-off RID
card never authenticates and the real UID is never recovered.

• Implement: on RID detection (anticollision UID0 == 0x08, or the RID_ACT bit after a read),
  auto-attempt an authentication to retrieve the real UID using the UIDRetrKey
  (MfUltralightAesKeyTypeUid, type 0x01; dict / all-zero) — not only the DataProtKey the read/unlock
  path uses today (mf_ultralight.c:138) — then display the recovered real UID in the UL-AES info
  view ("on top of the AES info"), alongside Random ID: on. Optionally also offer Unlock when
  the presented UID is random even though data read completed.
• Isolation test: set RID_ACT only (open card, hf mfu wrbl -b 41 -d 0100003C) → plain Read
  → expect the real UID auto-retrieved and shown in info with no manual unlock; cross-check vs PM3's
  known static UID 04 7B A2 C2 45 13 90. Then set a non-zero UIDRetrKey ≠ DataProtKey (pages
  0x34–0x37, plain write while open; same tag-memory/reversed byte order as DataProtKey) and confirm
  the reveal uses the UID key specifically (fails if only the Data key is tried). Restore both.
• Interim mechanism check (current build): force an incomplete read so Unlock appears — set RID
  and AUTH0=0x2A (keeps 0x29 plain-writable): hf mfu wrbl -b 41 -d 0100002A → Read → Unlock
  with Dictionary → see whether 04 7B A2 C2 45 13 90 appears (answers: does DataProtKey auth reveal
  it, or is UIDRetrKey required?). Restore plain: hf mfu wrbl -b 41 -d 0000003C.

Sign-off Copy Chapter

Once P1–P9 + P11 pass and the SEC_MSG reader-side rows (P10 → R1/R2/W1) pass with correct
multi-exchange counter behavior, the feature is validated on real silicon to the extent this kit
allows, and PR #1058 can leave draft (noting the emulation-side CMAC gap for a follow-up with a
2nd Flipper).

Documentation MifareUltralightAES SecureMessaging QA (`documentation/MifareUltralightAES_SecureMessaging_QA.md`) Copy Section

MIFARE Ultralight AES — Secure Messaging (CMAC) QA validation plan

Hardware validation plan for the secure-messaging (CMAC) capability of the MIFARE
Ultralight AES (MF0AES20) support. This is the one part of the UL-AES feature that has no
reference implementation to cross-check against (Proxmark3 only detects the SEC_MSG_ACT
bit — it does not implement the secure-messaging protocol), so its framing was derived from
the datasheet alone and must be confirmed on real silicon before merge.

Scope Copy Chapter

In scope — secure messaging only:

• Reader, read over secure messaging: adaptive detection (a plain READ NAKs right after
  auth ⇒ re-auth and switch to CMAC), MAC-wrapped READ, MAC-wrapped READ_CNT.
• Reader, write-back over secure messaging: adaptive detection on the first page write,
  MAC-wrapped WRITE, standalone-MAC ACK.
• Emulation of a secure-messaging card: listener verifies the command MAC, MAC-wraps every
  response, replaces the WRITE ACK with a standalone MAC, drops the session on a bad MAC.

Relevant commits: 3af5af8a9, 5f72e5e31, 8251a8222, db0a51cac, c06ef72bd.
Key code: mf_ultralight_aes_crypto.c (mf_ultralight_aes_cmac8_ctr),
mf_ultralight_poller_i.c (mf_ultralight_poller_txrx_aes_cmac),
mf_ultralight_poller.c (mf_ultralight_poller_write_page_auto, counter handler),
mf_ultralight_listener.c (send_response, verify_strip_cmd, run-loop dispatch).

Out of scope (covered by the general UL-AES validation, not repeated here): AES 3-pass auth,
dictionary attack, manual unlock, read/write/emulation on non-secure-messaging cards, config
render, Random ID, key management.

Why the first test must go past the first frame Copy Chapter

The two highest-risk, HW-unverified choices are both invisible on a single exchange:

1. Counter progression. The command counter must advance +2 per exchange (command uses
   CmdCtr, response uses CmdCtr+1), both sides starting at 0. A wrong step size still lets
   the first C=0 read succeed, then fails every later frame. So a passing test must span
   at least two MAC'd exchanges (a multi-READ full read already does — 60 pages ≈ 15
   READs) and, ideally, a secure write (the ACK-replacement MAC uses CmdCtr+1 over an
   empty body — a distinct code path).
2. MAC byte order / SV2 layout. A mismatch here fails the very first MAC. Any successful
   authenticated read is already strong evidence this is right.

Start with X1 and W1 below.

Equipment Copy Chapter

• One genuine MF0AES20 (MIFARE Ultralight AES) card with a known DataProtKey.
• A Proxmark3 — used only to (a) set SEC_MSG_ACT on the card and (b) read back raw memory
  to confirm expected contents. PM3 cannot act as a secure-messaging reader.
• One blank/factory UL-AES card (for the clone-to-blank regression, W2).
• For emulation tests, one of:
  • a second Flipper running this firmware (preferred — enables the self-contained
    cross-validation, group X, with no special reader), or
  • a real access reader / phone app that speaks UL-AES secure messaging.
• Debug logging enabled on the device under test (see below).

Setup — turn a card into a secure-messaging card Copy Chapter

While SEC_MSG_ACT is still off, secure messaging is not yet required, so an authenticated
plain write can set it. With Proxmark3:

1. Authenticate and dump the card; record the config pages (0x29–0x2D) and all data.
2. Set the SEC_MSG_ACT bit in the configuration (per datasheet §8.6 / Table "Random ID
   RID_ACT and Secure Messaging SEC_MSG_ACT"). Do not touch AUTH0/LOCK/AUTH_LIM —
   a wrong value there can brick or lock the card.
3. Re-select the card. From now on every authenticated session requires CMAC.
4. Confirm on the Flipper: read the card and open the full info view — the config decoder should
   show Secure messaging: on.

Keep the recorded plain dump — it is the ground truth to diff every read/write result against.

Observing which path executed Copy Chapter

Enable debug logs (CLI log at debug level, or Settings → System → Log level → Debug) and
watch for the markers added for this feature:

• Reader switched to CMAC read: full read of a SEC_MSG card succeeds (a plain read would
  NAK), and the counters appear — impossible over plain commands.
• UL-AES response MAC mismatch (ctr N) — reader rejected a card response MAC (should not
  appear in a healthy run; expected only in the tamper test).
• UL-AES command MAC mismatch, dropping session — emulator rejected a reader command MAC
  (expected only in E3).
• UL-AES secure-messaging write: re-auth failed, page N locked / ... card gone during re-activation — write-back adaptive fallback diagnostics.

A clean end-to-end run should show none of the mismatch/failure warnings.

Test matrix Copy Chapter

Record Pass/Fail + notes for each. A Fail on any MAC/counter test most likely points at
byte order, the +2 counter step, or the SV2 session-key layout — note exactly which exchange
number failed.

Group X — Flipper ↔ Flipper cross-validation (no external reader needed) — DO FIRST Copy Section

Group R — Reader reads a real secure-messaging card Copy Section

Group W — Reader writes back to a real secure-messaging card Copy Section

Group E — Emulate to an external reader (only if no 2nd Flipper; else X covers it) Copy Section

Group N — Regression (secure messaging must not disturb the plain paths) Copy Section

Sign-off Copy Chapter

Once X1 + W1 (or R1 + W1) pass with correct multi-exchange counter behaviour, the CMAC framing
is confirmed against real silicon and the feature is clear for a PR.

HW validation result (2026-08-13) Copy Chapter

Reader-side R1 + R2 + R4 + W1 PASS on a real MF0AES20 (1 Flipper + PM3 kit). Full CMAC read of all
60 pages with correct +2 command-counter progression across ~60 exchanges and zero MAC mismatches
(data matched the PM3 ground truth); the 3 counters read over CMAC; key pages 0x30–0x37 masked to
zero; CMAC write-back of data pages 0x04–0x27 MAC-wrapped with +2 write-counter progression, PM3
re-read confirming the overwrite. So the SV2 session key, CMAC byte order, and counter step are all
confirmed correct on silicon.

Bug found + fixed by this testing (commit ce541e129): the CMAC path never engaged because a real
card mutes (frame-wait Timeout) the first plain command in a secure session instead of sending a
Protocol NAK, and the read/write detection gates only accepted Protocol. Fixed by also accepting
Timeout. This is precisely the R1/W1 "must go past the first frame" gate doing its job — the failure
was invisible until a multi-frame exchange ran on real hardware.

Out of scope for this kit (need a 2nd Flipper / CMAC reader): X-group, E-group, W2/W3.

Documentation MultiConverter (`documentation/MultiConverter.md`) Copy Section

MultiConverter

Author: [theisolinearchip](https://github.com/theisolinearchip/flipperzero_stuff/tree/main/applications/multi_converter) Copy Chapter

An expanded version of my previous Dec/Hex Converter, this time allowing more units and a (probably poorly made from a design-point-of-view) selector mode
to swap between different unit groups.

I wrote it with the idea of expanding the unit list on mind, so adding new ones it's a matter of increasing an array of constants + defining the proper conversion functions.

(Actually the whole project is more about "making the framework" rather than providing ALL of the possible units : D)

Current conversions Copy Chapter

• Decimal / Hexadecimal / Binary
• Celsius / Fahrenheit / Kelvin
• Kilometers / Meters / Centimeters / Miles / Feet / Inches
• Degree / Radian

Usage Copy Chapter

Base keyboard allows numbers from 0 to F, being disabled (or not) according to the current selected unit.

Long press on 0 toggles a negative value; long press on 1 sets a decimal point (only if allowed by the current selected unit).

< removes the last character; # changes to Unit Select Mode.

Unit Select Mode Copy Section

Left and Right to swap between origin unit and destination unit (notice the destination will change according to the current selected origin).

Ok to save the changes and go back to the Display Mode; Back to go back without changing any unit.

Adding new units Copy Chapter

1. Add the new units in the MultiConverterUnitType enum on multi_converter_definitions.h (basic definitions header). Notice each enum element will be used as an array index later.

2. Increase the MULTI_CONVERTER_AVAILABLE_UNITS constant on multi_converter_units.h (units main header file).

3. Set a pair of functions for converting units and to check if a target unit is allowed to work with the destination unit (both on multi_converter_units.h
   and multi_converter_units.c; follow the already built-in units for more info).

4. Add the proper MultiConverterUnit structs for each new unit.

5. Add each new struct to the main multi_converter_available_units array.

And that's it! The system will fetch the new units and display it!

Known issues, TODO-list, etc. Copy Chapter

This is an initial release, so expect some bugs and issues (also I don't work with C that much, so there're probably lots of things that can be improved and/or changed!).

• I've noticed some small decimal variations when "going deep" with some units (like converting miles to centimeters and things like that); probably due to the precision-level required. Need to check that.
• Pending: improve overflow checks.
• The way some long numbers are shown could probably be improved to look fancier.
• Both origin and destination buffers are the same. The destination one could probably be longer in order to avoid certain overflow scenarios.
• The GUI needs improvement too: there's a whole widget/views system built in the Flipper that allows things like setting up keys, showing "Save/Back/Cancel" messages with
  callbacks and stuff like that. Didn't know anything about them, so I moved on with something more basic (which is probably fine since it's not a "very big project"); but
  a more "standard" way with the regular GUI stuff provided by the firmware will be interesting...
• More GUI stuff: the long click buttons for adding a decimal point / negative number aren't very clear on the view itself (I tried to add a small dot / dash symbol, but I think those are small enough to be a little bit confusing)

Documentation NRF24 (`documentation/NRF24.md`) Copy Section

flipperzero-nrf24

Author: [mothball187](https://github.com/mothball187/flipperzero-nrf24/tree/main/mousejacker) Copy Chapter

An NRF24 driver for the Flipper Zero device. The NRF24 is a popular line of 2.4GHz radio transceivers from Nordic Semiconductors. This library is not currently complete, but functional.

How to use

• Connect NRF24 to flipper using provided pinouts
• Open NRF24: Sniffer, and scan channels, switch between modes/channels using buttons
• When you got address -> Open NRF24: Mouse Jacker
• Select Address and open badusb file
• Done

Demo (YouTube)

Warning Copy Chapter

These apps are for educational purposes only. Please use this code responsibly and only use these apps on your own equipment.

Acknowledgments Copy Chapter

The NRF24 sniffing technique was discovered and shared by Travis Goodspeed in his blog.

The mousejack vulnerabilities were discovered and reported by Marc Newlin, see the blog for technical details.

Much of the driver code was inspired by RadioHead's Arduino library.
Much of the mousejack code was inspired by the Jackit project.

Pinout from from NoComp/Frog

Mousejacker / NRF24 pinout by UberGuidoZ

2/A7 on FZ goes to MOSI/6 on nrf24l01
3/A6 on FZ goes to MISO/7 on nrf24l01
4/A4 on FZ goes to CSN/4 on nrf24l01
5/B3 on FZ goes to SCK/5 on nrf24l01
6/B2 on FZ goes to CE/3 on nrf24l01
8/GND on FZ goes to GND/1 on nrf24l01
9/3V3 on FZ goes to VCC/2 on nrf24l01
IRQ/8 is left disconnected on nrf24l01

If the nRF module is acting a bit flakey, try adding a capacitor to the vcc/gnd lines!
I've not tried the Plus model so it may have a bigger need for a cap.
Otherwise, I haven't had any major issues.
Anything from a 3.3 uF to 10 uF should do. (Watch your positive/negative placement! Negative to ground.)
I learned if you wanna get fancy, include a 0.1 uF cap in parallel.
The 3.3 uF to 10 uF will respond to slow freq changes while the 0.1 uF will respond to the high freq switching spikes that the larger one cannot. That said, a single 10 uF will likely suffice for the Mousejack attack. ¯\_(ツ)_/¯

Documentation OTA (`documentation/OTA.md`) Copy Section

Flipper Zero OTA update process {#ota_updates}

Executing code from RAM Copy Chapter

In Flipper firmware, we have a special boot mode that loads a specially crafted system image into RAM and transfers control to it. The system image executing in RAM has full write access to Flipper's entire flash memory — something that's not possible when running main code from the same flash.

We leverage that boot mode to perform OTA firmware updates, including operations on a radio stack running on the second MCU core.

How does Flipper OTA work? Copy Chapter

Installation of OTA updates goes through 3 stages:

1. Backing up internal storage (/int) Copy Section

It is a special partition of Flipper's flash memory, taking up all available space not used by the firmware code. Newer versions of firmware may be of different size, and simply installing them would cause flash repartitioning and data loss.

So, before taking any action on the firmware, we back up the current configuration from /int into a plain tar archive on the SD card.

2. Performing device update Copy Section

The main firmware loads an updater image — a customized build of the main Flipper firmware — into RAM and runs it. Updater performs operations on system flash as described by an Update manifest file.

First, if there's a Radio stack image bundled with the update, updater compares its version with the currently installed one. If they don't match, updater performs stack deinstallation followed by writing and installing a new one. The installation itself is performed by proprietary software FUS running on Core2, and leads to a series of system restarts.

Then, updater validates and corrects Option Bytes — a special memory region containing low-level configuration for Flipper's MCU.

After that, updater loads a .dfu file with firmware to be flashed, checks its integrity using CRC32, writes it to system flash and validates written data.

3. Restoring internal storage and updating resources Copy Section

After performing operations on flash memory, the system restarts into newly flashed firmware. Then it performs restoration of previously backed up /int contents.

If the update package contains an additional resources archive, it is extracted onto the SD card.

Update manifest Copy Chapter

An update package comes with a manifest that contains a description of its contents. The manifest is in Flipper File Format — a simple text file, comprised of key-value pairs.

Mandatory fields Copy Section

An update manifest must contain the following keys in the given order:

• Filetype: a constant string, "Flipper firmware upgrade configuration".

• Version: manifest version. The current value is 2.

• Info: arbitrary string, describing package contents.

• Target: hardware revision for which the package is built.

• Loader: file name of stage 2 loader that is executed from RAM.

• Loader CRC: CRC32 of loader file. Note that it is represented in little-endian hex.

Optional fields Copy Section

Other fields may have empty values. In this case, updater skips all operations related to these values.

• Radio: file name of radio stack image, provided by STM.

• Radio address: address to install the radio stack at. It is specified in Release Notes by STM.

• Radio version: radio major, minor and sub versions followed by branch, release and stack type packed into 6 hex-encoded bytes.

• Radio CRC: CRC32 of radio image.

• Resources: file name of TAR archive with resources to be extracted onto the SD card.

• OB reference, OB mask, OB write mask: reference values for validating and correcting option bytes.

OTA update error codes Copy Chapter

We designed the OTA update process to be as fail-safe as possible. We don't start any risky operations before validating all related pieces of data to ensure we don't leave the device in a partially updated, or bricked, state.

Even if something goes wrong, updater allows you to retry failed operations and reports its state with an error code. These error codes have an [XX-YY] format, where XX encodes the failed operation, and YY contains extra details on its progress where the error occurred.

Building update packages Copy Chapter

Full package Copy Section

To build a full update package, including firmware, radio stack and resources for the SD card, run:

./fbt COMPACT=1 DEBUG=0 updater_package

Minimal package Copy Section

To build a minimal update package, including only firmware, run:

./fbt COMPACT=1 DEBUG=0 updater_minpackage

Customizing update bundles Copy Section

Default update packages are built with Bluetooth Light stack.
You can pick a different stack if your firmware version supports it, and build a bundle with it by passing the stack type and binary name to fbt:

./fbt updater_package COMPACT=1 DEBUG=0 COPRO_OB_DATA=scripts/ob_custradio.data COPRO_STACK_BIN=stm32wb5x_BLE_Stack_full_fw.bin COPRO_STACK_TYPE=ble_full

Note that COPRO_OB_DATA must point to a valid file in the scripts folder containing reference Option Byte data matching your radio stack type.

In certain cases, you might have to confirm your intentions by adding COPRO_DISCLAIMER=... to the build command line.

Building partial update packages Copy Section

You can customize package contents by calling scripts/update.py directly.
For example, to build a package only for installing BLE FULL stack:

scripts/update.py generate \
  -t f7 -d r13.3_full -v "BLE FULL 13.3" \
  --stage dist/f7/flipper-z-f7-updater-*.bin \
  --radio lib/stm32wb_copro/firmware/stm32wb5x_BLE_Stack_full_fw.bin \
  --radiotype ble_full

For the full list of options, check scripts/update.py generate help.

Documentation SentrySafe (`documentation/SentrySafe.md`) Copy Section

Sentry Safe plugin

Author: [H4ckd4ddy](https://github.com/H4ckd4ddy/flipperzero-sentry-safe-plugin) Copy Chapter

Flipper zero exploiting vulnerability to open any Sentry Safe and Master Lock electronic safe without any pin code.

Demo and Vulnerability described here

Usage Copy Section

• Start "Sentry Safe" plugin

• Place wires as described on the plugin screen
  (Flipper GPIO) 8/GND -> Black wire (Safe)
  (Flipper GPIO) 15/C1 -> Green wire (Safe)

• Press enter

• Open safe

Documentation SubGHzCounterMode (`documentation/SubGHzCounterMode.md`) Copy Section

SubGHz Counter Experimental Mode

Overview Copy Chapter

Experimental Counter Mode is an advanced feature that allows you to customize how rolling codes increment when transmitting SubGHz signals. Different protocols support different counter modes, which can be useful for specific cases, main purpose is to make clone of the original remote that will not conflict with original remote, so both Flipper and original remote can be used at same time in rolling code systems without desync or other issues.

Be aware, do not experiment with equipment you don't have access to, if you are not sure what mode works for you and can't reprogram your original remote to the receiver - do not use these modes!!!

In case you have access to the receiver and can do some tests, try some of these modes on your system and let us know how it works for you, in github issues or our communities, thanks!

How to Use Experimental Counter Mode Copy Chapter

To enable a specific counter mode, you need to manually edit your .sub file and add a CounterMode line.

Steps: Copy Section

1. Locate your .sub file (in /ext/subghz/ on your Flipper Zero SD card)
2. Open the file in a text editor
3. Add the following line at the end of the file:
   text Copy

   CounterMode: X

   Where X is the mode number (0, 1, 2, etc.)

Example .sub File: Copy Section

Filetype: Flipper SubGhz Key File
Version: 1
Frequency: 433920000
Preset: FuriHalSubGhzPresetOok650Async
Protocol: Nice FloR-S
Bit: 52
Key: AA AA AA AA AA AA AA
CounterMode: 1

Supported Protocols and Counter Modes Copy Chapter

1. Nice Flor S Copy Section

Mode 0 (Default):

• Standard - acts like regular remote
• Uses rolling counter multiplier from global settings (default +1)
• Counter increments based on the multiplier value (default +1)
• Resets to 0 when overflow occurs (> 0xFFFF)

Mode 1 (floxi2r):

• Counter sequence: 0x0001 / 0xFFFE
• For receiver model floxi2r

Mode 2 (ox2):

• Counter sequence: 0x0000 / 0x0001
• For receiver model ox2

2. Came Atomo Copy Section

Mode 0 (Default):

• Standard - acts like regular remote
• Uses rolling counter multiplier from global settings (default +1)
• Counter increments based on the multiplier value (default +1)
• Resets to 0 when overflow occurs (> 0xFFFF)

Mode 1:

• Counter sequence: 0x0000 / 0x0001 / 0xFFFE / 0xFFFF
• Works with external CAME RE432 receiver, may work with other type of receivers

Mode 2:

• Counter sequence: 0x807B / 0x807C / 0x007B / 0x007C
• Works with external CAME RE432 receiver, may work with other type of receivers

Mode 3:

• Counter freeze - do not increment

3. Alutech AT-4N Copy Section

Mode 0 (Default):

• Standard - acts like regular remote
• Uses rolling counter multiplier from global settings (default +1)
• Counter increments based on the multiplier value (default +1)
• Resets to 0 when overflow occurs (> 0xFFFF)

Mode 1:

• Counter sequence: 0x0000 / 0x0001 / 0xFFFE / 0xFFFF
• For receiver model MCSW-3.3M

Mode 2:

• Counter sequence: 0x0000 / 0x0001 / 0x0002 / 0x0003 / 0x0004 / 0x0005
• For other receiver boards

4. KeeLoq Copy Section

Mode 0 (Default):

• Standard - acts like regular remote
• Uses rolling counter multiplier from global settings (default +1)
• Counter increments based on the multiplier value (default +1)
• Resets to 0 when overflow occurs (> 0xFFFF)

Mode 1:

• Counter sequence: 0x0000 / 0x0001 / 0xFFFE / 0xFFFF
• Might work with some systems (let us know!)

Mode 2:

• Incremental mode: +0x3333 each transmission
• Adds 0x3333 (13107 in decimal) to counter each time
• Might work with Doorhan, seen in some "universal remotes"

Mode 3:

• Counter sequence: 0x8006 / 0x8007 / 0x0006 / 0x0007
• Might work with some systems like Hormann EcoStar

Mode 4:

• Counter sequence: 0x807B / 0x807C / 0x007B / 0x007C
• Might work with some systems like Nice Smilo

Mode 5:

• Counter sequence: 0x0000 / 0xFFFF
• Alternates between 0 and maximum value (65535)
• Might work with some systems (let us know!)

Mode 6:

• Counter freeze - do not increment

Mode 7:

• Incremental mode: +0x3333 5 times to current counter and return original value back adding +1 - 2 times - 7 signals in pack total
• Might work with Doorhan, seen in some "universal remotes"
• One click of Send button on flipper may bypass receiver counter, wait for full transmission

5. V2 Phoenix (Phox) Copy Section

Mode 0 (Default):

• Standard - acts like regular remote
• Uses rolling counter multiplier from global settings (default +1)
• Counter increments based on the multiplier value (default +1)
• Resets to 0 when overflow occurs (> 0xFFFF)

Mode 1 (ofex like):

• Counter sequence: 0x0000 / 0x0001 / 0xFFFE / 0xFFFF
• Verified as working

Mode 2 (0 - 4):

• Counter sequence: 0x0000 / 0x0001 / 0x0002 / 0x0003 / 0x0004
• Might work (let us know!)

Notes and Warnings Copy Chapter

Important Considerations: Copy Section

1. Default Behavior:

   • If you don't specify a CounterMode, Regular remote simulation (cnt +1) is used by default
   • Regular remote simulation is the standard mode and works with most cases

2. Protocol Compatibility:

   • Not all protocols support all counter modes
   • Using an unsupported mode number may result in unexpected behavior
   • Always test your configuration before relying on it

Troubleshooting: Copy Section

• If your file doesn't work after adding CounterMode:
  1. Double-check the syntax: CounterMode: X (with space after colon)
  2. Verify the mode number is valid for your protocol

Example Configurations Copy Chapter

Example 1: Nice Flor S with Mode 1 Copy Section

Filetype: Flipper SubGhz Key File
Version: 1
Frequency: 433920000
Preset: FuriHalSubGhzPresetOok650Async
Protocol: Nice FloR-S
Bit: 52
Key: 01 23 45 67 89 AB CD
CounterMode: 1

Example 2: KeeLoq with Mode 2 (+0x3333 (Doorhan)) Copy Section

Filetype: Flipper SubGhz Key File
Version: 1
Frequency: 433920000
Preset: FuriHalSubGhzPresetOok650Async
Protocol: KeeLoq
Bit: 64
Key: DE AD BE EF CA FE BA BE
Manufacture: Doorhan
CounterMode: 2

FAQ Copy Chapter

Q: Will this damage my remote or receiver?
A: Yes it may do that - depending on the receiver, it may desync your remote, be aware and don't experiment with equipment you don't have access to

Q: Which mode should I use?
A: Do not use those mods if you are not sure

Q: What happens if I use an invalid mode number?
A: Last mode from the list will be used

Q: Do I need to add CounterMode to every .sub file?
A: No, only add it if you need non-default behavior. Mode 0 is automatic if not specified.

Made for Unleashed FW, please mention source when copying

Documentation SubGHzRemotePlugin (`documentation/SubGHzRemotePlugin.md`) Copy Section

Sub-GHz Remote

UPDATE!!!!!!

Now you can create and edit map files directly on flipper, go into Sub-GHz Remote and click back button Copy Chapter

The SubGHz Remote Tool *requires* the creation of custom user map with `.txt` extension in the `subghz_remote` folder on the sdcard. Copy Section

If these files are not exist or not configured properly, **you will receive an error each time you try to select wrong file in the UniRF Tool**.

You can add as many `.txt` map files as you want, file name doesn't matter! Copy Chapter

Incorrect or unconfigured file error Copy Chapter

If the .txt file has not been properly configured, the following error will be thrown when trying to run the UniRF Remix app:

Config is incorrect.

Please configure map

Press Back to Exit

Setting up the `subghz_remote/example.txt` file: Copy Chapter

UP: /ext/subghz/Up.sub
DOWN: /ext/subghz/Down.sub
LEFT: /ext/subghz/Left.sub
RIGHT: /ext/subghz/Right.sub
OK: /ext/subghz/Ok.sub
ULABEL: Up Label
DLABEL: Down Label
LLABEL: Left Label
RLABEL: Right Label
OKLABEL: Ok Label

The UP/DOWN/LEFT/RIGHT/OK file locations must be set to the specific file you want mapped to that directional pad direction.

The ULABEL/DLABEL/LLABEL/RLABEL/OKLABEL variables should be set to the text to be displayed for each of the files set earlier.

Example: Copy Chapter

UP: /ext/subghz/Fan1.sub
DOWN: /ext/subghz/Fan2.sub
LEFT: /ext/subghz/Door.sub
RIGHT: /ext/subghz/Garage3.sub
OK: /ext/subghz/Garage3l.sub
ULABEL: Fan ON
DLABEL: Fan OFF
LLABEL: Doorbell
RLABEL: Garage OPEN
OKLABEL: Garage CLOSE

Notes Copy Chapter

• App Usage

  • Press a button to send the assigned capture file.
  • Press Back button to exit app.

• SubGHz Remote Map

  • File path should not have any spaces or special characters (- and _ excluded).
  • Labels are limited to 16 characters.
    • Why? This is to prevent overlapping elements on screen.
    • For example: If you set your label or file to WWWWWWWWWWWWWWW you'll be over the screen limits.

Documentation SubGHzRemoteProg (`documentation/SubGHzRemoteProg.md`) Copy Section

Using the Flipper as a new Sub-GHz remote

This guide is about making the Flipper into a brand new remote that you register in your gate, garage or blind receiver - the same way you would register a spare remote you bought in a shop.

It is not about cloning, and for the systems in this guide that matters:

• Rolling code (dynamic) remotes - BFT, Erreka, FAAC, Nice, CAME Atomo, Somfy, KeeLoq and the rest of this guide. Every press sends a new code from a counter, and the receiver only accepts a counter that moved forward. A clone shares the original's counter, so the two fight over it - whichever one you pressed last works, and the other needs several presses to catch up. That is why you make a new remote instead: it gets its own serial and counter, and lives alongside your original ones.
• Static (fixed) code remotes - CAME 12/24 bit, Nice Flo, Princeton, Marantec, Holtek, Roger, Gate TX and the other static protocols. There is no counter, so cloning is fine here - a copy is simply identical to the original and both keep working, forever, in any order. Just read the remote with SubGHz -> Read and save it. You do not need this guide for those, unless you want a remote with its own separate code.

So: if your remote is static, read and save it. If it is rolling code, find your system below.

Read this first Copy Chapter

What Add Manually does. SubGHz -> Add Manually builds a brand new remote with a randomly generated serial number and saves it as a file. Nothing is sent until you open that file and press a key. Your original remotes are not touched.

If your system is not in this guide, the Flipper may still support it. Open SubGHz -> Add Manually and scroll the list. If your brand is there, create a remote and follow the programming steps from your receiver's own manual - this guide only collects the ones people have already worked out. The full protocol list is in SubGHzSupportedSystems.md.

Read and Add Manually are different jobs. Read captures and replays a remote you already have. Add Manually creates a new remote that can be registered in the receiver. Many protocols support Read only.

The Flipper's keys are the original remote's buttons. When a remote file is open:

Which arrow is which depends on the protocol. Where a receiver wants a hidden or programming button - a recessed pin hole, two buttons held together, pads you bridge inside the case - the Flipper sends it as one single key press. Each section below tells you which key that is, and there is a full table in Programming / hidden button reference.

Hold the key down. The Flipper transmits only while a key is held. A quick tap often sends an incomplete code. Hold for 1-3 seconds unless a step says otherwise.

Timing matters. Most receivers open a programming window of 5, 10 or 30 seconds. Read the whole procedure before you start so you are not reading it while the window is closing.

[!WARNING]
On many receivers, holding the programming button too long erases every remote the receiver knows, not just one. If that happens you have to re-register all of your original remotes. When a step says "about 1 second", do not hold it for five.

[!NOTE]
A step ending in Done! has been confirmed working. A step ending in Done? comes from the manufacturer's manual but nobody has reported back yet - it should work, tell us in the issues tab if it does not.

Add Manually [Advanced] is the second menu entry, right under Add Manually. Use it when you need to type values in by hand instead of getting a random serial. After you pick the type it asks for SERIAL, BUTTON, COUNTER and, on protocols that use one, SEED - all in hex.

Find your system Copy Chapter

Not listed? See Programming / hidden button reference - it covers every other entry in the Add Manually menu.

Alutech AT4N (AN-Motors) Copy Chapter

• Create it: SubGHz -> Add Manually -> Alutech AT4N 433MHz

This is for boards with a display and F, CL, +, - buttons. If your board has a Learn button instead, use AN-Motors AT4.

1. Open your new remote file
2. Open the receiver box, find the F button and hold it for ~3 sec - the display shows Pr
3. Press F a few more times until the display shows Lr
4. With + / - pick a free remote number. A number that already has a remote on it shows a red dot in the bottom right corner
5. Press Send on the Flipper one time - the display flashes and a red dot appears next to that number
6. Hold F on the receiver board for ~3 sec to leave programming mode
7. Done!

Video walkthrough, also shows other board types (Russian)

AN-Motors AT4 Copy Chapter

• Create it: SubGHz -> Add Manually -> AN-Motors AT4 433MHz

This is for older boards with a Learn button. If your board has no Learn button but has F, CL, +, -, use Alutech AT4N instead.

1. Open your new remote file
2. Open the receiver box, find the Learn button and click it one time - the led turns on
3. Press Send on the Flipper one time - the led on the receiver board turns off
4. Press Send again - the led starts flashing, wait a couple of seconds until it turns off
5. Done!

Video walkthrough (Russian)

Aprimatic TR Copy Chapter

• Create it: SubGHz -> Add Manually -> KL: Aprimatic 433MHz
• Programming key: Right Arrow = 0xF (on the original remote this is all 4 buttons held together)

1. Open your new remote file
2. On your existing remote that already works with the receiver, push all 4 buttons at the same time
3. The receiver makes a continuous beep
4. Press Send on the Flipper and hold for ~2 sec
5. Wait until the receiver stops beeping
6. Done?

Beninca ARC (TO.GO) Copy Chapter

• Also sold as: TO.GO 2VA / TO.GO 4VA (previously TO.GO 2WV / 4WV) - receivers WB, WI, and receivers built into the control panel
• Create it: SubGHz -> Add Manually -> Beninca ARC 433MHz
• Programming key: Down Arrow = 0x0, the hidden button

On a 2 button original remote the hidden button means holding both buttons at once, which is awkward or impossible to do reliably. On the Flipper it is just the Down Arrow.

With a remote that already works - receivers WB / WI Copy Section

1. Stand close to the receiver
2. Open the file of the remote that already works, press Down Arrow and hold ~3 sec - the hidden function is now active (on an original remote its led blinks at this point)
3. Within 5 seconds press Send on that same remote, for the channel you want to share
4. Within 5 seconds open your new remote file and press Send - this is the button that will control that channel
5. The receiver leaves programming mode, test the new remote
6. Done?

With a remote that already works - receiver built into the control panel Copy Section

Here the hidden button has to be sent from both remotes:

1. Already working remote: Down Arrow, then Send within 5 seconds
2. New remote: Down Arrow, then Send within 5 seconds
3. Done?

[!NOTE]
ARC and HCS (Rolling Code) remotes cannot share one receiver. The first remote you save decides which type the receiver will accept from then on. Changing it needs a full receiver reset.

BFT Mitto Copy Chapter

• Create it: SubGHz -> Add Manually -> BFT Mitto 433MHz
• Programming key: Right Arrow = 0xF (on the original this is the pin hole on the back, or buttons 1+2 held together)

With a remote that already works Copy Section

1. Open your new remote file
2. Stand at least 3 meters from the receiver
3. Original remote: press the hidden button on the back with a pin or paper clip, OR press buttons 1 & 2 together, until the remote's led lights up
4. Original remote: briefly press the button that opens the device
5. On the Flipper, long press Right Arrow (0xF - Btn:F) for 3-5 sec
6. Press the button on the Flipper that you want to use for opening the device
7. Press Right Arrow again
8. Done?

With access to the receiver box Copy Section

1. Open your new remote file
2. Open the receiver board box
3. Watch this video first - it shows the board side of the procedure
4. On the Flipper, long press Right Arrow (0xF - Btn:F) for 3-5 sec. This acts exactly like holding buttons 1 & 2 on the original remote as shown in the video
5. Done?

Making a full clone instead (reads the Seed off your original) Copy Section

[!CAUTION]
This makes a copy that fights with your original remote. Both use the same counter, so whichever one you press last works and the other needs several presses to catch up. Your original may even stop working until it is re-registered at the receiver board.

Only do this if the original is broken or worn out and you want the Flipper to replace it. To simply add the Flipper as an extra remote, use one of the two procedures above instead.

1. Open SubGHz -> Read on your Flipper
2. On the original remote only: hold every button at the same time - on a 2 button remote hold both, on a 4 button remote hold the two in the top row - or press the hidden button on the back with a pin
3. You receive a signal. Open it and look at Fix: - it starts with F, for example F00F1C9B. The leading F is the button code, meaning "programming button pressed"
4. The Hop: value of that same signal is your Seed
5. Write the Hop value down and replace its first digit F with 0
6. Now press the button on your remote that you actually want to clone, and read that signal
7. Write down its Fix: value. Its first digit matches the Btn: shown for that signal
8. Create the remote: SubGHz -> Add Manually [Advanced] -> BFT Mitto 433MHz, then enter:
   • SERIAL - the Fix from step 7 with its first digit replaced by 0
   • BUTTON - the first digit of that Fix (the one you just replaced)
   • COUNTER - FF F9
   • SEED - the value from step 5
9. A high counter like FF F9 jumps past your original remote's current counter. That is what makes the clone work immediately - and what desyncs the original

Or edit a saved file instead of typing values in. Save the signal of your original remote (it will be listed as KL: Unknown), copy the file to a PC and add these two lines after the Key: ... line:

Seed: 0X XX XX XX
Manufacture: BFT

Replace the Xs with the digits of the Seed from step 4, save, and copy the file back to the Flipper. You now have an exact clone with the same counter - a few presses push it past the original, and from then on only one of the two works at a time.

CAME Atomo Copy Chapter

• Also sold as: TOP42R / TOP44R / TOP44RGR (806TS-0130)
• Create it: SubGHz -> Add Manually -> CAME Atomo 433MHz or CAME Atomo 868MHz

[!IMPORTANT]
When using CAME Atomo from the Flipper, always hold Send for at least 2 seconds. The Flipper transmits only while the key is held, and this protocol needs the time to get the whole code out.

With a remote that already works (or a copy of it on the Flipper) Copy Section

1. Open your new remote file
2. Stand at least 3 meters from the receiver
3. Original remote: press and hold the button that is bound to that receiver - the one you normally use - for about 10 seconds
4. You now have about 20 seconds to add the new remote
5. Long press Send on the Flipper in the new remote file for 3-4 sec and release - this registers it
6. Wait 20 seconds, then press and hold Send again - this should now operate the receiver
7. Done!

With access to the receiver box Copy Section

1. Open your new remote file
2. Open the receiver box and find the programming button for the channel you need. Some receivers have several independent channels - an RE432M / RE862M for example has two, each with its own remotes and buttons. Press 1 or 2 on the receiver board to enter programming mode for that channel
3. Long press Send on the Flipper for 3-4 sec and release - this registers the new remote
4. Press CLEAR on the receiver board once to leave programming mode, or just wait ~20 seconds and it leaves by itself
5. Done!

[!NOTE]
Static 12/24 bit CAME remotes and CAME TWEE remotes cannot trigger programming mode in the receiver, and they cannot be registered into a programming mode that an Atomo remote opened. Only Atomo remotes can. Static remotes have their own remote-to-remote cloning option, but it needs the first remote to be registered at the receiver board.

Video walkthrough (Russian)

Cardin S449 Copy Chapter

• Also sold as: S449 QZ1 / QZ2 / QZ4, TXQ449100 / TXQ449200 - receivers RCQ449
• Read with: modulation FM12K, not AM650
• Create it: SubGHz -> Add Manually -> KL: Cardin S449 433MHz
• Programming key: Right Arrow = 0xD (on the original this is the button in the small hole under the keys)

1. Open your new remote file
2. Stand 1-2 meters from the receiver
3. Open the file of the remote that already works, press Right Arrow and release it when the receiver makes a short beep
4. Press Send on that same remote one time - the receiver makes another short beep
5. Open your new remote file and press Send - the receiver makes 2 beeps in a row
6. Release the key - the receiver makes one longer beep
7. Wait at least 10 seconds, then try the new remote
8. Done?

If it fails, or if you hear a long beep before step 5, wait 20 seconds and start again from step 3.

DEA Mio Copy Chapter

• Create it: SubGHz -> Add Manually -> KL: DEA Mio 433MHz
• Programming key: Right Arrow = 0xF, the hidden button on the original remote

1. Open your new remote file
2. Send acts as one of the normal buttons of the remote - this is the one you register into the receiver
3. Right Arrow acts as the hidden button of the original remote
4. Follow your manufacturer's instructions for adding a new remote, using those two keys in place of the original remote's buttons

Ditec GOL4 Copy Chapter

• Also sold as: GOL4 / GOL4C - receivers BIXLG4, BIXLP2, BIXLS2, BIXR2
• Create it: SubGHz -> Add Manually -> Ditec GOL4 433MHz
• Programming key: Right Arrow = 0x0, the hidden button on the original remote

1. Open your new remote file
2. Open the receiver box, press and release the PRG button - the SIG led lights up and stays on
3. Press Send on the Flipper for the channel you want to store
4. The SIG led flashes while storing. When it is steady again you can add another remote
5. Storing ends 10 seconds after the last remote, or press PRG again to leave straight away
6. Done?

[!NOTE]
On some boards a jumper on the receiver has to be set before programming works at all. Check your receiver manual.

DoorHan Copy Chapter

• Create it: SubGHz -> Add Manually -> KL: DoorHan 433MHz or KL: DoorHan 315MHz

Finding your frequency first Copy Section

DoorHan uses either 315.00 or 433.92 MHz. To find out which, create a DoorHan remote on one of them, open it, press Send and watch the receiver. If you guessed right, the light on the receiver turns on while you hold the key and off when you release it. If nothing happens, try the other frequency.

You can also just read your existing remote in SubGHz -> Read.

With access to the receiver box Copy Section

Take the protective cover off and look at the buttons on the board:

• 4 buttons (Radio, Reverse, Auto, ...): press and hold Radio until the led lights up, then press Send on the Flipper 2 times - the led goes out
• 4 buttons (R, P, +, -) and a display: press R, then press Send on the Flipper 2 times, then wait about 10 seconds
• 4 buttons (+, -, F, TR) and a display: press TR, then press Send on the Flipper 2 times, then wait about 10 seconds
• Anything else: press and hold P for about 2 seconds until the led flashes, then press Send on the Flipper 2 times - the led goes out

In all cases, wait until the receiver returns to normal mode before testing.

With an original remote in your hand Copy Section

1. Open your new remote file
2. Stand 1-2 meters from the receiver board
3. On the old remote, press the second button (the lower one), keep holding it and also press the first button (the upper one). Hold both for 1 sec, then release
4. Press the working button on the old remote - the one you use to open the gate - hold for 1 sec and release
5. Steps 3 and 4 must be done within 5 seconds of each other. Do not hold the buttons too long, and do not rush either
6. The receiver beeps. You now have 10 seconds: press Send on the Flipper's new remote 2 times, holding for at least 1 sec each time
7. The receiver beeps again - the new remote is registered
8. Done!

With a copy of your original remote on the Flipper Copy Section

1. Open your existing (original) remote file
2. Stand 1-2 meters from the receiver board
3. Press Left Arrow (0x8) on the Flipper, hold 1 sec, release. Then press Right Arrow (0xA), hold 1 sec, release
4. Press the working button - the centre Send key - hold 1 sec and release
5. Steps 3 and 4 must be done within 5 seconds of each other. Do not hold too long, and do not rush
6. The receiver beeps. Press Back, open your new remote file - you have 10 seconds - and press Send 2 times, holding at least 1 sec each time
7. The receiver beeps again - the new remote is registered
8. Done!

Video walkthroughs (Russian) and second one

Erreka IRIS (NEW!) Copy Chapter

• Also sold as: IRIS IR02 / IR04 on 433.92 MHz, IR02/868 / IR04/868 on 868.35 MHz
• Create it: SubGHz -> Add Manually -> Erreka 433MHz or Erreka 868MHz
• Programming key: Right Arrow = 0xF (on the original this means bridging pins 1 and 5 of the 5 way connector, which sits exposed on the side of the remote - no need to open the case)

Erreka IRIS is a Roller Code remote - KeeLoq with a secret Seed. The manufacturer gives two ways to register a new remote, and both work from the Flipper.

[!NOTE]
Pick the entry that matches your receiver: Erreka 433MHz for IR02 / IR04, Erreka 868MHz for IR02/868 / IR04/868.

With access to the receiver box Copy Section

1. Open your new remote file
2. Open the receiver box and activate programming mode - usually a button on the receiver board, check your receiver manual
3. Press Send on the Flipper one time - the receiver beeps twice if the remote was stored
4. Repeat step 3 for any other remotes you want to add
5. Turn programming mode off on the receiver when you are done
6. Done!

With a remote that already works Copy Section

The original IRIS opens the programming window by bridging pins 1 and 5 of the 5 way connector exposed on the side of the case - that makes it transmit its Seed in the clear, and the receiver answers with a single beep. On the Flipper the same thing is just the Right Arrow, no wires needed.

The remote that opens the window has to be one the receiver already knows. That means either the first Flipper remote you registered with the receiver button above, or your original remote with its Seed recovered (see below).

1. Open the file of the Erreka remote that is already registered
2. Long press Right Arrow (0xF - Btn:F) for ~2 sec - the receiver beeps once, it is ready to store codes
3. You have 10 seconds: press Back and open your new remote file
4. Press Send - the receiver beeps twice if the remote was stored
5. If 10 seconds pass with nothing stored, the receiver leaves programming mode. Start again from step 2
6. Done?

If the new remote will not register Copy Section

Some installations give every remote the same Seed - the installer programmed them as a set. On those, a remote with a freshly generated random Seed is never accepted, no matter how exactly you follow the procedure above.

The fix is to keep the existing Seed and change only the serial, so you get a genuinely new remote that still belongs to the installation:

1. Get the Seed off a remote that already works - either way below
2. Create the remote with SubGHz -> Add Manually [Advanced] -> Erreka 433MHz (or Erreka 868MHz) and enter:
   • SERIAL - 0X XX XX XX, any value that is not one of your existing remotes. Keep the leading 0 - that nibble is the button, which the Advanced screen asks for separately
   • BUTTON - 02
   • COUNTER - 00 02
   • SEED - the Seed from step 1
3. Run the registration procedure again, either one

[!TIP]
Keep the leading zeros in the serial. Some systems have turned up using only the bottom 3 or 4 digits of the serial, so their remotes look like 00 00 0A BC rather than a full length number. If your installation is one of those, a long random serial may simply be refused.

Read one of your working remotes first and copy the shape of its serial - same number of significant digits, leading zeros kept - and only change the last digits to make it unique.

[!TIP]
If two of your original remotes read with the same Seed once you have recovered it, that is this kind of installation, and reusing the Seed is the right move rather than a workaround.

Getting the Seed off your original IRIS remote Copy Section

Erreka cannot be decoded without the Seed - a normal button press from an original remote reads as KL: Unknown until you know it. There are two ways to get it.

Option 1 - by shorting the pins and reading it. This is the quick one, the remote transmits the Seed in the clear, and the pins are on the outside of the case so nothing has to be taken apart:

1. Open SubGHz -> Read, set the frequency to 433.92 or 868.35 and the modulation to AM650
2. Bridge pins 1 and 5 of the 5 way connector on the side of your original IRIS remote
3. You receive a signal. The manufacturer will show as Unknown - that is expected, not an error. The Flipper cannot name the manufacturer yet precisely because it does not know the Seed
4. Open the signal and look at Fix: - it starts with F, the button code meaning "programming button pressed"
5. The Hop: value of that signal is your Seed, in the clear
6. From here you can either type it into Add Manually [Advanced] as above, or turn the captured signal into a working file: save it, copy it to a PC and add these two lines after the Key: ... line:

Seed: 0X XX XX XX
Manufacture: Erreka

Replace the Xs with the digits of the Seed from step 5, save, and copy the file back to the Flipper. It decodes now, and you can use it to open the programming window for new remotes.

Option 2 - with the Seed Capturer app, when you cannot bridge the pins or the remote has no connector. Pick Erreka and your frequency and press one button repeatedly - see Recovering a Seed with the Seed Capturer app for the whole procedure. This one needs a recovery step in qUnleashed afterwards, so option 1 is faster whenever you can reach the pins.

FAAC RC, XT Copy Chapter

• Also sold as: XT2 / XT4 433 RC / 868 RC, and the older RC coding
• Create it: SubGHz -> Add Manually -> KL: FAAC RC,XT 433MHz or KL: FAAC RC,XT 868MHz
• Programming key: Right Arrow = 0xB (on the original this is buttons 1+2 held together, the "master" press)

[!IMPORTANT]
These are KeeLoq, not SLH. Read your remote first: if the Flipper calls it KL: FAAC_RC,XT you are in the right place. If it says FAAC SLH, use FAAC SLH instead.

1. Open your new remote file
2. Stand close to the receiver
3. Open the file of the remote that already works, press Right Arrow and hold until the original remote's led would start flashing, about 1-2 sec, then release
4. While the window is open, press Send on that same remote for the button you want to copy
5. Open your new remote file and press Send
6. Repeat steps 3-5 for every other button you want
7. Done?

[!NOTE]
Only a master remote can hand its system code over. On an original remote you can tell them apart by the led - a short blink before it goes steady means master, steady straight away means slave. A slave cannot be used for this, so with a slave you have to register the new remote at the receiver instead.

FAAC SLH Copy Chapter

• Create it: SubGHz -> Add Manually -> FAAC SLH 433MHz or FAAC SLH 868MHz
• Programming key: Up Arrow sends the programming signal

With access to the receiver box Copy Section

1. Open your new remote file
2. Open the receiver box and find the programming button on the receiver board
3. Hold Up Arrow on the Flipper to send the programming signal, and at the same time press and hold the programming button on the receiver board
4. The led on the receiver board goes on, off, on, off, then on again
5. Release everything
6. Press Send on the Flipper a couple of times, holding each press for 1-3 seconds
7. Done!

Video walkthrough

With a master remote - no need to open the box Copy Section

FAAC has a procedure for registering new remotes from an existing master remote, and the Flipper can take part in it. First you read the Seed off the master.

1. Open SubGHz -> Read, set the frequency to 868.35 or 433.92 and the modulation to AM650
2. Hold two buttons on the original master remote until its led turns on
3. Click the one button you want the Seed for. The Seed is different for every button on the original remote
4. You receive a signal on the read screen. Open it and read the Seed for the button you used
5. Create the remote: SubGHz -> Add Manually [Advanced] -> FAAC SLH 433MHz (or 868), then enter:
   • SERIAL - 0A 0R RR RR, replacing each R with any digit you like
   • BUTTON - 06
   • COUNTER - 00 00 00 02
   • SEED - the Seed you read in step 4
6. The Flipper now acts as a new remote. Press Send a couple of times near the receiver to register it
7. Done!

If neither of those is possible Copy Section

Two situations leave you stuck:

• The receiver's remote programming is disabled. Some installers switch it off, and then nothing you send will register a new remote
• Your remote is a slave, not a master. Only a master can transmit the programming code. On an original remote, press any button and watch the led - a short blink before it goes steady means master, steady straight away means slave

In both cases the only remaining route is a clone of a remote the receiver already knows, and that needs the Seed. Get it with the Seed Capturer app, then build the clone with the original remote's SERIAL and BUTTON instead of your own.

[!TIP]
SERIAL and BUTTON together make up the Fix value you see when reading a signal, and where the button sits inside Fix depends on the protocol:

• FAAC SLH and Genius: BUTTON is the last digit of Fix. SERIAL is the rest, with a 0 put in front.
• KeeLoq protocols (BFT, Erreka, DoorHan, Cardin and the other KL: entries): BUTTON is the first digit of Fix. SERIAL is that same Fix with the first digit replaced by 0.

Genius (SLH) Copy Chapter

• Also sold as: Echo TX2 433 SLH / Echo TX4 433 SLH / KILO TX2 / TX4 / JLC / Amigo
• Create it: SubGHz -> Add Manually -> Genius 433MHz or Genius 868MHz
• Programming key: Up Arrow sends the programming signal

Genius SLH is the same frame as FAAC SLH with its own manufacturer key, so the FAAC SLH procedures apply exactly as written - both the receiver button one and the master remote one.

1. Create the remote from the Genius entry for your frequency
2. Follow the FAAC SLH steps

If the receiver's remote programming is disabled, or your remote is a slave and cannot send the programming code, the Seed route applies here too - capture it with the Seed Capturer app (pick Genius) and follow If neither of those is possible under FAAC SLH.

[!IMPORTANT]
Do not confuse this with KL: Genius TX4RC 433M.. The RC models are KeeLoq, not SLH, and they have their own section. If you are not sure which you have, read the remote first and see what the Flipper calls it.

Genius TX4RC (Bravo / Echo) Copy Chapter

• Also sold as: Echo TX2 433 RC / Echo TX4 433 RC / TE443H Bravo
• Create it: SubGHz -> Add Manually -> KL: Genius TX4RC 433M.
• Programming key: Right Arrow = 0xB, the programming mode button of the original remote

1. Open your new remote file
2. Open the receiver box and press SW1 for channel 1 or SW2 for channel 2 - LED1 / LED2 lights up and stays on, that is learning mode
3. Within 10 seconds press Send on the Flipper and hold for at least 1 sec
4. The led blinks twice - the remote is stored
5. The receiver stays in learning mode, so you can add more remotes by repeating step 3. Press SW1 / SW2 again to leave, or it leaves by itself 10 seconds after the last remote
6. Done?

Hormann EcoStar Copy Chapter

• Also sold as: RSC2 / RSE2 / RSZ1 on 433.92 MHz - EcoStar Liftronic / Portronic drives
• Create it: SubGHz -> Add Manually -> KL: Hor. EcoStar 433MHz
• Programming key: Down Arrow = 0x6 - note this one is on Down, not Right

1. Open your new remote file
2. Find the clear programming button on the drive, usually underneath the motor, and hold it for ~1 sec - the indicator led on the motor starts flashing slowly
3. Press Send on the Flipper and hold for ~2 sec - the motor led speeds up
4. Press Send again and hold for ~2 sec - the motor led flashes very fast then goes out. The remote is programmed
5. Done?

[!WARNING]
Holding that clear button for ~5 seconds erases every remote the drive knows, not just one.

Jarolift Copy Chapter

• Also sold as: TDEF radio tube motors - TDRC / TDRCE remotes
• Create it: SubGHz -> Add Manually -> Jarolift 433MHz

The keys are already mapped to the original remote's buttons:

Learn is a single code. On the original remote you produce it by holding Up + Down together and then pressing Stop - on the Flipper it is one key press.

With access to the motor head Copy Section

1. Open your new remote file
2. Press the learning button on the motor head - the motor vibrates briefly, it is now in learning mode for 5 seconds
3. If you cannot reach that button, disconnect the motor from the mains and reconnect it - it enters learning mode automatically for 5 seconds
4. Within those 5 seconds press Up Arrow (Learn) on the Flipper
5. The motor vibrates again - the code was learned
6. Done!

With a remote that already works Copy Section

1. Open your new remote file
2. On the already working remote, hold Up + Down together, then press Stop 8 times - the motor vibrates briefly
3. Within 5 seconds press Up Arrow (Learn) on the Flipper
4. The motor vibrates again - the code was learned
5. Done?

[!TIP]
If the already working remote is also on your Flipper, step 2 is just Up Arrow (Learn) on that remote's file.

KingGates Stylo 4k Copy Chapter

• Also sold as: Stylo 2K / Stylo 4K (10S001) - receivers Fred, Myo
• Create it: SubGHz -> Add Manually -> KingGates Stylo4k 433M.

There is no separate programming button on this one. The four keys are simply the four channels of the original remote:

1. Open your new remote file
2. Open the receiver box. On a Fred 2 channel receiver the led colour tells you the channel - green is channel 1, red is channel 2
3. Press the receiver button once for channel 1 (green) or twice for channel 2 (red) - this starts learning mode
4. Within 5 seconds press Send on the Flipper for ~1 sec
5. The led turns off then on again - the remote was learned
6. Learning mode ends after 5 seconds with no signal, or press the receiver button again to leave
7. Done?

Mhouse Copy Chapter

• Also sold as: GTX4 / GTX4C / TX3 / TX4 - also Moovo and Nice Home ECCO
• Create it: SubGHz -> Add Manually -> KL: Mhouse 433MHz
• Programming key: Right Arrow = 0xF, the extra (hidden) button of the original remote

With access to the receiver box Copy Section

1. Open your new remote file
2. Press and hold the P1 button on the receiver until the P1 led stays on, then release
3. Press Send on the Flipper and hold until the P1 led flashes 3 times
4. Release the key. This registers all buttons of the remote at once (Nice "mode 1")
5. Wait 10 seconds before testing the new remote
6. Done?

With a remote that already works Copy Section

Mhouse is the same Nice receiver family as Nice Smilo, so the procedure is the same:

1. Stand close to the receiver
2. Open your new remote file, press and hold Send for at least 5 sec, then release
3. On the already working remote, press and slowly release its button 3 times
4. Open your new remote file again, press Send for 1 sec and release
5. Wait 10 seconds before testing the new remote
6. Done?

Nice Flor S Copy Chapter

• Create it: SubGHz -> Add Manually -> Nice FloR-S 433MHz