Flipper Zero Zig テンプレート

Zig プログラミング言語を使用して Flipper Zero アプリケーションを開発するための、モダンで本番環境対応のテンプレートです。このプロジェクトは Zig と Flipper Zero SDK を統合する合理化されたビルドシステムを提供し、開発者が Flipper Zero プラットフォーム向けに型安全かつメモリ安全なアプリケーションを記述できるようにします。

概要

このテンプレートは、Zig の強力なビルドシステムと言語機能を Flipper Zero ファームウェア開発キットに橋渡しします。Zig の ARM Cortex-M4 クロスコンパイルと Flipper SDK の間の複雑な統合を処理し、カスタムアプリケーションのためのクリーンな出発点を提供します。

主な機能

ネイティブ Zig サポート: Flipper アプリケーションを完全に Zig で記述し、コンパイル時の安全性保証と C 相互運用性を活用
自動化されたビルドパイプライン: FAP ファイルのパッケージングのための ufbt(非公式ビルドツール)とのシームレスな統合
クロスプラットフォーム開発: macOS、Linux、その他 Zig がサポートするプラットフォームで動作
SDK 統合: 完全な Flipper SDK(F7 ターゲット)用に事前構成されたインクルードパスとコンパイラフラグ
対話型セットアップ: アプリのメタデータをカスタマイズするためのガイド付き初期化スクリプト
クイック起動: Flipper デバイスへのビルド、パッケージング、デプロイのための組み込みコマンド

アーキテクチャ

このテンプレートは2段階のビルドプロセスを使用します:

Zig ビルド段階: Zig ソースを ARM Cortex-M4 オブジェクトファイル(app.o)にコンパイル
- ターゲット: cortex-m4 CPU モデルを備えた thumb アーキテクチャ
- ABI: eabihf(組み込みアプリケーション・バイナリ・インターフェース、ハードフロート)
- 最適化: バイナリサイズを最小化する ReleaseSmall
UFBT パッケージ段階: オブジェクトファイルを SDK とリンクし、.fap 形式にパッケージング
- 公式 Flipper ビルドツールチェーンによって処理
- デプロイ可能なアプリケーションパッケージを生成

前提条件

必要なツール

Zig: バージョン 0.15.1 以降(ダウンロード)
UFBT: 非公式 Flipper ビルドツール(インストールガイド)
Python 3: ufbt コマンドの実行に必要
Flipper Zero SDK: ufbt によって自動管理(~/.ufbt にインストール)

プラットフォーム別セットアップ

macOS

このテンプレートは ARM ツールチェーンパスを使用する ARM64 macOS 用に事前構成されています:

~/.ufbt/toolchain/arm64-darwin/arm-none-eabi/include

別のプラットフォームを使用している場合は、build.zig:31 の arm_libc_include パスを自分のツールチェーンの場所に合わせて調整する必要があるかもしれません。

インストール

UFBT をインストール:

python3 -m pip install --upgrade ufbt
ufbt update

このテンプレートをクローンまたはダウンロード:

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

プロジェクトを初期化:
```
zig build init
```
この対話型スクリプトは次の項目を要求します:
- アプリ ID(例: my_custom_app)
- 表示名(Flipper メニューに表示されます)
- 説明
- 作者名
- GitHub リポジトリ URL

使用方法

アプリケーションのビルド

Zig ソースをオブジェクトファイルにコンパイル:

zig build

これにより、コンパイルされたすべてのアプリケーションコードを含む zig-out/bin/app.o が作成されます。

FAP パッケージの作成

完全なアプリケーションをビルドしてパッケージング:

zig build fap

これにより完全なパイプラインが実行されます:

Zig ソースをオブジェクトファイルにコンパイル
ufbt を呼び出して SDK とリンク
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」の例が含まれています:

// Import Flipper SDK functions
const flipper = @cImport({
    @cInclude("furi.h");
    @cInclude("gui/gui.h");
    @cInclude("gui/canvas.h");
    @cInclude("gui/view_port.h");
});

// Application entry point (must be named "start")
export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 {
    // Initialize GUI viewport
    const gui = flipper.furi_record_open("gui");
    const view_port = flipper.view_port_alloc();

    // Set up callbacks and UI
    // ... (see src/root.zig for complete implementation)

    // Event loop
    _ = flipper.furi_thread_flags_wait(1, flipper.FuriFlagWaitAny, flipper.FuriWaitForever);

    return 0;
}

SDK 統合

ビルドシステムは以下のインクルードパスを自動的に構成します:

コア SDK: FURI(Flipper Universal Runtime Interface)
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 ではなく zig build fap を使用してリンクを完了する

デプロイの問題

問題: 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,  // or .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 を開くかプルリクエストを送信してください。

改善分野

Windows ツールチェーンパスのサポート
SDK バージョンの自動検出
Flipper アプリケーションカタログとの統合
追加の SDK ラッパー抽象化

リソース

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

謝辞

UFBT ツールチェーンを提供してくれた Flipper Devices チーム
ARM クロスコンパイルをサポートする Zig コミュニティ
Flipper Zero SDK への貢献者

注記: これは非公式のテンプレートであり、Flipper Devices Inc. とは提携していません。本番デバイスにデプロイする前に、必ずアプリケーションを十分にテストしてください。

flipper-template

人気