ufbt против fbt: сколько ответственности берёт на себя тот, кто собирает прошивку Flipper Zero

За просьбой «собрать прошивку для Flipper Zero» скрываются как минимум четыре непохожие задачи. Одному нужно собственное приложение, другому — правка в системном коде, третьему форк со снятыми ограничениями Sub-GHz, а четвёртому собирать не требуется вообще ничего. Выбирать между ними вслепую бессмысленно: сначала стоит разобраться, что уже лежит внутри и какой инструментарий приезжает вместе с исходниками.

Материал построен на замерах со стенда: официальный репозиторий на теге 1.4.3, Debian в контейнере с 2 vCPU и 7 ГБ RAM. Количественные оценки посчитаны по дереву исходников и файлу api_symbols.csv из SDK, размеры взяты с настоящей сборки, приложение на C реально скомпилировано.

Что стоковая прошивка умеет без единой правки

С этого места разумно начинать, поскольку добрая половина вопросов «а можно ли собрать прошивку, чтобы…» касается уже реализованного.

За десятью пользовательскими приложениями из applications/main стоят не десять пунктов меню, а десять аппаратных подсистем, каждая со своим набором протоколов:

Рядом трудятся 16 фоновых сервисов (gui, storage, notification, power, bt, cli, loader, rpc, dolphin, region, crypto, input и другие), 10 экранов настроек, 27 отладочных стендов и 13 примеров приложений, пригодных как каркас для своего.

Границы, заданные железом

Носителем прошивки служит STM32WB55 — двухъядерный чип, где прикладная часть достаётся Cortex-M4, а радиостек Bluetooth крутится на Cortex-M0+. Границы прописаны в линкер-скриптах targets/f7 жёстко: всего 1024 КБ флеш-памяти, прикладному процессору отходит всё до адреса радиостека 0x080D7000, то есть 860 КБ.

Собранный с COMPACT=1 DEBUG=0 образ занял у меня 750 КБ, оставив в запасе около 110 КБ. Вот почему флаги сборки — не косметика: отладочный вариант заметно объёмнее, а на форке с десятком лишних встроенных приложений этот резерв тает на глазах.

Оперативная память устроена так же тесно: 192 КБ в RAM1 на всё сразу — саму прошивку, ваши приложения и графику, плюс пара блоков по 10 КБ для обмена с радиопроцессором. По этой причине stack_size в манифесте и задаётся явным числом байт, а не по принципу «сколько понадобится».

Что из этого видит ваш код

Статической линковки с прошивкой у .fap нет — обращение идёт через таблицу экспортируемых символов. Таблица приезжает вместе с SDK файлом targets/f7/api_symbols.csv, и посмотреть её можно вручную:

head -3 ~/.ufbt/current/sdk_headers/f7_sdk/targets/f7/api_symbols.csv
# entry,status,name,type,params
# Version,+,87.1,,
# Header,+,applications/drivers/subghz/cc1101_ext/cc1101_ext_interconnect.h,,

# сколько всего чего
cut -d, -f1 ~/.ufbt/current/sdk_headers/f7_sdk/targets/f7/api_symbols.csv | sort | uniq -c

Для версии 1.4.3 набор такой: 3531 функция, 311 переменных, 319 заголовков, версия API — 87.1. По подсистемам мощность распределена неравномерно.

Ядро furi — 29 заголовков. Внизу лежит FreeRTOS, но наружу выведен свой слой: потоки (furi_thread), мьютексы, семафоры, очереди сообщений, потоковые буферы, флаги событий, таймеры, цикл событий (furi_event_loop), шина pubsub, реестр сервисов record. Добавьте сюда furi_string со счётчиком ссылок — при 192 КБ оперативной памяти голый char* надоедает быстро.

