NishantJoshi00/flipper-template

来源: https://github.com/NishantJoshi00/flipper-template

Flipper Zero Zig 模板

一个现代、可用于生产的模板，用于使用 Zig 编程语言开发 Flipper Zero 应用程序。该项目提供了一个精简的构建系统，将 Zig 与 Flipper Zero SDK 集成，使开发者能够为 Flipper Zero 平台编写类型安全、内存安全的应用程序。

概述

该模板将 Zig 的强大构建系统和语言特性与 Flipper Zero 固件开发套件连接起来。它处理了 Zig 的 ARM Cortex-M4 交叉编译与 Flipper SDK 之间的复杂集成，为自定义应用程序提供了一个清晰的起点。

主要特性

• 原生 Zig 支持：完全使用 Zig 编写 Flipper 应用程序，利用其编译时安全保证和 C 互操作性
• 自动化构建流水线：与 ufbt（非官方构建工具）无缝集成，用于打包 FAP 文件
• 跨平台开发：在 macOS、Linux 以及 Zig 支持的其他平台上均可工作
• SDK 集成：预配置的包含路径和编译器标志，支持完整的 Flipper SDK（F7 目标）
• 交互式设置：引导式初始化脚本，用于自定义应用元数据
• 快速启动：内置构建、打包和部署到 Flipper 设备的命令

架构

该模板使用两阶段构建过程：

1. Zig 构建阶段：将 Zig 源码编译为 ARM Cortex-M4 目标文件（app.o）

   • 目标：thumb 架构，cortex-m4 CPU 模型
   • ABI：eabihf（嵌入式应用程序二进制接口，硬浮点）
   • 优化：ReleaseSmall，以获得最小二进制体积

2. UFBT 打包阶段：将目标文件与 SDK 链接并打包为 .fap 格式

   • 由官方 Flipper 构建工具链处理
   • 生成可部署的应用包

前提条件

必需工具

