Flipper Zero SDK — это набор инструментов для сборки прошивки и разработки собственных приложений под микроконтроллер STM32WB55, и первое, что стоит проверить перед началом работы, — наличие установленного Python 3.8+ и Git, без которых ни fbt, ни ufbt просто не запустятся. Большинство ошибок вроде command not found или падения сборки на этапе загрузки тулчейна связаны именно с неподготовленным окружением, а не с самим SDK.
В этой статье разберём, чем отличаются два официальных инструмента сборки, как развернуть среду разработки на Windows, Linux и macOS, как собрать и запустить первое приложение формата FAP (Flipper Application Package) и как отлаживать код через GPIO-отладчик. Материал рассчитан на разработчиков, знакомых с основами C, но впервые работающих с экосистемой Flipper.
Что такое Flipper Zero SDK и как он устроен
Под термином Flipper Zero SDK обычно понимают набор заголовочных файлов, библиотек и систему сборки, которые предоставляет команда Flipper Devices в официальном репозитории прошивки flipperzero-firmware. Строго говоря, отдельного «SDK-пакета» как у мобильных платформ здесь нет: вся разработка ведётся либо внутри дерева исходников прошивки, либо через микро-инструмент ufbt, который подтягивает нужные компоненты SDK автоматически под версию прошивки вашего устройства.
Архитектурно прошивка Flipper построена на FreeRTOS, а приложения взаимодействуют с системой через слои API: furi (ядро, потоки, таймеры, примитивы синхронизации) и furi_hal (аппаратная абстракция — GPIO, Sub-GHz, NFC, инфракрасный порт, дисплей). Понимание этого двухуровневого разделения критично: прямое обращение к регистрам микроконтроллера в обход HAL — частая причина нестабильной работы сторонних приложений.
Внешние приложения распространяются в формате .fap — это динамически загружаемые модули, которые не требуют перепрошивки устройства. Они копируются на microSD-карту и запускаются из меню Apps. Именно этот формат рекомендуется для начинающих: риск «окирпичить» устройство минимален.
fbt и ufbt: два инструмента сборки
В экосистеме Flipper существует два официальных инструмента, и выбор между ними зависит от задачи. fbt (Flipper Build Tool) — полная система сборки, которая работает внутри клонированного репозитория прошивки и позволяет собирать саму прошивку, встроенные приложения и внешние FAP. ufbt (micro Flipper Build Tool) — лёгкая обёртка, которая скачивает только необходимые части SDK и предназначена исключительно для разработки внешних приложений без клонирования всего дерева исходников.
| Критерий | fbt | ufbt |
|---|---|---|
| Назначение | Сборка прошивки и приложений | Только внешние FAP-приложения |
| Размер загрузки | Полный репозиторий прошивки | Только компоненты SDK |
| Установка | Клонирование репозитория git | pip install ufbt |
| Прошивка устройства | Поддерживается | Не поддерживается |
| Для кого | Контрибьюторы, кастомные сборки | Авторы сторонних приложений |
Если ваша цель — написать своё приложение и запустить его на устройстве, начинайте с ufbt: настройка занимает минуты, а инструмент сам определяет версию прошивки подключённого Flipper и подтягивает совместимый SDK. Полный fbt нужен, когда вы правите код самой прошивки или собираете кастомный образ.
Установка окружения: пошаговая инструкция
Ниже — универсальный порядок действий для ufbt, который работает на Windows (в PowerShell), Linux и macOS. Предварительно убедитесь, что установлены Python 3 и менеджер пакетов pip.
Установка самого инструмента выполняется одной командой:
python3 -m pip install --upgrade ufbtПосле установки создайте пустую папку для будущего приложения, перейдите в неё и выполните инициализацию SDK. При первом запуске ufbt скачает компоненты, соответствующие каналу обновления вашей прошивки:
ufbt updateДля полного варианта с fbt потребуется клонировать репозиторий и запустить сборку из его корня:
git clone --recursive https://github.com/flipperdevices/flipperzero-firmware.git
cd flipperzero-firmware
./fbt
☑️ Готовность среды разработки
⚠️ Внимание: версия SDK должна соответствовать версии прошивки на устройстве. Приложение, собранное под другой major-версией API, либо не запустится, либо будет работать нестабильно. Команда
ufbt updateбез подключённого устройства подтянет SDK релизного канала — уточняйте канал флагами, если у вас установлена dev-сборка или сторонняя прошивка.
Создание первого приложения FAP
Каркас внешнего приложения состоит минимум из двух файлов: application.fam (манифест с метаданными) и исходника на C с точкой входа. В манифесте указываются appid, имя, тип приложения, категория и требуемые зависимости. Точка входа — функция с согласованной сигнатурой, которую система вызывает при запуске.
Типичный минимальный код приложения использует furi для управления жизненным циклом и GUI-модуль прошивки для вывода на экран. Чтобы не выдумывать точные сигнатуры под конкретную версию API, корректнее всего взять шаблон из официальных примеров: ufbt умеет генерировать скелет приложения командой ufbt create, а в репозитории прошивки есть каталог с примерами плагинов, которые гарантированно собираются под соответствующую версию SDK.
Сборка и заливка на подключённое устройство выполняются одной командой:
ufbt launchЭта команда компилирует приложение, копирует .fap на устройство по USB и сразу запускает его — удобный цикл для итеративной разработки. Если устройство не подключено, используйте просто ufbt для сборки: готовый файл появится в подкаталоге dist, откуда его можно вручную скопировать на SD-карту в папку apps.
Структура API: furi, furi_hal и GUI
Разработчику важно понимать, какие возможности открывает SDK и через какие модули к ним обращаться. Ниже — основные блоки, с которыми вы будете работать чаще всего.
- 🧵 furi — потоки (FuriThread), очереди сообщений, таймеры, мьютексы, строки FuriString, логирование через FURI_LOG.
- 📟 furi_hal — доступ к GPIO, Sub-GHz трансиверу, NFC, RFID 125 кГц, инфракрасному приёмопередатчику, питанию и вибромотору.
- 🖥️ GUI — canvas для отрисовки, готовые view-модули: меню, диалоги, текстовые поля, виджеты.
- 💾 Storage — работа с файлами на SD-карте: чтение, запись, диалоги выбора файла.
- 🔔 Notification — системные уведомления: звук, вибрация, подсветка, последовательности.
Ключевой принцип: приложение не владеет аппаратурой единолично. Например, чтобы работать с Sub-GHz, нужно «захватить» соответствующий ресурс через HAL и освободить его при выходе — иначе другие приложения и системные сервисы получат ошибку доступа. Тот же подход действует для GPIO и инфракрасного порта.
Почему приложение падает при выходе в меню
Наиболее частая причина — неосвобождённые ресурсы: поток не остановлен, мьютекс не отдан, захват HAL не снят, выделенная память не освобождена. Прошивка отслеживает утечки: при некорректном завершении вы увидите системное сообщение об ошибке. Проверяйте, что каждый malloc имеет парный free, а каждый acquire — парный release, включая пути выхода по ошибке.
Отладка и логирование
Самый доступный способ отладки — логирование. Макросы семейства FURI_LOG_I, FURI_LOG_E выводят сообщения, которые видны при подключении к устройству через CLI: запустите ufbt cli и выполните команду log — поток логов пойдёт в терминал. Этого достаточно для большинства задач прикладного уровня.
Для пошаговой отладки с точками останова потребуется аппаратный отладчик, подключаемый к GPIO-пинам Flipper (SWD-интерфейс). Официально поддерживается связка с отладчиком и GDB через openocd; в fbt есть цели для запуска отладочной сессии. Конкретная распиновка и поддерживаемые адаптеры описаны в официальной документации разработчика — сверяйтесь с ней, так как назначение пинов может уточняться между ревизиями.
⚠️ Внимание: работа с SWD-отладкой и прошивкой по низкоуровневым интерфейсам — зона повышенного риска. Ошибочные действия при записи во flash могут потребовать восстановления устройства через режим DFU. Перед экспериментами убедитесь, что вы знаете процедуру восстановления прошивки для вашей ревизии устройства по официальной документации.
Типичные ошибки при работе с SDK
Разберём проблемы, с которыми чаще всего сталкиваются при первой настройке и сборке. Большинство из них диагностируется за несколько минут, если знать, куда смотреть.
- 🔧 ufbt не находит устройство — проверьте кабель (нужен кабель с линиями данных, а не только питание), права доступа к USB на Linux (правила udev) и то, что Flipper не занят другим приложением вроде qFlipper.
- 📦 Ошибка несовместимости API при запуске FAP — версия SDK не совпадает с прошивкой; выполните
ufbt updateс подключённым устройством и пересоберите приложение. - 🐍 pip не ставит ufbt или ругается на версию Python — обновите Python и pip, на Windows проверьте, что Python добавлен в PATH.
- 💥 Приложение собирается, но падает при запуске — смотрите логи через
ufbt cli; типичные причины — обращение к незахваченному ресурсу HAL или переполнение стека потока (увеличьте stack size в манифесте). - 🧱 git clone обрывается — репозиторий прошивки содержит сабмодули; используйте флаг
--recursive, при обрыве выполнитеgit submodule update --init.
Если ошибка не воспроизводится из списка выше, полезно собрать заведомо рабочий пример из официального репозитория. Успешная сборка примера означает, что проблема в вашем коде, а не в окружении; провал на примере указывает на неисправность среды — тогда переустановка ufbt и повторный ufbt update обычно решают вопрос.
Публикация и распространение приложений
Готовое приложение можно распространять как отдельный файл .fap — пользователю достаточно скопировать его на SD-карту. Существует и каталог приложений, поддерживаемый сообществом, куда разработчики могут отправить свой проект: сборка для каталога выполняется автоматически под несколько каналов прошивки, поэтому важно, чтобы код не использовал устаревшие или недокументированные вызовы API.
При публикации обратите внимание на корректное заполнение манифеста: осмысленный appid, версия, краткое описание и категория упрощают жизнь пользователям и сопровождающим каталога. Также хорошей практикой считается открытый репозиторий с исходниками и инструкцией по сборке через ufbt — это снимает вопросы доверия к бинарному файлу.
⚠️ Внимание: приложения, работающие с радиоэфиром (Sub-GHz, NFC-эмуляция), должны использоваться в рамках законодательства вашей страны. Техническая возможность SDK не отменяет ограничений на частоты, мощность и перехват чужих сигналов — проверяйте местные нормы перед экспериментами с передачей.
FAQ: частые вопросы о Flipper Zero SDK
Нужно ли перепрошивать Flipper, чтобы установить своё приложение?
Нет. Внешние приложения в формате .fap копируются на SD-карту и запускаются из меню Apps без изменения прошивки. Перепрошивка требуется только если вы модифицируете саму систему через fbt.
На каком языке пишутся приложения для Flipper Zero?
Основной язык — C, именно под него спроектированы API furi и furi_hal. Существуют экспериментальные варианты с другими языками от сообщества, но официально поддерживаемый и документированный путь — C.
Чем ufbt отличается от fbt и что выбрать новичку?
ufbt — лёгкий инструмент только для внешних приложений, ставится через pip и сам скачивает нужный SDK. fbt — полная система сборки прошивки из клонированного репозитория. Новичку, пишущему своё первое приложение, достаточно ufbt.
Приложение не запускается после обновления прошивки — что делать?
Скорее всего, изменилась версия API. Подключите устройство, выполните ufbt update, чтобы подтянуть SDK под новую прошивку, пересоберите приложение и установите его заново. Если код использует устаревшие вызовы, компилятор укажет на них при сборке.
Можно ли разрабатывать без физического устройства?
Частично: собрать приложение и проверить логику на уровне компиляции можно без Flipper. Но полноценный запуск и отладка требуют устройства — эмулятора аппаратной части с полной поддержкой периферии официально не существует.