Слой железа — 47 заголовков furi_hal_*, 488 функций. Периферия доступна напрямую: gpio, spi, i2c, adc, pwm, serial, usb (с cdc, hid, ccid), nfc, subghz, infrared, rfid, ibutton, bt, power, speaker, vibro, light, rtc, random, crypto, flash, sd, region. Задачи вида «подёргать ногой и послушать ответ» закрываются здесь, без пересборки прошивки.

Интерфейс — 17 готовых элементов. submenu, menu, button_menu, button_panel, dialog_ex, popup, widget, text_input, byte_input, number_input, text_box, variable_item_list, file_browser, loading, empty_screen и валидаторы. Писать меню с нуля незачем: экран монохромный, 128×64, и всё типовое давно отрисовано.

Четыре уровня и где вы окажетесь

Уровень 0. Убедиться, что собирать не надо

Канал обновлений раздаёт официальные прошивки и одновременно служит самым честным ответом на вопрос о версиях:

curl -s https://update.flipperzero.one/firmware/directory.json \
  | python3 -c 'import json,sys;[print(c["id"], c["versions"][0]["version"]) for c in json.load(sys.stdin)["channels"]]'

development       a55e3939
release-candidate 1.4.2-rc
release           1.4.3

В стабильном канале сейчас 1.4.3 — релиз от 5 декабря 2025 года. Когда цель формулируется как «обновиться» или «поставить готовый чужой форк», исходники не нужны: минуты работы qFlipper или веб-апдейтера достаточно, а образ придёт подписанным и проверенным.

Уровень 1. Приложение .fap за пять команд

Файлы .fap лежат на SD-карте самостоятельно и в прошивку не входят. Их сборкой занимается ufbt — усечённая система сборки, качающая готовый SDK вместо полного дерева исходников.

python3 -m pip install --upgrade ufbt
mkdir gig_hello && cd gig_hello
ufbt create APPID=gig_hello

SDK приезжает на первом запуске — строкой Using version: 1.4.3 и распаковкой в ~/.ufbt/current. Результат ufbt create — ровно пять файлов:

gig_hello.c                  исходник приложения
application.fam              манифест сборки
gig_hello.png                иконка 10×10, 1 бит
images/.gitkeep              каталог под ассеты
.github/workflows/build.yml  готовый CI на GitHub Actions

Манифест — обыкновенный вызов на Python, генерируемый дословно так:

App(
    appid="gig_hello",  # Must be unique
    name="App gig_hello",  # Displayed in menus
    apptype=FlipperAppType.EXTERNAL,
    entry_point="gig_hello_app",
    stack_size=2 * 1024,
    fap_category="Examples",
    fap_icon="gig_hello.png",  # 10x10 1-bit PNG
    fap_icon_assets="images",
)

Существенных полей три. В entry_point записано имя стартовой функции на C, обязанное совпасть с объявленным в исходнике. Через stack_size задаётся размер стека потока приложения: двух килобайт хватит на простую отрисовку, работа с NFC или файлами потребует больше. От fap_category зависит подкаталог на SD-карте — допустимы Sub-GHz, RFID, NFC, Infrared, GPIO, iButton, Bluetooth, USB, Games, Tools, Media, Debug, Examples.

Возможности шаблонного gig_hello.c исчерпываются записью в лог. Заменим его минимальным приложением с экраном и выходом по кнопке — код собран и проверен на SDK 1.4.3:

#include <furi.h>
#include <gui/gui.h>
#include <input/input.h>

static void gig_hello_draw_callback(Canvas* canvas, void* ctx) {
    UNUSED(ctx);
    canvas_clear(canvas);
    canvas_set_font(canvas, FontPrimary);
    canvas_draw_str(canvas, 2, 12, "GIG Community");
    canvas_set_font(canvas, FontSecondary);
    canvas_draw_str(canvas, 2, 28, "Built from source");
    canvas_draw_str(canvas, 2, 40, "Press Back to exit");
}

static void gig_hello_input_callback(InputEvent* event, void* ctx) {
    FuriMessageQueue* queue = ctx;
    furi_message_queue_put(queue, event, FuriWaitForever);
}

