Desplegar y provisionar un panel Luckfox¶

Esta guía te lleva de un panel Luckfox en blanco a una terminal Smiley operando y vinculada a un sanitario. A diferencia del kiosk Android (que se instala con un APK), el Luckfox corre un binario nativo que se compila y se pushea por USB.

Para el detalle de arquitectura y config del panel, ver la referencia del kiosk Luckfox.

Prerequisitos¶

Necesitás	Detalle
WSL2 Ubuntu 22.04	El SDK de Luckfox solo soporta esa distro. En Windows: WSL2.
SDK de Luckfox	Clonado en `/home/pi/luckfox-pico` (no está en el repo).
El repo `workdone_luckyfox`	Con el toolchain configurado.
Cable USB-C	Para `adb`/SSH al panel (RNDIS gadget).
Acceso ADMIN al BackOffice	Para crear la terminal y obtener el código de vinculación.

Panorama del flujo¶

flowchart TD
    BUILD["1. make -j16 (WSL)<br/>build/caritas"] --> DEPLOY["2. adb push + install<br/>al panel"]
    DEPLOY --> BOOT["3. Reboot → arranca en modo kiosk"]
    ADMIN["BackOffice → Terminales Smiley<br/>+ Nueva → código 24h"] --> PAIR
    BOOT --> PAIR["4. Menú técnico → Re-vincular<br/>ingresás el código"]
    PAIR --> VINC["POST /api/v1/smiley/vincular<br/>obtiene device_uuid + api_key"]
    VINC --> OP["5. Operando: idle con backend OK"]

Paso 1 — Compilar¶

Dentro de WSL, desde la raíz del repo:

make -j16

Produce build/caritas (ELF ARM uClibc). El primer build compila LVGL + mbedTLS (tarda minutos); los siguientes solo recompilan lo que cambió.

Si tocaste lv_conf.h

El Makefile no trackea ese header. Forzá el rebuild del archivo de LVGL: rm -rf build/lvgl build/liblvgl.a && make -j16.

Paso 2 — Desplegar al panel¶

Con el panel conectado por USB:

# instalación completa (binario + init script, deshabilita la demo de fábrica)
# desde WSL, en la raíz del repo:
bash device/install.sh

O un push rápido del binario (para iterar):

adb push build/caritas /root/caritas
adb shell 'chmod +x /root/caritas; killall caritas'   # el watchdog lo relanza

El bit de ejecución

adb push resetea el bit de ejecución — hacé chmod +x después de cada push, o el watchdog no lo levanta.

Resultado: reiniciás y el panel arranca directo en la app (modo kiosk). Deberías ver las tres caritas.

Paso 3 — Conectar a la red¶

Desde el panel: menú técnico (10 toques sobre el logo Smiley en 2,5 s → PIN) → Configurar WiFi → elegís la red y tecleás la contraseña.

Verificás con el indicador WiFi abajo a la izquierda:

Color	Significado
🔴 Rojo	sin WiFi (no asociado)
🔵 Azul	asociado, pero el backend no responde
🟢 Verde	backend alcanzable ✓

Paso 4 — Crear la terminal y vincular¶

En el BackOffice (igual que el kiosk Android): andá a Terminales Smiley → + Nueva, elegís el sanitario, y obtenés un código de vinculación de un solo uso (vence en 24 h).

En el panel: menú técnico → Re-vincular → ingresás el código. El panel llama a POST /api/v1/smiley/vincular {codigo} y recibe device_uuid + api_key + su identidad legible (número de terminal, alias, sanitario), que persiste en config_local.

Bajo el capó

A partir de la vinculación, el panel se autentica en /api/v1/smiley/* con los headers X-Device-Uuid + X-Api-Key. La api_key viaja en texto plano una sola vez en la respuesta de /vincular; el backend solo guarda su hash.

Paso 5 — Verificar¶

El reposo muestra la línea de diagnóstico con backend OK y el indicador WiFi en verde.
La línea inferior muestra el número de terminal, sanitario y versión (ej. Terminal Nº2 · Baño Mujeres · Piso 1 · v0.1.0).
Registrá una opinión de prueba: al tocar una carita, ves "¡Gracias!" y en el log (/tmp/smiley.log) aparece una línea sync: drenando la opinión.

Apuntar a un backend de prueba (sin TLS)¶

Para probar contra un backend local:

# desde el menú: Servidor → http://<ip>:<port>   (http:// plano saltea TLS)
# o por archivo:
echo "http://192.168.0.10:8080" > /userdata/backend.conf
killall caritas

Volver a producción: rm /userdata/backend.conf && killall caritas.

Problemas comunes¶

Síntoma	Causa / solución
SSH por WiFi da timeout	El panel y tu laptop están en subredes distintas — usá la IP USB `169.254.148.50`, o poné ambos en la misma WiFi
Indicador WiFi rojo	no asociado — reconfigurá la WiFi desde el menú
Indicador azul (no verde)	asociado pero el backend no responde (red/DNS)
`sync: error de red` en el log	red caída o backend inalcanzable; se recupera solo
Nada en el panel tras el boot	revisá `/tmp/smiley.log`; asegurate de que la demo de fábrica (`86UI_demo`) no esté peleando por `/dev/fb0`
`adb push` y después "permission denied"	`adb push` resetea el bit de ejecución — `chmod +x` después de cada push

Los logs viven en /tmp/smiley.log (tmpfs, se resetea al reboot). La app imprime líneas backend:, ping:, vincular:, sync: y db:.