Modèle Zig pour Flipper Zero

Un modèle moderne et prêt pour la production pour développer des applications Flipper Zero en utilisant le langage de programmation Zig. Ce projet fournit un système de construction rationalisé qui intègre Zig avec le SDK Flipper Zero, permettant aux développeurs d'écrire des applications sécurisées au niveau des types et de la mémoire pour la plateforme Flipper Zero.

Présentation

Ce modèle fait le pont entre le système de construction et les fonctionnalités puissantes de Zig et le kit de développement du firmware Flipper Zero. Il gère l'intégration complexe entre la cross-compilation ARM Cortex-M4 de Zig et le SDK Flipper, offrant un point de départ propre pour des applications personnalisées.

Fonctionnalités clés

• Support natif de Zig : Écrivez des applications Flipper entièrement en Zig, en exploitant ses garanties de sécurité à la compilation et son interopérabilité avec C.
• Pipeline de construction automatisé : Intégration transparente avec ufbt (outil de construction non officiel) pour empaqueter les fichiers FAP.
• Développement multiplateforme : Fonctionne sur macOS, Linux et d'autres plates-formes supportées par Zig.
• Intégration du SDK : Chemins d'inclusion et drapeaux de compilation préconfigurés pour le SDK Flipper complet (cible F7).
• Configuration interactive : Script d'initialisation guidé pour personnaliser les métadonnées de l'application.
• Lancement rapide : Commandes intégrées pour construire, empaqueter et déployer sur les appareils Flipper.

Architecture

Le modèle utilise un processus de construction en deux étapes :

