Flipper Zero Zig テンプレート

Zig プログラミング言語を用いて Flipper Zero アプリケーションを開発するための、現代的で生産環境に即したテンプレートです。本プロジェクトは、Zig と Flipper Zero SDK を統合した簡潔なビルドシステムを提供し、開発者が 型安全かつメモリ安全なアプリケーションを作成することを可能にします。

概要

このテンプレートは、Zig の強力なビルドシステムおよび言語機能を、Flipper Zero のファームウェア開発キットと結び付けます。

• Zig の ARM Cortex-M4 クロスコンパイル
• Flipper SDK との複雑な統合を処理
• カスタムアプリケーションのための清潔なスタートポイントを提供

主な機能

• ネイティブ Zig サポート: コンパイル時の安全性保証および C 言語との互換性を活かし、Flipper アプリケーションを完全に Zig で記述できます。
• 自動化されたビルドパイプライン: FAP ファイルのパッケージングのために ufbt（非公式ビルドツール） とシームレスに統合されています。
• クロスプラットフォーム開発: Zig がサポートする macOS、Linux および他のプラットフォームで動作します。
• SDK 統合: 完全な Flipper SDK（F7 ターゲット）のためのプリ構成済み include パスおよびコンパイラフラグが用意されています。
• インタラクティブなセットアップ: アプリメタデータをカスタマイズするためのガイドされた初期化スクリプトが含まれています。
• クイックローンチ: Flipper デバイスへビルド、パッケージ化、デプロイするための組み込みコマンドが用意されています。

アーキテクチャ

本テンプレートは、2 つ段階のビルドプロセスを採用しています。

1. Zig ビルドステージ

• Zig ソースを ARM Cortex-M4 オブジェクトファイル（

  app.o

  ）へコンパイルします。
• ターゲット: ARM Thumb アーキテクチャ、Cortex-M4 CPU モデル
• ABI: EABIHF（Embedded Application Binary Interface, Hard Float）
• 最適化: 最小二値サイズの取得を目指した

  ReleaseSmall

2. UFBT パッケージステージ

• オブジェクトファイルを SDK とリンカーし、

  .fap

  フォーマットへパッケージ化します。
• 公式 Flipper ビルドツールチェーンによって処理されます。
• デプロイ可能なアプリケーションパッケージを生成します。

必要条件

必要なツール

• Zig: バージョン 0.15.1 以降（ダウンロード）
• UFBT: Unofficial Flipper Build Tool（インストールガイド参照）
• 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

インストール手順

UFBT をインストールする:

python3 -m pip install --upgrade ufbt
ufbt update

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

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

プロジェクトを初期化する: このインタラクティブスクリプトは、以下の情報をユーザーに確認します。

• アプリ ID（例：

  my_custom_app

  ）
• ディスプレイ名（Flipper メニューに表示されます）
• 説明
• 著者名
• GitHub リポジトリ URL

使用方法

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

Zig ソースをオブジェクトファイルへコンパイルします。これにより、

zig-out/bin/app.o

FAP パッケージの作成

完全なアプリケーションをビルドしてパッケージ化します。このコマンドは以下のフルパイプラインを実行します。

1. Zig ソースをオブジェクトファイルへコンパイルする。
2. SDK とリンケージを行うために ufbt を呼出す。

3. dist/

   ディレクトリに

   .fap

   ファイルを生成する。

Flipper へのデプロイ

接続された Flipper Zero で直接アプリを起動します。これはビルド、パッケージ化、および 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 の統合

ビルドシステムは自動的に以下の include パスを設定します。

• コア 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 された関数が期待される呼出し規約と一致していることを確認してください：

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;

トラブルシューティング

ビルドエラー

• 問題: ヘッダー

  'furi.h'

  が見つからない
  • 原因：UFBT SDK がインストールされていない、または

    ~/.ufbt

    のパスが正しくない。
  • 解決策：SDK ヘッダーをインストールするために

    ufbt update

    を実行してください。
• 問題:

  'view_port_alloc'

  に未定義の参照
  • 原因：オブジェクトファイルを SDK と適切にリンクしていない。
  • 解決策：リンケージを完了させるために

    zig build fap

    を使用し、単なる

    zig build

    は避けてください。

デプロイの問題

• 問題: Flipper デバイスが検出されません
  • 原因：デバイスが接続されていないか、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 ファイルを参照してください。

謝辞

• UFBT ツールチェーンを提供してくれた Flipper Devices チームへ
• ARM クロスコンパイルサポートを提供してくれた Zig コミュニティへ
• Flipper Zero SDK にコントリビューションされた方々へ

※本テンプレートは非公式であり、Flipper Devices Inc. とは関係ありません。必ず実装デバイスへのデプロイ前に、アプリケーションを慎重にテストしてください。