int32_t gig_hello_app(void* p) {
    UNUSED(p);

    FuriMessageQueue* queue = furi_message_queue_alloc(8, sizeof(InputEvent));

    ViewPort* view_port = view_port_alloc();
    view_port_draw_callback_set(view_port, gig_hello_draw_callback, NULL);
    view_port_input_callback_set(view_port, gig_hello_input_callback, queue);

    Gui* gui = furi_record_open(RECORD_GUI);
    gui_add_view_port(gui, view_port, GuiLayerFullscreen);

    InputEvent event;
    bool running = true;
    while(running) {
        if(furi_message_queue_get(queue, &event, FuriWaitForever) == FuriStatusOk) {
            if(event.type == InputTypeShort && event.key == InputKeyBack) {
                running = false;
            }
        }
    }

    gui_remove_view_port(gui, view_port);
    furi_record_close(RECORD_GUI);
    view_port_free(view_port);
    furi_message_queue_free(queue);

    return 0;
}

Финальный порядок освобождения ресурсов не произволен: вьюпорт снимается с GUI прежде, чем освобождается. Переставьте две строки местами — и отрисовка продолжится по уже освобождённой структуре. Компилятор не возразит, а устройство перезагрузится прямо в руках.

Сборка запускается вызовом ufbt без параметров:

$ ufbt
    CC      /tmp/fz/gig_hello.c
    LINK    /root/.ufbt/build/gig_hello_d.elf
    FAP     /root/.ufbt/build/gig_hello.fap
    INSTALL /tmp/fz/dist/gig_hello.fap
    APPCHK  /root/.ufbt/build/gig_hello.fap
            Target: 7, API: 87.1

Итог — dist/gig_hello.fap на 2200 байт. Наибольшую ценность во всём выводе представляет строка APPCHK.

ufbt update --channel=dev      # или rc, или release
ufbt update --branch=1.4.3     # конкретная ветка SDK
ufbt update --local=/path/to/flipper-z-f7-sdk-local.zip   # SDK из своей сборки

Заливка с немедленным стартом на подключённом устройстве:

ufbt launch

Файл уходит на SD-карту в подкаталог из fap_category, после чего приложение запускается. Условие одно — закрытый qFlipper, последовательный порт он занимает монопольно.

Каким путём приложения попадают на устройство

Написание собственного кода — способ отнюдь не самый распространённый. Путей всего четыре, и отличает их не удобство установки, а версия API, под которую собран бинарник.

Каталог на 437 приложений

Хостится каталог по адресу lab.flipper.net; установка идёт либо из браузера, либо через мобильное приложение. Разбивку по разделам публикует открытый API, так что цифры проверяются самостоятельно:

curl -s 'https://catalog.flipperzero.one/api/v0/category?limit=50' \
  | python3 -c 'import json,sys;[print(f"{c[\"name\"]:12} {c[\"applications\"]}") for c in json.load(sys.stdin)]'

Распределение говорит само за себя: на GPIO приходится 112 приложений, на Games — 102, на Tools — 93, тогда как весь раздел iButton состоит из двух. Каталог вырос вокруг внешних модулей и утилит — радиочасть закрывать нечем, её и так покрывают стоковые приложения.

Своё приложение туда добавляется без загрузки исходников. В репозиторий flipper-application-catalog отправляется единственный файл applications/<Категория>/<app_id>/manifest.yml, содержащий ссылку на ваш репозиторий и конкретный коммит:

sourcecode:
  type: git
  location:
    origin: https://github.com/example/test.git
    commit_sha: bf7019d16d7b50f6a98cc3abdac38c53952a4f30
short_description: Test app
description: "@README.md"
changelog: "@./docs/changelog.md"
screenshots:
  - screenshots/ss0.png

