Template Zig para Flipper Zero

Um template moderno e pronto para produção para desenvolver aplicações para Flipper Zero usando a linguagem de programação Zig. Este projeto fornece um sistema de build simplificado que integra Zig com o SDK do Flipper Zero, permitindo que desenvolvedores escrevam aplicações type-safe e memory-safe para a plataforma Flipper Zero.

Visão Geral

Este template faz a ponte entre o poderoso sistema de build e os recursos de linguagem do Zig e o kit de desenvolvimento de firmware do Flipper Zero. Ele lida com a complexa integração entre a compilação cruzada ARM Cortex-M4 do Zig e o SDK do Flipper, fornecendo um ponto de partida limpo para aplicações personalizadas.

Principais Recursos

• Suporte nativo a Zig: Escreva aplicações Flipper inteiramente em Zig, aproveitando suas garantias de segurança em tempo de compilação e a interoperabilidade com C
• Pipeline de build automatizado: Integração perfeita com o ufbt (ferramenta de build não oficial) para empacotar arquivos FAP
• Desenvolvimento multiplataforma: Funciona em macOS, Linux e outras plataformas suportadas pelo Zig
• Integração com SDK: Caminhos de inclusão e flags do compilador pré-configurados para o SDK completo do Flipper (alvo F7)
• Configuração interativa: Script de inicialização guiado para personalizar os metadados do aplicativo
• Inicialização rápida: Comandos integrados para compilar, empacotar e implantar em dispositivos Flipper

Arquitetura

O template usa um processo de build em duas etapas:

1. Etapa de build do Zig: Compila o código-fonte Zig para arquivos-objeto ARM Cortex-M4 (app.o)

   • Alvo: arquitetura thumb com modelo de CPU cortex-m4
   • ABI: eabihf (Embedded Application Binary Interface, Hard Float)
   • Otimização: ReleaseSmall para tamanho mínimo do binário

2. Etapa de empacotamento UFBT: Liga os arquivos-objeto com o SDK e empacota no formato .fap

   • Gerenciado pela toolchain de build oficial do Flipper
   • Produz pacotes de aplicativos implantáveis

Pré-requisitos

Ferramentas Necessárias

• Zig: Versão 0.15.1 ou posterior (download)
• UFBT: Ferramenta de build não oficial do Flipper (guia de instalação)
• Python 3: Necessário para executar comandos ufbt
• SDK do Flipper Zero: Gerenciado automaticamente pelo ufbt (instalado em ~/.ufbt)

Configuração Específica por Plataforma

macOS

O template é pré-configurado para macOS ARM64 com o caminho da toolchain ARM:

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

Se você estiver em uma plataforma diferente, talvez seja necessário ajustar o caminho arm_libc_include em build.zig:31 para corresponder à localização da sua toolchain.

Instalação

1. Instale o UFBT:

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. Clone ou Baixe Este Template:

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

3. Inicialize Seu Projeto:

   zig build init
   

   Este script interativo solicitará:

   • ID do aplicativo (ex.: my_custom_app)
   • Nome de exibição (mostrado no menu do Flipper)
   • Descrição
   • Nome do autor
   • URL do repositório no GitHub

Uso

Compilando a Aplicação

Compile o código-fonte Zig para um arquivo-objeto:

zig build

Isso cria zig-out/bin/app.o com todo o código da aplicação compilado.

Criando um Pacote FAP

Compile e empacote a aplicação completa:

zig build fap

Isso executa o pipeline completo:

1. Compila o código-fonte Zig para arquivo-objeto
2. Invoca o ufbt para linkar com o SDK
3. Gera o arquivo .fap no diretório dist/

Implantando no Flipper

Execute a aplicação diretamente em um Flipper Zero conectado:

zig build launch

Isso compila, empacota e transfere o aplicativo via USB e, em seguida, inicia-o automaticamente.

Estrutura do Projeto

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

Arquivos Principais

• src/root.zig: Ponto de entrada contendo a função start() e a lógica da aplicação
• application.fam: Configuração específica do Flipper (ID do aplicativo, categoria, dependências, tamanho da pilha)
• build.zig: Define os alvos de compilação, caminhos do SDK e comandos de build

Guia de Desenvolvimento

Estrutura Mínima da Aplicação

O template inclui um exemplo "Hello World" que demonstra as APIs principais do Flipper:

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

Integração com o SDK

O sistema de build configura automaticamente os caminhos de inclusão para:

• SDK principal: FURI (Flipper Universal Runtime Interface)
• HAL: Camada de abstração de hardware para STM32WB55
• Bibliotecas padrão: mbedTLS, nanopb, mlib
• Bibliotecas de protocolo: Sub-GHz, NFC, RFID, Infrared
• APIs de periféricos: GPIO, SPI, I2C, UART

Todos os cabeçalhos estão disponíveis via @cImport() no seu código Zig.

Notas sobre Convenções de Chamada

O SDK do Flipper usa convenções de chamada ARM AAPCS:

• AAPCS: Chamada de procedimento ARM padrão (ex.: ponto de entrada start())
• AAPCS-VFP: Com suporte a ponto flutuante/vetores (ex.: callbacks)

Garanta que as funções exportadas correspondam à convenção de chamada esperada:

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

Lidando com Imports do SDK

Alguns cabeçalhos do SDK contêm construções que o tradutor C do Zig não consegue processar (ex.: unions com tipos opacos em input/input.h). Nesses casos, declare manualmente as funções externas:

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;

Solução de Problemas

Erros de Build

Problema: unable to find header 'furi.h'

• Causa: SDK do UFBT não instalado ou caminho ~/.ufbt incorreto
• Solução: Execute ufbt update para instalar os cabeçalhos do SDK

Problema: undefined reference to 'view_port_alloc'

• Causa: Arquivo-objeto não linkado corretamente com o SDK
• Solução: Use zig build fap em vez de zig build para concluir a linkagem

Problemas de Implantação

Problema: No Flipper device found

• Causa: Dispositivo não conectado ou em modo DFU
• Solução: Conecte via USB e certifique-se de que o dispositivo esteja desbloqueado no menu principal