Template Zig per Flipper Zero

Un template moderno e pronto per la produzione per lo sviluppo di applicazioni Flipper Zero utilizzando il linguaggio di programmazione Zig. Questo progetto fornisce un sistema di compilazione ottimizzato che integra Zig con l'SDK di Flipper Zero, consentendo agli sviluppatori di scrivere applicazioni type-safe e memory-safe per la piattaforma Flipper Zero.

Panoramica

Questo template colma il divario tra il potente sistema di compilazione di Zig e le caratteristiche del linguaggio con il kit di sviluppo firmware di Flipper Zero. Gestisce la complessa integrazione tra la cross-compilazione ARM Cortex-M4 di Zig e l'SDK Flipper, fornendo un punto di partenza pulito per applicazioni personalizzate.

Caratteristiche principali

• Supporto nativo a Zig: Scrivi applicazioni Flipper interamente in Zig, sfruttando le garanzie di sicurezza in fase di compilazione e l'interoperabilità con C
• Pipeline di compilazione automatizzata: Integrazione senza soluzione di continuità con ufbt (strumento di compilazione non ufficiale) per il confezionamento dei file FAP
• Sviluppo multipiattaforma: Funziona su macOS, Linux e altre piattaforme supportate da Zig
• Integrazione SDK: Percorsi di inclusione e flag del compilatore preconfigurati per l'SDK Flipper completo (target F7)
• Configurazione interattiva: Script di inizializzazione guidato per personalizzare i metadati dell'app
• Avvio rapido: Comandi integrati per compilare, impacchettare e distribuire sui dispositivi Flipper

Architettura

Il template utilizza un processo di compilazione a due stadi:

1. Fase di compilazione Zig: Compila il codice sorgente Zig in file oggetto ARM Cortex-M4 (app.o)

   • Target: architettura thumb con modello CPU cortex-m4
   • ABI: eabihf (Interfaccia Binaria per Applicazioni Embedded, Hard Float)
   • Ottimizzazione: ReleaseSmall per dimensione binaria minima

2. Fase di impacchettamento UFBT: Collega i file oggetto con l'SDK e li impacchetta nel formato .fap

   • Gestito dalla toolchain ufficiale di Flipper
   • Produce pacchetti applicativi distribuibili

Prerequisiti

Strumenti richiesti

• Zig: Versione 0.15.1 o successiva (download)
• UFBT: Strumento di compilazione Flipper non ufficiale (guida all'installazione)
• Python 3: Necessario per eseguire i comandi ufbt
• SDK Flipper Zero: Gestito automaticamente da ufbt (installato in ~/.ufbt)

Configurazione specifica per piattaforma

macOS

Il template è preconfigurato per macOS ARM64 con il percorso della toolchain ARM:

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

Se sei su una piattaforma diversa, potresti dover modificare il percorso arm_libc_include in build.zig:31 in base alla posizione della tua toolchain.

Installazione

1. Installa UFBT:

   root@kitploit:~

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. Clona o scarica questo template:

   root@kitploit:~

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

3. Inizializza il tuo progetto:

   root@kitploit:~

   zig build init
   

   Questo script interattivo ti chiederà:

   • ID App (es., my_custom_app)
   • Nome visualizzato (mostrato nel menu Flipper)
   • Descrizione
   • Nome autore
   • URL repository GitHub

Utilizzo

Compilare l'applicazione

Compila il codice sorgente Zig in un file oggetto:

zig build

Questo crea zig-out/bin/app.o con tutto il codice applicativo compilato.

Creare un pacchetto FAP

Compila e impacchetta l'applicazione completa:

zig build fap

Questo esegue l'intera pipeline:

1. Compila il codice Zig in file oggetto
2. Invoca ufbt per il collegamento con l'SDK
3. Genera il file .fap nella directory dist/

Distribuire su Flipper

Avvia l'applicazione direttamente su un Flipper Zero connesso:

zig build launch

Questo compila, impacchetta e trasferisce l'app via USB, quindi la avvia automaticamente.

Struttura del progetto

flipper-template/
├── application.fam       # Manifest dell'app Flipper (metadati, punti di ingresso)
├── build.zig            # Configurazione del sistema di compilazione Zig
├── build.zig.zon        # Manifest del pacchetto Zig
├── icon.png             # Icona dell'app (10x10px consigliati)
├── setup.sh             # Script di inizializzazione interattivo del progetto
├── src/
│   └── root.zig         # Codice sorgente principale dell'applicazione
└── zig-out/             # Artefatti di compilazione (generati)
    └── bin/
        └── app.o        # File oggetto compilato

File chiave

• src/root.zig: Punto di ingresso contenente la funzione start() e la logica dell'applicazione
• application.fam: Configurazione specifica per Flipper (ID app, categoria, dipendenze, dimensione dello stack)
• build.zig: Definisce i target di compilazione, i percorsi SDK e i comandi di compilazione

Guida allo sviluppo

Struttura minima dell'applicazione

Il template include un esempio "Hello World" che dimostra le API core di 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;
}

