Show HN: Production-ready Zig template for Flipper Zero apps

4 days ago 1

A modern, production-ready template for developing Flipper Zero applications using the Zig programming language. This project provides a streamlined build system that integrates Zig with the Flipper Zero SDK, enabling developers to write type-safe, memory-safe applications for the Flipper Zero platform.

This template bridges Zig's powerful build system and language features with the Flipper Zero firmware development kit. It handles the complex integration between Zig's ARM Cortex-M4 cross-compilation and the Flipper SDK, providing a clean starting point for custom applications.

Native Zig Support: Write Flipper applications entirely in Zig, leveraging its compile-time safety guarantees and C interoperability
Automated Build Pipeline: Seamless integration with ufbt (unofficial build tool) for packaging FAP files
Cross-Platform Development: Works on macOS, Linux, and other platforms supported by Zig
SDK Integration: Pre-configured include paths and compiler flags for the complete Flipper SDK (F7 target)
Interactive Setup: Guided initialization script to customize app metadata
Quick Launch: Built-in commands to build, package, and deploy to Flipper devices

The template uses a two-stage build process:

Zig Build Stage: Compiles Zig source to ARM Cortex-M4 object files (app.o)
- Target: thumb architecture with cortex-m4 CPU model
- ABI: eabihf (Embedded Application Binary Interface, Hard Float)
- Optimization: ReleaseSmall for minimal binary size
UFBT Package Stage: Links object files with SDK and packages into .fap format
- Handled by the official Flipper build toolchain
- Produces deployable application packages

Zig: Version 0.15.1 or later (download)
UFBT: Unofficial Flipper Build Tool (installation guide)
Python 3: Required for running ufbt commands
Flipper Zero SDK: Automatically managed by ufbt (installed to ~/.ufbt)

The template is pre-configured for ARM64 macOS with the ARM toolchain path:

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

If you're on a different platform, you may need to adjust the arm_libc_include path in build.zig:31 to match your toolchain location.

Install UFBT:

python3 -m pip install --upgrade ufbt ufbt update
Clone or Download This Template:

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

This interactive script will prompt you for:
- App ID (e.g., my_custom_app)
- Display name (shown in Flipper menu)
- Description
- Author name
- GitHub repository URL

Compile the Zig source to an object file:

This creates zig-out/bin/app.o with all the compiled application code.

Build and package the complete application:

This runs the full pipeline:

Compiles Zig source to object file
Invokes ufbt to link with SDK
Generates .fap file in dist/ directory

Launch the application directly on a connected Flipper Zero:

This builds, packages, and transfers the app via USB, then starts it automatically.

flipper-template/ ├── application.fam # Flipper app manifest (metadata, entry points) ├── build.zig # Zig build system configuration ├── build.zig.zon # Zig package manifest ├── icon.png # App icon (10x10px recommended) ├── setup.sh # Interactive project initialization script ├── src/ │ └── root.zig # Main application source code └── zig-out/ # Build artifacts (generated) └── bin/ └── app.o # Compiled object file

src/root.zig: Entry point containing the start() function and application logic
application.fam: Flipper-specific configuration (app ID, category, dependencies, stack size)
build.zig: Defines compilation targets, SDK paths, and build commands

Minimal Application Structure

The template includes a "Hello World" example demonstrating core Flipper APIs:

// 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; }

The build system automatically configures include paths for:

Core SDK: FURI (Flipper Universal Runtime Interface)
HAL: Hardware abstraction layer for STM32WB55
Standard Libraries: mbedTLS, nanopb, mlib
Protocol Libraries: Sub-GHz, NFC, RFID, Infrared
Peripheral APIs: GPIO, SPI, I2C, UART

All headers are available via @cImport() in your Zig code.

Flipper SDK uses ARM AAPCS calling conventions:

AAPCS: Standard ARM procedure call (e.g., start() entry point)
AAPCS-VFP: With floating-point/vector support (e.g., callbacks)

Ensure exported functions match the expected calling convention:

export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 export fn draw_callback(canvas: ?*Canvas, ctx: ?*anyopaque) callconv(.{ .arm_aapcs_vfp = .{} }) void

Some SDK headers contain constructs that Zig's C translator cannot process (e.g., unions with opaque types in input/input.h). For these cases, manually declare external functions:

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;

Issue: unable to find header 'furi.h'

Cause: UFBT SDK not installed or ~/.ufbt path incorrect
Fix: Run ufbt update to install SDK headers

Issue: undefined reference to 'view_port_alloc'

Cause: Object file not properly linked with SDK
Fix: Use zig build fap instead of zig build to complete linking

Issue: No Flipper device found

Cause: Device not connected or in DFU mode
Fix: Connect via USB and ensure device is unlocked at main menu

Issue: App crashes on launch

Cause: Stack overflow or incorrect calling convention
Fix: Increase stack_size in application.fam or verify function signatures

Modify addFlipperDefines() in build.zig to adjust preprocessor macros:

obj.root_module.addCMacro("FAP_VERSION", "\\\"1.0\\\""); obj.root_module.addCMacro("CUSTOM_DEFINE", "value");

Change optimization level in build.zig:11:

const optimize = b.standardOptimizeOption(.{ .preferred_optimize_mode = .ReleaseFast, // or .ReleaseSmall, .Debug });

The template targets Flipper Zero's STM32WB55 (ARM Cortex-M4F). To port to other ARM devices, adjust 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, });

Contributions are welcome! This template aims to simplify Zig development for Flipper Zero. If you encounter SDK compatibility issues or have suggestions for improving the build process, please open an issue or pull request.

Support for Windows toolchain paths
Automated SDK version detection
Integration with Flipper application catalog
Additional SDK wrapper abstractions

This project is licensed under the MIT License - see the LICENSE file for details.

Flipper Devices team for the UFBT toolchain
Zig community for ARM cross-compilation support
Contributors to the Flipper Zero SDK

Note: This is an unofficial template and is not affiliated with Flipper Devices Inc. Always test applications thoroughly before deploying to production devices.

Read Entire Article