# Crear una app de Flipper Zero desde cero: APP FIT-XVII

Esta guía parte de una idea deliberadamente pequeña: mostrar tarjetas educativas y responder a los botones. No exige saber radiofrecuencia ni utilizar hardware externo. Al terminar, tendrás un archivo `.fap` real que aparece en el menú del Flipper.

## 1. Las tres piezas que debes entender

Una app externa sencilla necesita, como mínimo:

1. `application.fam`: le dice al firmware cómo se llama la app, qué función debe ejecutar, dónde aparece y qué recursos utiliza.
2. Un archivo `.c`: contiene la pantalla, los botones y la lógica.
3. Un icono PNG monocromo de `10 x 10` píxeles: identifica la app en el menú.

El resultado de compilarlas es un **FAP** (`Flipper Application Package`). Es el archivo que se copia a la tarjeta microSD.

## 2. Preparar uFBT

Instala Python y después ejecuta:

```powershell
py -m pip install --upgrade ufbt
ufbt update
ufbt status
```

`ufbt update` obtiene el SDK. Conviene actualizarlo para que coincida con el firmware que utilizarás. Un FAP compilado para una API distinta puede ser rechazado por el Flipper.

## 3. Crear la carpeta

La estructura de este ejemplo es:

```text
APP_FIT_XVII/
├── application.fam
├── app_fit_xvii.c
└── assets/icon.png
```

Los demás archivos solo documentan y facilitan compartir el proyecto.

## 4. Entender `application.fam`

```python
App(
    appid="app_fit_xvii",
    name="APP FIT-XVII",
    apptype=FlipperAppType.EXTERNAL,
    entry_point="app_fit_xvii_app",
    requires=["gui"],
    stack_size=2 * 1024,
    fap_category="Tools",
    fap_icon="assets/icon.png",
    fap_version="1.0",
)
```

- `appid`: identificador técnico único; usa letras minúsculas y guiones bajos.
- `name`: texto visible en el Flipper.
- `EXTERNAL`: indica que se compilará como `.fap`, no dentro del firmware.
- `entry_point`: nombre exacto de la función principal del archivo C.
- `requires=["gui"]`: declara que utiliza la pantalla y el sistema gráfico.
- `stack_size`: memoria reservada para la ejecución; 2 KiB bastan para este ejemplo.
- `fap_category`: carpeta del menú; aquí será `Apps > Tools`.
- `fap_icon`: icono monocromo de 10 x 10 píxeles.
- `fap_version`: versión que debes aumentar al publicar cambios.

## 5. Entender el código C sin saltos

### A. Los datos

`AppFitTopic` es una plantilla para cada tarjeta. El arreglo `app_fit_topics[]` contiene el título, dos líneas descriptivas y dos líneas para el dato rápido. Para agregar otra tarjeta, copia un bloque y cambia sus textos; no debes modificar la navegación.

### B. El estado

La app solo recuerda dos cosas:

- `screen`: qué pantalla está abierta: portada, tarjetas o dato.
- `topic_index`: cuál tarjeta se está mostrando, empezando por cero.

Esto es una **máquina de estados** pequeña. Cada botón cambia uno de esos valores y solicita redibujar la pantalla.

### C. Dibujar

`app_fit_draw_callback()` limpia la pantalla de 128 x 64 píxeles y llama a una de tres funciones:

- `app_fit_draw_splash()` dibuja la portada.
- `app_fit_draw_card()` dibuja la tarjeta seleccionada.
- `app_fit_draw_tip()` dibuja el dato rápido.

El Flipper no usa HTML. Dibuja texto, líneas, marcos e imágenes directamente sobre un `Canvas`.

### D. Leer botones

`app_fit_input_callback()` recibe cada evento y lo coloca en una cola. La función principal lee esa cola sin congelar la interfaz.

En la portada:

- `OK` abre las tarjetas.
- `Back` termina la app.

En una tarjeta:

- Izquierda o arriba: tarjeta anterior.
- Derecha o abajo: tarjeta siguiente.
- `OK`: muestra el dato.
- `Back`: regresa a la portada.

En el dato, `OK` o `Back` vuelve a la tarjeta.

### E. Limpiar al salir

La última parte desactiva y libera la pantalla, la cola y la memoria. Este paso es importante: una app debe devolver al firmware todos los recursos que reservó.

## 6. Compilar

Abre PowerShell dentro de la carpeta del proyecto:

```powershell
ufbt
```

Si la compilación termina correctamente, obtendrás:

```text
dist/app_fit_xvii.fap
```

## 7. Instalar y probar por USB

Con el Flipper conectado y sin qFlipper ocupando el puerto:

```powershell
ufbt launch FLIP_PORT=COM3
```

Este comando compila, copia el FAP a la microSD y lo inicia. Después podrás encontrarlo en:

```text
Apps > Tools > APP FIT-XVII
```

## 8. Cambiar la app en el taller

El ejercicio más rápido es agregar una quinta tarjeta. Copia uno de los bloques dentro de `app_fit_topics[]`, cambia sus cinco textos, compila otra vez y ejecuta `ufbt launch`.

También puedes cambiar el título visible, pero recuerda:

- Si cambias `entry_point` en `application.fam`, debes cambiar el nombre de la función C.
- Mantén cada texto corto; la pantalla solo mide 128 píxeles de ancho.
- Evita tildes en fuentes básicas si no vas a usar caracteres gráficos propios.

## 9. Compartirlo en GitHub

Sube el código fuente, el manifiesto, el icono, la guía, el `README` y la licencia. No subas la carpeta temporal `.ufbt`. Puedes adjuntar el `.fap` compilado a una Release, indicando claramente:

- Modelo: Flipper Zero.
- Firmware usado para compilar.
- Target de hardware.
- Versión de API.
- Ruta sugerida: `/ext/apps/Tools/app_fit_xvii.fap`.

Quien use otro firmware debe instalar el SDK correspondiente y recompilar. Así evita presentar como universal un binario ligado a una API concreta.

## 10. Checklist antes de presentar

- La compilación termina sin errores.
- El Flipper acepta el FAP sin error de API.
- Las cuatro flechas cambian de tarjeta sin perder el contexto.
- `OK` abre y cierra el dato.
- `Back` siempre regresa y finalmente sale.
- La app continúa apareciendo en `Apps > Tools` después de reiniciar.