🛠 Troubleshooting

Errores habituales al reflashear un Pocket CHIP desde CachyOS / Arch.

waiting for FEL... TIMEOUT

Causa: El PC no ve el CHIP en modo FEL.

Soluciones (en orden):

1. Revisar puente pin 7 ↔ pin 39.
2. Cambiar cable micro-USB (debe ser de datos).
3. Probar puerto USB 2.0 directo (sin hub).
4. Desconectar, quitar puente, esperar 10 s, repetir secuencia FEL.
5. Alimentación extra: 5 V en pin CHG-IN mientras flasheas.
6. Elegir imagen No-Limit (pn en lugar de p).

Verificación:

sudo sunxi-fel ping

fastboot: invalid option -- 'i'

Causa: La versión de fastboot en Arch/CachyOS es demasiado nueva. Los scripts del CHIP usan -i para vendor ID, eliminado en fastboot moderno.

Comprobar:

fastboot --help 2>&1 | grep "\-i"

Si no aparece -i, necesitas fastboot antiguo o CHIP-tools parcheados.

Fix A — platform-tools r26 (recomendado si usas Flash-Chip-Arch)

cd /tmp
wget https://dl.google.com/android/repository/platform-tools_r26.0.1-linux.zip
unzip platform-tools_r26.0.1-linux.zip
export PATH="/tmp/platform-tools:$PATH"
fastboot --help 2>&1 | grep "\-i"   # debe aparecer ahora

cd ~/Flash-Chip-Arch
PATH="/tmp/platform-tools:$PATH" ./Flash.sh

Fix B — nytpu/CHIP-tools (ya sin -i en parte del script)

cd ~/CHIP-tools
FEL='sudo sunxi-fel' FASTBOOT='sudo fastboot' SNIB=false ./chip-update-firmware.sh -p

waiting for fastboot... TIMEOUT

Causa: Tras FEL, el CHIP reinicia en modo fastboot pero el PC pierde la conexión USB (cambio de ID).

Soluciones:

1. Asegurar reglas udev (Flash-Chip-Arch las crea en /etc/udev/rules.d/99-allwinner.rules).
2. Reiniciar el script — a menudo funciona al segundo intento.
3. No uses máquina virtual ni WSL.
4. Desactivar ahorro de energía USB en el portátil si existe.

Durante el timeout, monitoriza:

watch -n1 'lsusb | grep -E "1f3a|18d1"'

sunxi-nand-image-builder: command not found

Causa: El binario no viene en el paquete sunxi-tools de Arch.

Fix:

git clone --branch v1.4.1 https://github.com/linux-sunxi/sunxi-tools.git
cd sunxi-tools
make install-all install-misc
# Si sigue fallando, copiar manualmente:
sudo cp sunxi-nand-image-builder /usr/local/bin/

FLASH VERIFICATION FAILED

Causas posibles:

• Descarga corrupta → usar opción f (force clean) en Flash.sh
• Puente FEL se movió durante el flash
• Alimentación insuficiente
• fastboot incompatible (ver error -i)

Acción: Ctrl+C, desconectar, repetir desde FEL con imagen pn y cable/puerto distintos.

apt update muy lento o "Waiting for headers"

Síntoma: apt update se queda en Waiting for headers minutos sin avanzar.

Causa: Líneas rotas en sources.list (mirrors Jessie activos, nextthing.co, http.debian.net).

Solución: Limpiar sources.list y dejar solo archive.debian.org + chip.jfpossibilities.com. Ver 00-mi-recovery.md paso 7. Luego:

wget -O deploy.sh https://pocketchip.2red.com.es/deploy.sh
sudo INTERACTIVE=0 bash deploy.sh

En Pocket CHIP, 1–3 min por repo puede ser normal; 10+ min sin cambiar = atascado.

PICO-8: icono carga y vuelve a Pocket Home

Causa: Binario en /usr/lib/pico8/pico8 pero el launcher usa /usr/lib/pico-8/pico8.

Fix:

sudo ln -sfn /usr/lib/pico8 /usr/lib/pico-8
sudo wget -O /usr/lib/pico8/libcurl.so.3 \
  https://raw.githubusercontent.com/mackemint/PocketCHIP-buster-update/main/assets/libcurl.so.3

Probar: LD_PRELOAD=/usr/lib/pico8/libcurl.so.3 /usr/lib/pico-8/pico8

