Plantilla Zig para Flipper Zero

Una plantilla moderna y lista para producción para desarrollar aplicaciones para Flipper Zero con el lenguaje de programación Zig. Este proyecto proporciona un sistema de compilación optimizado que integra Zig con el SDK de Flipper Zero, lo que permite a los desarrolladores escribir aplicaciones con seguridad de tipos y de memoria para la plataforma Flipper Zero.

Visión general

Esta plantilla tiende un puente entre el potente sistema de compilación y las características del lenguaje Zig y el kit de desarrollo de firmware de Flipper Zero. Gestiona la compleja integración entre la compilación cruzada ARM Cortex-M4 de Zig y el SDK de Flipper, proporcionando un punto de partida limpio para aplicaciones personalizadas.

Características principales

• Soporte nativo de Zig: Escribe aplicaciones para Flipper completamente en Zig, aprovechando sus garantías de seguridad en tiempo de compilación y su interoperabilidad con C
• Pipeline de compilación automatizado: Integración fluida con ufbt (herramienta de compilación no oficial) para empaquetar archivos FAP
• Desarrollo multiplataforma: Funciona en macOS, Linux y otras plataformas compatibles con Zig
• Integración con el SDK: Rutas de inclusión y banderas del compilador preconfiguradas para el SDK completo de Flipper (objetivo F7)
• Configuración interactiva: Script de inicialización guiado para personalizar los metadatos de la aplicación
• Inicio rápido: Comandos integrados para compilar, empaquetar y desplegar en dispositivos Flipper

Arquitectura

La plantilla utiliza un proceso de compilación en dos etapas:

1. Etapa de compilación Zig: Compila el código fuente Zig a archivos objeto ARM Cortex-M4 (app.o)

   • Objetivo: arquitectura thumb con modelo de CPU cortex-m4
   • ABI: eabihf (Interfaz Binaria de Aplicaciones Embebidas, coma flotante hardware)
   • Optimización: ReleaseSmall para un tamaño de binario mínimo

2. Etapa de empaquetado UFBT: Enlaza los archivos objeto con el SDK y los empaqueta en formato .fap

   • Gestionado por la cadena de herramientas de compilación oficial de Flipper
   • Produce paquetes de aplicación desplegables

Requisitos previos

Herramientas necesarias

• Zig: Versión 0.15.1 o posterior (descarga)
• UFBT: Herramienta de compilación no oficial de Flipper (guía de instalación)
• Python 3: Necesario para ejecutar comandos ufbt
• SDK de Flipper Zero: Gestionado automáticamente por ufbt (se instala en ~/.ufbt)

Configuración específica por plataforma

macOS

La plantilla está preconfigurada para macOS ARM64 con la ruta de la cadena de herramientas ARM:

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

Si estás en otra plataforma, es posible que necesites ajustar la ruta arm_libc_include en build.zig:31 para que coincida con la ubicación de tu cadena de herramientas.

Instalación

1. Instalar UFBT:

   root@kitploit:~

   python3 -m pip install --upgrade ufbt
   ufbt update
   

2. Clonar o descargar esta plantilla:

   root@kitploit:~

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

3. Inicializar tu proyecto:

   root@kitploit:~

   zig build init
   

   Este script interactivo te solicitará:

   • ID de la aplicación (p. ej., my_custom_app)
   • Nombre para mostrar (visible en el menú de Flipper)
   • Descripción
   • Nombre del autor
   • URL del repositorio de GitHub

Uso

Compilar la aplicación

Compila el código fuente Zig a un archivo objeto:

zig build

Esto crea zig-out/bin/app.o con todo el código de aplicación compilado.

Crear un paquete FAP

Compila y empaqueta la aplicación completa:

zig build fap

Esto ejecuta el pipeline completo:

1. Compila el código fuente Zig a archivo objeto
2. Invoca ufbt para enlazar con el SDK
3. Genera el archivo .fap en el directorio dist/

Desplegar en Flipper

Ejecuta la aplicación directamente en un Flipper Zero conectado:

zig build launch

Esto compila, empaqueta y transfiere la aplicación por USB y, a continuación, la inicia automáticamente.