Integrazione SDK

Il sistema di compilazione configura automaticamente i percorsi di inclusione per:

• SDK core: FURI (Flipper Universal Runtime Interface)
• HAL: Livello di astrazione hardware per STM32WB55
• Librerie standard: mbedTLS, nanopb, mlib
• Librerie di protocollo: Sub-GHz, NFC, RFID, Infrared
• API periferiche: GPIO, SPI, I2C, UART

Tutte le intestazioni sono disponibili tramite @cImport() nel codice Zig.

Note sulle convenzioni di chiamata

L'SDK Flipper utilizza le convenzioni di chiamata ARM AAPCS:

• AAPCS: Chiamata di procedura ARM standard (es., punto di ingresso start())
• AAPCS-VFP: Con supporto per numeri a virgola mobile/vettori (es., callback)

Assicurati che le funzioni esportate corrispondano alla convenzione di chiamata prevista:

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

Gestione degli import SDK

Alcune intestazioni dell'SDK contengono costrutti che il traduttore C di Zig non può elaborare (es., unioni con tipi opachi in input/input.h). In questi casi, dichiara manualmente funzioni esterne:

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;

Risoluzione dei problemi

Errori di compilazione

Problema: unable to find header 'furi.h'

• Causa: SDK UFBT non installato o percorso ~/.ufbt errato
• Soluzione: Esegui ufbt update per installare le intestazioni SDK

Problema: undefined reference to 'view_port_alloc'

• Causa: File oggetto non collegato correttamente con SDK
• Soluzione: Usa zig build fap invece di zig build per completare il collegamento

Problemi di distribuzione

Problema: No Flipper device found

• Causa: Dispositivo non connesso o in modalità DFU
• Soluzione: Collega via USB e assicurati che il dispositivo sia sbloccato nel menu principale

Problema: L'app si blocca all'avvio

• Causa: Overflow dello stack o convenzione di chiamata errata
• Soluzione: Aumenta stack_size in application.fam o verifica le firme delle funzioni

Configurazione avanzata

Flag del compilatore

Modifica addFlipperDefines() in build.zig per regolare le macro del preprocessore:

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

Impostazioni di ottimizzazione

Cambia il livello di ottimizzazione in build.zig:11:

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

Architettura target

Il template ha come target lo STM32WB55 (ARM Cortex-M4F) di Flipper Zero. Per portarlo su altri dispositivi ARM, modifica 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,
});

Contribuire

I contributi sono benvenuti! Questo template mira a semplificare lo sviluppo in Zig per Flipper Zero. Se incontri problemi di compatibilità con l'SDK o hai suggerimenti per migliorare il processo di compilazione, apri una issue o una pull request.

Aree di miglioramento

• Supporto per percorsi della toolchain Windows
• Rilevamento automatico della versione SDK
• Integrazione con il catalogo applicazioni Flipper
• Astrazioni wrapper SDK aggiuntive

Risorse

• Documentazione per sviluppatori Flipper Zero
• Repository UFBT
• Riferimento del linguaggio Zig
• Riferimento API SDK Flipper

Licenza

Questo progetto è concesso in licenza sotto la licenza MIT - consulta il file LICENSE per i dettagli.

Riconoscimenti

• Team di Flipper Devices per la toolchain UFBT
• Comunità Zig per il supporto alla cross-compilazione ARM
• Contributori all'SDK Flipper Zero

Nota: Questo è un template non ufficiale e non è affiliato con Flipper Devices Inc. Testa sempre accuratamente le applicazioni prima di distribuirle su dispositivi di produzione.