Tras upgrade a Buster: PICO-8 reloj y vuelve al home

Síntoma: icono carga → reloj → vuelta a Pocket Home (Make Music u otras apps pueden ir bien).

Causa: Pocket Home lanza /usr/lib/pico-8/pico8 sin LD_PRELOAD=libcurl.so.3 — en Buster el binario necesita la libcurl antigua explícita (symlink solo no basta).

Fix:

sudo tee /usr/local/bin/pico8-chip << 'EOF'
#!/bin/sh
cd /usr/lib/pico-8 || exit 1
export LD_PRELOAD=/usr/lib/pico-8/libcurl.so.3
exec /usr/lib/pico-8/pico8 -splore "$@"
EOF
sudo chmod +x /usr/local/bin/pico8-chip

Actualiza el icono en /usr/share/pocket-home/config.json → "shell": "/usr/local/bin/pico8-chip" o ejecuta upgrade-buster-post.sh.

Probar: DISPLAY=:0 LD_PRELOAD=/usr/lib/pico-8/libcurl.so.3 /usr/lib/pico-8/pico8

Tras upgrade a Buster: error rojo Awesome

Síntoma: rc.lua:37 attempt to call a nil value (field 'add_signal') u otros errores en Awesome.

Causa: ~/.config/awesome/rc.lua de Jessie (Awesome 3) en Buster (Awesome 4).

Fix: usar rc.lua de mackemint — no el genérico de /etc/xdg/awesome/. Ejecuta pocketchip-load y pocket-home al arrancar.

wget -O ~/.config/awesome/rc.lua \
  https://raw.githubusercontent.com/mackemint/PocketCHIP-buster-update/main/assets/rc.lua
sudo reboot

Si Wi‑Fi sigue sin redes: nmcli device status, conectar con ifname wlan0 o wlan1, o apagado completo (no solo reboot). Ver 08-upgrade-buster.md.

Tras upgrade a Buster: Wi-Fi no lista redes

Causa: Reboot sin reconexión automática; Pocket Home no autostarteado.

Fix:

sudo rfkill unblock all
nmcli radio wifi on
sudo systemctl start NetworkManager
nmcli connection show
nmcli connection up "TU_RED"

PICO-8: controles y salir del juego

El Pocket CHIP no tiene tecla Esc dedicada en partida. Flujo probado (ej. Celeste):

1. Dentro del juego: pulsa Enter → menú de pausa
2. Salir a la lista de juegos (Splore)
3. En la lista: Esc → otro menú → salir de PICO-8

Esc no responde dentro del juego — es normal. Solo funciona en menús (Splore, consola).

Síntoma: Errores en apt update con URLs que parecen mal (http://http.debian.net).

Explicación: El hostname http.debian.net es real (por eso se ve doble "http"). Pero Jessie está archivado y esos mirrors fallan.

Solución: Usar archive.debian.org. Ver 05-post-flash.md o el deploy.sh actualizado en la web.

Flash termina OK pero sigue en logo CHIP

1. Espera 5 minutos — primer boot es lento.
2. ¿Quitaste el puente FEL antes de encender en el Pocket?
3. ¿Reinsertaste bien el CHIP en la carcasa?
4. Prueba hard reset: Power 10 s apagado, soltar, Power 2 s encender.
5. Si nada: reflashear otra vez con f (force clean).

Pantalla negra pero LEDs activos

• Panel LCD dañado (común en unidades viejas).
• Conecta UART 3.3 V (TX/RX/GND) para ver si Linux arranca sin pantalla.
• Si UART muestra login OK → problema de display, no de flash.

UART: 115200 8N1, adaptador 3.3 V (no 5 V).

Flash-Chip-Arch: el script no flashea / termina sin mensaje

El repo original tiene lógica frágida en install_chip_tools. Si falla:

1. Clona CHIP-tools manualmente:

cd ~/Flash-Chip-Arch
git clone https://github.com/Project-chip-crumbs/CHIP-tools.git
cd CHIP-tools
FEL='sudo sunxi-fel' FASTBOOT='sudo fastboot' SNIB=false ./chip-update-firmware.sh -p

2. O usa directamente nytpu/CHIP-tools.

Tabla rápida

Cuándo pedir ayuda

Documenta y pregunta en r/ChipCommunity con:

• Distro exacta (uname -a)
• Salida de lsusb en FEL
• Últimas 20 líneas del script de flash
• Imagen elegida (p, pn, etc.)