Estructura del proyecto

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

Archivos clave

• src/root.zig: Punto de entrada que contiene la función start() y la lógica de la aplicación
• application.fam: Configuración específica de Flipper (ID de la aplicación, categoría, dependencias, tamaño de pila)
• build.zig: Define los objetivos de compilación, las rutas del SDK y los comandos de compilación

Guía de desarrollo

Estructura mínima de una aplicación

La plantilla incluye un ejemplo "Hola mundo" que demuestra las API principales de 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;
}

Integración con el SDK

El sistema de compilación configura automáticamente las rutas de inclusión para:

• SDK principal: FURI (Interfaz de tiempo de ejecución universal de Flipper)
• HAL: Capa de abstracción de hardware para STM32WB55
• Bibliotecas estándar: mbedTLS, nanopb, mlib
• Bibliotecas de protocolos: Sub-GHz, NFC, RFID, infrarrojos
• API de periféricos: GPIO, SPI, I2C, UART

Todos los encabezados están disponibles mediante @cImport() en tu código Zig.

Notas sobre la convención de llamada

El SDK de Flipper utiliza las convenciones de llamada ARM AAPCS:

• AAPCS: Llamada a procedimiento ARM estándar (p. ej., punto de entrada start())
• AAPCS-VFP: Con soporte de coma flotante/vectores (p. ej., callbacks)

Asegúrate de que las funciones exportadas coincidan con la convención de llamada esperada:

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

Gestión de importaciones del SDK

Algunos encabezados del SDK contienen construcciones que el traductor de C de Zig no puede procesar (p. ej., uniones con tipos opacos en input/input.h). Para estos casos, declara manualmente las funciones 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;

Solución de problemas

Errores de compilación

Problema: unable to find header 'furi.h'

• Causa: El SDK de UFBT no está instalado o la ruta ~/.ufbt es incorrecta
• Solución: Ejecuta ufbt update para instalar los encabezados del SDK

Problema: undefined reference to 'view_port_alloc'

• Causa: El archivo objeto no está correctamente enlazado con el SDK
• Solución: Usa zig build fap en lugar de zig build para completar el enlazado

Problemas de despliegue

Problema: No Flipper device found

• Causa: El dispositivo no está conectado o está en modo DFU
• Solución: Conéctalo por USB y asegúrate de que el dispositivo esté desbloqueado en el menú principal

Problema: La aplicación falla al iniciarse

• Causa: Desbordamiento de pila o convención de llamada incorrecta
• Solución: Aumenta stack_size en application.fam o verifica las firmas de las funciones

Configuración avanzada

Banderas del compilador

Modifica addFlipperDefines() en build.zig para ajustar las macros del preprocesador:

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

Ajustes de optimización

Cambia el nivel de optimización en build.zig:11:

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

Arquitectura objetivo

La plantilla está orientada al STM32WB55 (ARM Cortex-M4F) del Flipper Zero. Para portarla a otros dispositivos ARM, ajusta 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,
});

Contribuciones

¡Las contribuciones son bienvenidas! Esta plantilla tiene como objetivo simplificar el desarrollo con Zig para Flipper Zero. Si encuentras problemas de compatibilidad con el SDK o tienes sugerencias para mejorar el proceso de compilación, abre un issue o una pull request.

Áreas de mejora

• Soporte para rutas de cadena de herramientas en Windows
• Detección automática de la versión del SDK
• Integración con el catálogo de aplicaciones de Flipper
• Abstracciones adicionales de envoltorio del SDK

Recursos

• Documentación para desarrolladores de Flipper Zero
• Repositorio de UFBT
• Referencia del lenguaje Zig
• Referencia de la API del SDK de Flipper

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Agradecimientos

• Al equipo de Flipper Devices por la cadena de herramientas UFBT
• A la comunidad de Zig por el soporte de compilación cruzada ARM
• A los contribuidores del SDK de Flipper Zero

Nota: Esta es una plantilla no oficial y no está afiliada a Flipper Devices Inc. Prueba siempre las aplicaciones a fondo antes de desplegarlas en dispositivos de producción.