1. Étape de construction Zig : Compile le source Zig en fichiers objets ARM Cortex-M4 (app.o)

   • Cible : architecture thumb avec modèle de CPU cortex-m4
   • ABI : eabihf (Interface binaire d'application embarquée, virgule flottante matérielle)
   • Optimisation : ReleaseSmall pour une taille binaire minimale

2. Étape de paquetage UFBT : Lie les fichiers objets avec le SDK et les empaquette au format .fap

   • Géré par la chaîne d'outils officielle de Flipper
   • Produit des paquets d'application déployables

Prérequis

Outils requis

• Zig : Version 0.15.1 ou ultérieure (télécharger)
• UFBT : Outil de construction non officiel pour Flipper (guide d'installation)
• Python 3 : Nécessaire pour exécuter les commandes ufbt
• SDK Flipper Zero : Géré automatiquement par ufbt (installé dans ~/.ufbt)

Configuration spécifique à la plateforme

macOS

Le modèle est préconfiguré pour macOS ARM64 avec le chemin de la chaîne d'outils ARM :

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

Si vous êtes sur une plateforme différente, vous devrez peut-être ajuster le chemin arm_libc_include dans build.zig:31 pour correspondre à l'emplacement de votre chaîne d'outils.

Installation

1. Installer UFBT :

   root@kitploit:~

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. Cloner ou télécharger ce modèle :

   root@kitploit:~

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

3. Initialiser votre projet :

   root@kitploit:~

   zig build init
   

   Ce script interactif vous demandera :

   • ID de l'application (ex. my_custom_app)
   • Nom d'affichage (affiché dans le menu Flipper)
   • Description
   • Nom de l'auteur
   • URL du dépôt GitHub

Utilisation

Construction de l'application

Compilez le source Zig en un fichier objet :

zig build

Cela crée zig-out/bin/app.o avec tout le code d'application compilé.

Création d'un paquet FAP

Construisez et empaquetez l'application complète :

zig build fap

Cela exécute le pipeline complet :

1. Compile le source Zig en fichier objet
2. Invoque ufbt pour lier avec le SDK
3. Génère le fichier .fap dans le répertoire dist/

Déploiement sur Flipper

Lancez l'application directement sur un Flipper Zero connecté :

zig build launch

Cela construit, empaquette et transfère l'application via USB, puis la démarre automatiquement.

Structure du projet

flipper-template/
├── application.fam       # Manifeste d'application Flipper (métadonnées, points d'entrée)
├── build.zig            # Configuration du système de construction Zig
├── build.zig.zon        # Manifeste de paquet Zig
├── icon.png             # Icône de l'application (10x10px recommandé)
├── setup.sh             # Script interactif d'initialisation du projet
├── src/
│   └── root.zig         # Code source principal de l'application
└── zig-out/             # Artefacts de construction (générés)
    └── bin/
        └── app.o        # Fichier objet compilé

Fichiers clés

• src/root.zig : Point d'entrée contenant la fonction start() et la logique de l'application
• application.fam : Configuration spécifique à Flipper (ID de l'application, catégorie, dépendances, taille de la pile)
• build.zig : Définit les cibles de compilation, les chemins SDK et les commandes de construction

Guide de développement

Structure minimale d'application

Le modèle inclut un exemple "Hello World" illustrant les API de base de Flipper :

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

// Point d'entrée de l'application (doit être nommé "start")
export fn start(_: ?*anyopaque) callconv(.{ .arm_aapcs = .{} }) i32 {
    // Initialisation du viewport GUI
    const gui = flipper.furi_record_open("gui");
    const view_port = flipper.view_port_alloc();

    // Configuration des callbacks et de l'interface utilisateur
    // ... (voir src/root.zig pour l'implémentation complète)

    // Boucle d'événements
    _ = flipper.furi_thread_flags_wait(1, flipper.FuriFlagWaitAny, flipper.FuriWaitForever);

    return 0;
}

Intégration du SDK

Le système de construction configure automatiquement les chemins d'inclusion pour :

• SDK Core : FURI (Interface d'exécution universelle Flipper)
• HAL : Couche d'abstraction matérielle pour STM32WB55
• Bibliothèques standard : mbedTLS, nanopb, mlib
• Bibliothèques de protocole : Sub-GHz, NFC, RFID, Infrarouge
• API périphériques : GPIO, SPI, I2C, UART

Tous les en-têtes sont disponibles via @cImport() dans votre code Zig.

Notes sur les conventions d'appel

Le SDK Flipper utilise les conventions d'appel ARM AAPCS :

• AAPCS : Appel de procédure ARM standard (ex. point d'entrée start())
• AAPCS-VFP : Avec support virgule flottante/vectorielle (ex. callbacks)

Assurez-vous que les fonctions exportées correspondent à la convention d'appel attendue :

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

Gestion des importations du SDK

Certains en-têtes du SDK contiennent des constructions que le traducteur C de Zig ne peut pas traiter (ex. unions avec types opaques dans input/input.h). Dans ces cas, déclarez manuellement les fonctions externes :

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;

Dépannage

Erreurs de construction

Problème : unable to find header 'furi.h'

• Cause : SDK UFBT non installé ou chemin ~/.ufbt incorrect
• Solution : Exécutez ufbt update pour installer les en-têtes SDK

Problème : undefined reference to 'view_port_alloc'

• Cause : Fichier objet mal lié avec le SDK
• Solution : Utilisez zig build fap au lieu de zig build pour terminer l'édition de liens

Problèmes de déploiement

Problème : No Flipper device found

• Cause : Appareil non connecté ou en mode DFU
• Solution : Connectez via USB et assurez-vous que l'appareil est déverrouillé sur le menu principal

Problème : L'application plante au lancement

• Cause : Débordement de pile ou convention d'appel incorrecte
• Solution : Augmentez stack_size dans application.fam ou vérifiez les signatures de fonction

Configuration avancée

Drapeaux du compilateur

Modifiez addFlipperDefines() dans build.zig pour ajuster les macros du préprocesseur :

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

Paramètres d'optimisation

Changez le niveau d'optimisation dans build.zig:11 :

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

Architecture cible

Le modèle cible le STM32WB55 (ARM Cortex-M4F) du Flipper Zero. Pour porter sur d'autres appareils ARM, ajustez 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,
});

Contribution

Les contributions sont les bienvenues ! Ce modèle vise à simplifier le développement Zig pour Flipper Zero. Si vous rencontrez des problèmes de compatibilité avec le SDK ou avez des suggestions pour améliorer le processus de construction, veuillez ouvrir un issue ou une pull request.

Domaines d'amélioration

• Support des chemins de chaîne d'outils Windows
• Détection automatique de la version du SDK
• Intégration avec le catalogue d'applications Flipper
• Abstractions supplémentaires autour du SDK

Ressources

• Documentation développeur Flipper Zero
• Dépôt UFBT
• Référence du langage Zig
• Référence API du SDK Flipper

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Remerciements

• L'équipe Flipper Devices pour la chaîne d'outils UFBT
• La communauté Zig pour le support de la cross-compilation ARM
• Les contributeurs au SDK Flipper Zero

Note : Ce modèle est non officiel et n'est pas affilié à Flipper Devices Inc. Testez toujours les applications de manière approfondie avant de les déployer sur des appareils de production.