• Zig：0.15.1 或更高版本（下载 (https://ziglang.org/download/)）
• UFBT：非官方 Flipper 构建工具（安装指南 (https://github.com/flipperdevices/flipperzero-ufbt)）
• Python 3：运行 ufbt 命令所需
• Flipper Zero SDK：由 ufbt 自动管理（安装到 ~/.ufbt）

平台特定设置

macOS

该模板已为 ARM64 macOS 预配置了 ARM 工具链路径： ~/.ufbt/toolchain/arm64-darwin/arm-none-eabi/include

如果您使用其他平台，可能需要调整 build.zig:31 中的 arm_libc_include 路径，以匹配您的工具链位置。

安装

1. 安装 UFBT： bash python3 -m pip install --upgrade ufbt ufbt update

2. 克隆或下载此模板： bash git clone https://github.com/yourusername/flipper-template.git cd flipper-template

3. 初始化您的项目： bash zig build init

   此交互式脚本会提示您输入：

   • 应用 ID（例如 my_custom_app）
   • 显示名称（在 Flipper 菜单中显示）
   • 描述
   • 作者名称
   • GitHub 仓库 URL

使用

构建应用程序

将 Zig 源码编译为目标文件： bash zig build

这将创建 zig-out/bin/app.o，其中包含所有已编译的应用代码。

创建 FAP 包

构建并打包完整的应用程序： bash zig build fap

这会执行完整的流水线：

1. 将 Zig 源码编译为目标文件
2. 调用 ufbt 与 SDK 链接
3. 在 dist/ 目录中生成 .fap 文件

部署到 Flipper

直接在已连接的 Flipper Zero 上启动应用程序： bash 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 路径和构建命令

开发指南

最小应用结构

该模板包含一个演示核心 Flipper API 的“Hello World”示例：

``zig // 导入 Flipper SDK 函数 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 视口 const gui = flipper.furi_record_open(“gui”); const view_port = flipper.view_port_alloc();

// 设置回调和 UI
// ...（完整实现见 src/root.zig）

// 事件循环
_ = flipper.furi_thread_flags_wait(1, flipper.FuriFlagWaitAny, flipper.FuriWaitForever);

return 0;

} ``

SDK 集成

构建系统会自动配置以下包含路径：

• 核心 SDK：FURI（Flipper 通用运行时接口）
• HAL：STM32WB55 的硬件抽象层
• 标准库：mbedTLS、nanopb、mlib
• 协议库：Sub-GHz、NFC、RFID、红外
• 外设 API：GPIO、SPI、I2C、UART

所有头文件均可通过 Zig 代码中的 @cImport() 访问。

调用约定说明

Flipper SDK 使用 ARM AAPCS 调用约定：

• AAPCS：标准 ARM 过程调用（例如 start() 入口点）
• AAPCS-VFP：带浮点/向量支持（例如回调）

确保导出的函数与预期的调用约定匹配： zig export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 export fn draw_callback(canvas: ?*Canvas, ctx: ?*anyopaque) callconv(.{ .arm_aapcs_vfp = .{} }) void

处理 SDK 导入

某些 SDK 头文件包含 Zig 的 C 翻译器无法处理的结构（例如 input/input.h 中带有不透明类型的联合体）。对于这些情况，手动声明外部函数：

zig 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'

• 原因：UFBT SDK 未安装或 ~/.ufbt 路径不正确
• 解决方法：运行 ufbt update 安装 SDK 头文件

问题：undefined reference to 'view_port_alloc'

• 原因：目标文件未正确与 SDK 链接
• 解决方法：使用 zig build fap 而不是 zig build 完成链接

部署问题

问题：No Flipper device found

• 原因：设备未连接或处于 DFU 模式
• 解决方法：通过 USB 连接并确保设备已在主菜单解锁

问题：应用启动时崩溃

• 原因：栈溢出或调用约定不正确
• 解决方法：增加 application.fam 中的 stack_size，或验证函数签名

高级配置

编译器标志

修改 build.zig 中的 addFlipperDefines() 以调整预处理宏： zig obj.root_module.addCMacro("FAP_VERSION", "\\\"1.0\\\""); obj.root_module.addCMacro("CUSTOM_DEFINE", "value");

优化设置

在 build.zig:11 中更改优化级别： zig const optimize = b.standardOptimizeOption(.{ .preferred_optimize_mode = .ReleaseFast, // 或 .ReleaseSmall、.Debug });

目标架构

该模板以 Flipper Zero 的 STM32WB55（ARM Cortex-M4F）为目标。要移植到其他 ARM 设备，调整 build.zig:4-9： zig const target = b.resolveTargetQuery(.{ .cpu_arch = .thumb, .cpu_model = .{ .explicit = &std.Target.arm.cpu.cortex_m4 }, .os_tag = .freestanding, .abi = .eabihf, });

贡献

欢迎贡献！该模板旨在简化 Flipper Zero 的 Zig 开发。如果您遇到 SDK 兼容性问题或有改进构建过程的建议，请提交 issue 或 pull request。

改进领域

• 支持 Windows 工具链路径
• 自动 SDK 版本检测
• 集成 Flipper 应用目录
• 更多 SDK 封装抽象

资源

• Flipper Zero 开发者文档 (https://developer.flipper.net/)
• UFBT 仓库 (https://github.com/flipperdevices/flipperzero-ufbt)
• Zig 语言参考 (https://ziglang.org/documentation/master/)
• Flipper SDK API 参考 (https://github.com/flipperdevices/flipperzero-firmware/tree/dev/documentation)

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• Flipper Devices 团队提供的 UFBT 工具链
• Zig 社区提供的 ARM 交叉编译支持
• Flipper Zero SDK 的贡献者

注意：这是一个非官方模板，与 Flipper Devices Inc. 无关。在部署到生产设备之前，务必彻底测试应用程序。