Шаблон разработки на Zig для Flipper Zero с автоматизированным конвейером сборки, интеграцией SDK и кросс-компиляцией для ARM Cortex-M4. Поддерживает протоколы Sub-GHz, NFC, RFID и Infrared.
Современный, готовый к использованию шаблон для разработки приложений Flipper Zero с использованием языка программирования Zig. Этот проект предоставляет оптимизированную систему сборки, которая интегрирует Zig с SDK Flipper Zero, позволяя разработчикам писать типобезопасные и безопасные по памяти приложения для платформы Flipper Zero.
Этот шаблон соединяет мощную систему сборки и возможности языка Zig с набором для разработки прошивки Flipper Zero. Он обрабатывает сложную интеграцию между кросскомпиляцией Zig для ARM Cortex-M4 и SDK Flipper, предоставляя чистую отправную точку для пользовательских приложений.
ufbt (неофициальный инструмент сборки) для упаковки FAP-файловШаблон использует двухэтапный процесс сборки:
Этап сборки Zig: Компилирует исходный код Zig в объектные файлы ARM Cortex-M4 (app.o)
thumb с моделью CPU cortex-m4eabihf (Встраиваемый двоичный интерфейс приложений, аппаратная плавающая запятая)ReleaseSmall для минимального размера бинарного файлаЭтап упаковки UFBT: Связывает объектные файлы с SDK и упаковывает в формат .fap
ufbtufbt (устанавливается в ~/.ufbt)Шаблон предварительно настроен для ARM64 macOS с путем к цепочке инструментов ARM:
~/.ufbt/toolchain/arm64-darwin/arm-none-eabi/include
Если вы работаете на другой платформе, возможно, потребуется изменить путь arm_libc_include в build.zig:31 в соответствии с расположением вашей цепочки инструментов.
Установите UFBT:
python3 -m pip install --upgrade ufbt
ufbt update
Клонируйте или скачайте этот шаблон:
git clone https://github.com/yourusername/flipper-template.git
cd flipper-template
Инициализируйте свой проект:
zig build init
Этот интерактивный скрипт запросит у вас:
my_custom_app)Скомпилируйте исходный код Zig в объектный файл:
zig build
Это создаст zig-out/bin/app.o со всем скомпилированным кодом приложения.
Соберите и упакуйте полное приложение:
zig build fap
Это запускает полный конвейер:
ufbt для связывания с SDK.fap в каталоге dist/Запустите приложение непосредственно на подключенном Flipper Zero:
zig build launch
Это собирает, упаковывает и передает приложение через USB, а затем автоматически запускает его.
flipper-template/
├── application.fam # Манифест приложения Flipper (метаданные, точки входа)
├── build.zig # Конфигурация системы сборки Zig
├── build.zig.zon # Манифест пакета Zig
├── icon.png # Иконка приложения (рекомендуется 10x10px)
├── setup.sh # Интерактивный скрипт инициализации проекта
├── src/
│ └── root.zig # Основной исходный код приложения
└── zig-out/ # Артефакты сборки (генерируются)
└── bin/
└── app.o # Скомпилированный объектный файл
src/root.zig: Точка входа, содержащая функцию start() и логику приложенияapplication.fam: Конфигурация Flipper (ID приложения, категория, зависимости, размер стека)build.zig: Определяет цели компиляции, пути к SDK и команды сборкиШаблон включает пример "Hello World", демонстрирующий основные API Flipper:
// Импорт функций SDK Flipper
const flipper = @cImport({
@cInclude("furi.h");
@cInclude("gui/gui.h");
@cInclude("gui/canvas.h");
@cInclude("gui/view_port.h");
});
// Точка входа приложения (должна называться "start")
export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 {
// Инициализация GUI viewport
const gui = flipper.furi_record_open("gui");
const view_port = flipper.view_port_alloc();
// Установка обратных вызовов и пользовательского интерфейса
// ... (см. src/root.zig для полной реализации)
// Цикл событий
_ = flipper.furi_thread_flags_wait(1, flipper.FuriFlagWaitAny, flipper.FuriWaitForever);
return 0;
}
Система сборки автоматически настраивает пути включения для:
Все заголовки доступны через @cImport() в вашем коде Zig.
SDK Flipper использует соглашения вызова ARM AAPCS:
start())Убедитесь, что экспортированные функции соответствуют ожидаемому соглашению вызова:
export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32
export fn draw_callback(canvas: ?*Canvas, ctx: ?*anyopaque) callconv(.{ .arm_aapcs_vfp = .{} }) void
Некоторые заголовки SDK содержат конструкции, которые C-транслятор Zig не может обработать (например, объединения с непрозрачными типами в input/input.h). Для таких случаев вручную объявляйте внешние функции:
extern fn view_port_input_callback_set(
view_port: ?*flipper.ViewPort,
callback: ?*const fn (?*anyopaque, ?*anyopaque) callconv(.{ .arm_aapcs_vfp = .{} }) void,
context: ?*anyopaque
) callconv(.{ .arm_aapcs = .{} }) void;
Проблема: unable to find header 'furi.h'
~/.ufbtufbt update для установки заголовков SDKПроблема: undefined reference to 'view_port_alloc'
zig build fap вместо zig build для завершения линковкиПроблема: No Flipper device found
Проблема: Приложение вылетает при запуске
stack_size в application.fam или проверьте сигнатуры функцийИзмените addFlipperDefines() в build.zig для настройки макросов препроцессора:
obj.root_module.addCMacro("FAP_VERSION", "\\\"1.0\\\"");
obj.root_module.addCMacro("CUSTOM_DEFINE", "value");
Измените уровень оптимизации в build.zig:11:
const optimize = b.standardOptimizeOption(.{
.preferred_optimize_mode = .ReleaseFast, // или .ReleaseSmall, .Debug
});
Шаблон нацелен на Flipper Zero с STM32WB55 (ARM Cortex-M4F). Для портирования на другие ARM-устройства измените build.zig:4-9:
const target = b.resolveTargetQuery(.{
.cpu_arch = .thumb,
.cpu_model = .{ .explicit = &std.Target.arm.cpu.cortex_m4 },
.os_tag = .freestanding,
.abi = .eabihf,
});
Вклад приветствуется! Этот шаблон направлен на упрощение разработки на Zig для Flipper Zero. Если вы столкнулись с проблемами совместимости SDK или у вас есть предложения по улучшению процесса сборки, пожалуйста, откройте issue или pull request.
Этот проект лицензирован по лицензии MIT - подробности см. в файле LICENSE.
Примечание: Это неофициальный шаблон и не имеет отношения к Flipper Devices Inc. Всегда тщательно тестируйте приложения перед развертыванием на рабочих устройствах.