Сборкой .fap занимается инфраструктура каталога. Требования не обсуждаются: id пишется строчными буквами и повторяет appid из application.fam, category обязана отвечать каталогу с манифестом, у version формат «мажор.минор», а обновление с номером не выше прежнего отклоняют. Для скриншотов предписана штатная функция qFlipper.

Чужой репозиторий как источник

Изрядная доля интересного до каталога не доходит и остаётся на GitHub. Порядок действий неизменен: клонировать, перейти в каталог приложения, вызвать ufbt.

Проверял на официальном наборе flipperzero-good-faps — это 15 приложений под присмотром самой команды Flipper:

git clone --depth 1 https://github.com/flipperdevices/flipperzero-good-faps.git
cd flipperzero-good-faps/weather_station
ufbt          # собрать
ufbt launch   # залить на устройство и запустить

Правок не потребовалось нигде, собралось всё. Замеренные размеры:

Компанию им составляют dap_link (Flipper в роли отладочного зонда CMSIS-DAP), avr_isp_programmer (программатор AVR), spi_mem_manager (чтение и запись SPI-флешек), air_mouse (мышь по гироскопу), mass_storage, music_player, nfc_rfid_detector, video_game_module_tool, flip_tdi, air_arkanoid.

Отчего каталожное приложение молчит на форке

Правило сформулировано в официальной документации предельно сжато: мажорная версия API у .fap сверяется загрузчиком с мажорной версией API прошивки, и при несовпадении запуска не происходит. Мажорный номер увеличивают при удалении функции из экспорта или смене сигнатуры, минорный — при добавлении новой.

Практическое следствие обычно выясняется опытным путём: каталог компилирует бинарники под API официальной прошивки, из-за чего на форке с его собственными изменениями часть приложений оттуда не стартует. По этой же причине форки таскают свои паки приложений прямо внутри прошивки — совпадение версий иначе не гарантировать.

Уровень 2. Прошивка целиком: fbt

Репозиторий клонируется полностью, вместе с сабмодулями. Ключ --recursive обязателен: без него сборка развалится на недостающих библиотеках.

git clone --recursive https://github.com/flipperdevices/flipperzero-firmware.git
cd flipperzero-firmware
./fbt COMPACT=1 DEBUG=0 updater_package

Первый вызов ./fbt со стороны похож на простой: проверяются tar и curl, затем качается архив тулчейна и распаковывается в ./toolchain внутри репозитория. Ничего системного не устанавливается — компилятор соседствует с исходниками, и удаление одного каталога сносит всю сборочную среду. У меня приехал arm-none-eabi-gcc (GCC) 12.3.1.

Чистая пересборка после ./fbt -c заняла на двух ядрах 144 секунды. Для 700 МБ исходников результат неожиданный — но львиную долю объёма составляют сабмодули, до целевого образа не доходящие.

Роль флагов COMPACT и DEBUG

Умолчания прописаны в fbt_options.py:

TARGET_HW = 7
COMPACT = 0
DEBUG = 1
DIST_SUFFIX = "local"
FIRMWARE_APP_SET = "default"
FBT_TOOLCHAIN_VERSIONS = (" 12.3.", " 13.2.")

Значит, по умолчанию собирается отладочная некомпактная версия — крупнее и медленнее, но пригодная для пошаговой отладки. Повседневной прошивке нужна обратная пара: COMPACT=1 DEBUG=0.

COMPACT = 1
DEBUG = 0
DIST_SUFFIX = "gig"
FIRMWARE_APP_SET = "default"

Артефакты и пути доставки

В dist/f7-C после моей сборки оказалось 11 файлов, разбор приведён на схеме выше. Каталог находится без запоминания суффиксов:

