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 或更高版本（下载）
• UFBT：非官方 Flipper 构建工具（安装指南）
• 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：

   root@kitploit:~

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. 克隆或下载此模板：

   root@kitploit:~

   git clone https://github.com/yourusername/flipper-template.git
   cd flipper-template
   

3. 初始化你的项目：

   root@kitploit:~

   zig build init
   

   这个交互式脚本会提示你输入：

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

使用

构建应用程序

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

zig build

这将在 zig-out/bin/app.o 生成包含所有编译的应用代码的目标文件。

创建 FAP 包

构建并打包完整的应用程序：

zig build fap

这会运行完整的流程：

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

部署到 Flipper

在连接的 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 路径和构建命令

开发指南

最小应用结构

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

// 导入 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：带浮点/向量支持（例如回调函数）

确保导出的函数与预期的调用约定匹配：

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 中的联合体与不透明类型）。对于这些情况，手动声明外部函数：

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() 以调整预处理器宏：

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,
});

贡献

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

改进方向

• 支持 Windows 工具链路径
• 自动检测 SDK 版本
• 集成到 Flipper 应用商店
• 提供更多 SDK 包装抽象

资源

• Flipper Zero 开发者文档
• UFBT 仓库
• Zig 语言参考
• Flipper SDK API 参考

许可证

本项目采用 MIT 许可证——详见 LICENSE 文件。

致谢

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

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