ls -1 dist/*/ | head -20

Доставить результат на устройство можно тремя путями, неравнозначными между собой.

./fbt flash_usb_full     # по USB, с ресурсами и радиостеком
./fbt flash              # через SWD-программатор: ST-Link, J-Link, CMSIS-DAP, Wi-Fi devboard

Третий вариант ручной: dist/f7-C/flipper-z-f7-update-local.tgz скармливается qFlipper через «Install from file». При неуверенности в сборке предпочтителен именно он — целостность пакета проверяется до начала записи во флеш.

Цели fbt: полный рабочий набор

Под ./fbt скрывается не одна команда, а несколько десятков целей. Ниже те, что действительно используются.

Когда пересобирать прошивку не хочется, есть работа с одним приложением:

./fbt launch APPSRC=applications_user/my_app   # собрать, залить и запустить
./fbt build APPSRC=applications_user/my_app    # только собрать
./fbt -c fap_my_app                            # почистить артефакты этого приложения

Что ещё приезжает вместе со сборочной системой

Кроме целей, в комплекте идёт несколько вещей, о существовании которых обычно узнают случайно.

Оболочка с тулчейном. Получить arm-none-eabi-gcc, gdb и objdump в своём шелле можно без правки путей:

source scripts/toolchain/fbtenv.sh     # Linux и macOS
. `./fbt -s env`                       # то же самое короче
scripts\toolchain\fbtenv.cmd           # Windows

Переменные окружения, меняющие поведение сборки:

Ключи командной строки. Глобальный define пробрасывается через --extra-define=NAME=VALUE; --extra-ext-apps=app1,app2 вынуждает собрать перечисленные приложения внешними; --options другой_файл.py подменяет конфигурацию целиком; --proxy-env=VAR1,VAR2 прокидывает переменные окружения в дочерние процессы, поскольку по умолчанию fbt окружение санирует.

Отладка на железе. Поддержку получили фирменный Wi-Fi devboard, ST-Link второй и третьей ревизий, J-Link, а также произвольные зонды с поддержкой CMSIS-DAP — сюда попадает и Raspberry Pi Debug Probe. По цели debug происходит сборка, заливка и запуск gdb, где символы уже подставлены; описание регистров периферии в формате SVD лежит там же.

CLI: доступ к подсистемам без строчки кода

Об этой части забывают чаще прочих, а она открывает все подсистемы вообще без программирования. Консоль поднимается по USB:

./fbt cli          # из репозитория
ufbt cli           # из проекта приложения

Базовый набор команд, зарегистрированных в прошивке: help, ?, !, device_info, info, uptime, date, free, free_blocks, top, log, sysctl, power, sleep, vibro, led, input, gpio, i2c, storage, crypto, bt, js, factory_reset, update, unit_tests, start_rpc_session, reload_ext_cmds.

За радиочасть отвечают внешние плагины, которые ищутся в /ext/apps_data/cli/plugins. Не увидели новую команду сразу после установки приложения — помогает reload_ext_cmds. Самое полезное:

JavaScript там, где C избыточен

Внутри прошивки работает js_app — интерпретатор на базе mJS. Ступень эта промежуточная — выше пунктов меню, но ниже разработки на C. Скрипт достаточно положить на SD-карту, а дальше запустить его либо из меню, либо консольной командой js.

Набор модулей: badusb, gpio, serial, storage, notification, math, event_loop, flipper, gui, tests. Причём gui здесь не декоративный — скрипту доступны те же элементы, что и коду на C: submenu, menu, button_menu, button_panel, dialog, popup, widget, text_input, byte_input, number_input, text_box, file_picker, loading, empty_screen.

В репозитории лежат 18 примеров — каталог applications/system/js_app/examples: от badusb_demo.js и uart_echo_8e1.js до event_loop.js, gpio.js, storage.js, gui.js. Разовую автоматизацию это покрывает с запасом при несопоставимо более низком пороге входа.

Уровень 3. Форк и его цена

Momentum и Unleashed собираются теми же целями fbt: ./fbt updater_package даёт TGZ, ./fbt flash_usb_full заливает напрямую. Технически всё сводится к клонированию другого репозитория и запуску знакомых команд.

Расходится наполнение. Ниже сведено то, что проекты заявляют в собственных описаниях.

Механизм Asset Packs из Momentum пригодится знать и тем, кто форк ставить не собирается: паки хранятся на карте по пути /ext/asset_packs/<Имя>/ с подкаталогами Anims и Icons, выбираются в настройках прямо на устройстве, а собираются скриптом scripts/asset_packer.py из репозитория. Анимации, иконки и шрифты, таким образом, меняются вовсе без пересборки прошивки.

Плата за это тоже есть. Всякое лишнее встроенное приложение откусывает от упомянутых 110 КБ флеш-резерва, а собственная версия API приводит к тому, что .fap из официального каталога может отказаться стартовать.

Модули расширения: что подключают снаружи

Выведенные наружу восемь линий GPIO — по сути полноценная шина расширения, через которую устройство получает недостающее на плате. Отсюда и перевес каталога в сторону раздела GPIO со 112 приложениями.

Внешняя радиочасть учтена в прошивке штатно: в дереве исходников присутствует applications/drivers/subghz/cc1101_ext, а SDK экспортирует семейство subghz_devices. Ни форка, ни патчей внешний CC1101 не требует.

Данные: сигналы, дампы, оформление

Существует и целый пласт экосистемы, к коду отношения не имеющий, — файлы, которые просто кладутся на карту памяти.

Инфракрасные базы. Крупнейшая общая коллекция ИК-дампов — репозиторий Flipper-IRDB. Клонировал и пересчитал: 8901 файл .ir, разложенный по 47 разделам, от телевизоров, кондиционеров и проекторов до вентиляторов, пылесосов, автомагнитол, камер, каминов и подъёмников. Место назначения — /ext/infrared, открывается штатным приложением.

Сводные коллекции. В UberGuidoZ/Flipper собран объёмный архив файлов, документации и дампов сразу всех видов: Sub-GHz, NFC, ИК, скрипты BadUSB, графика. Роль указателя по остальному играет список awesome-flipperzero с прошивками, приложениями, базами и модулями и краткими пояснениями к ним.

Оформление. Кроме Asset Packs от Momentum, сообщество сделало отдельные утилиты — менеджеры анимаций и конвертеры из GIF в формат анимаций Flipper. Монохромный экран 128×64 сам по себе исключает существование «тяжёлой» графики.

Когда устройство перестало включаться

Новость хорошая: прошивка находится в основном контроллере STM32WB55, загрузчик там отдельный, и угробить его пользовательской сборкой практически нереально. Порядок восстановления описан в официальной документации и сводится к двум комбинациям клавиш.

Когда DFU-устройство в системе не появляется, причина уже не в прошивке, а в кабеле или питании. Проверьте заведомо исправным кабелем, желательно не «зарядным».

Первоисточники

• flipperdevices/flipperzero-firmware — официальный репозиторий и README
• documentation/fbt.md — полный список целей и переменных окружения
• documentation/AppManifests.md — поля манифеста application.fam
• documentation/AppsOnSDCard.md — категории и запуск приложений с SD
• flipperdevices/flipperzero-ufbt — установка, команды и переключение каналов SDK
• update.flipperzero.one/firmware/directory.json — официальный канал обновлений
• Firmware recovery — официальная документация по восстановлению
• Next-Flip/Momentum-Firmware
• DarkFlippers/unleashed-firmware
• RogueMaster/flipperzero-firmware-wPlugins
• Flipper Lab — официальный каталог приложений
• flipper-application-catalog — требования к manifest.yml
• flipperzero-good-faps — приложения от команды Flipper
• Wi-Fi Developer Board — официальная документация
• Video Game Module — официальная документация
• Asset Packs — вики Momentum
• Lucaslhm/Flipper-IRDB — база инфракрасных дампов
• djsime1/awesome-flipperzero — индекс по экосистеме