⬆ Guía 09

⬆ Upgrade Buster

Guía para quien ya tiene el Pocket CHIP estable con el Método Revive (Jessie + deploy.sh) y quiere Debian 10 (Buster) con repos más recientes y mejor soporte de paquetes.

No es obligatorio. Jessie funciona bien para PICO-8, SSH y uso retro. Solo hazlo si entiendes el riesgo y tienes FEL listo para reflashear.

Estado: ✅ Probado en hardware — Julio 2026. Buster 10.13, Pocket Home, Wi‑Fi, Make Music y PICO-8 (Splore) OK.

Resumen
Ruta Jessie (8) → Stretch (9) → Buster (10) — nunca saltar pasos
Tiempo 1–3 horas (descargas + reboots)
Conexión SSH + tmux instalado (Jessie no lo trae por defecto)
Plan B FEL + Flash-Chip-Arch opción p → deploy.sh

Prerrequisitos

  1. Método Revive completado y verificado (apt update, SSH, Pocket Home).
  2. Batería cargada o alimentación estable.
  3. Espacio libre en NAND (~500 MB mínimo recomendado): df -h /
  4. FEL preparado — Checklist FEL + Recovery CachyOS.
  5. tmux instalado — en Jessie stock no viene instalado; hay que instalarlo antes del upgrade:
sudo apt update
sudo apt install tmux
tmux new -s upgrade

Quédate dentro de tmux para todo el proceso (descargas, scripts, apt full-upgrade). Si se cae el SSH: tmux attach -t upgrade.

Si tmux dice need UTF-8 locale:

export LC_ALL=C.UTF-8
export LANG=C.UTF-8
tmux new -s upgrade

Si falta el locale: sudo apt install locales && sudo locale-gen C.UTF-8

Alternativa: sudo apt install screen y luego screen -S upgrade (salir sin matar: Ctrl+A, D · volver: screen -r upgrade). O ejecutar desde la consola local del Pocket CHIP con teclado.

Scripts (alojados en esta web)

Paso Script Cuándo
1 upgrade-to-stretch.sh En Jessie (8.x)
reboot — Verificar cat /etc/debian_version → 9.x
2 upgrade-to-buster.sh En Stretch (9.x)
reboot — Verificar → 10.x
3 upgrade-buster-post.sh En Buster — PICO-8, teclado, SSH

Descarga desde el Pocket CHIP (dentro de tmux):

sudo apt install tmux    # obligatorio en Jessie — no viene por defecto
tmux new -s upgrade

wget https://pocketchip.2red.com.es/upgrade-to-stretch.sh
chmod +x upgrade-to-stretch.sh
sudo ./upgrade-to-stretch.sh

Tras cada reboot: tmux new -s upgrade (o tmux attach -t upgrade) y el script siguiente.

Archivos de referencia (incluidos en los scripts): /upgrade/ — sources.list y xorg.conf por versión.

Paso 1 — Jessie → Stretch

wget https://pocketchip.2red.com.es/upgrade-to-stretch.sh
chmod +x upgrade-to-stretch.sh
sudo ./upgrade-to-stretch.sh

El script:

Al terminar:

sudo reboot

Verifica:

cat /etc/debian_version    # debe ser 9.x
uname -r                   # ideal: armmp — en muchos CHIP sigue 4.4.13-ntc-mlc (ver abajo)

Si Pocket Home o el escritorio no arrancan bien, prueba consola local o SSH. Si el sistema no responde → FEL y reflasheo.

Preguntas Y/I/N/O durante Stretch (dpkg)

Archivo Tecla (CHIP stock) Por qué
/etc/systemd/journald.conf Y / I Config genérica de logs
/etc/securetty Y / I Terminales root — no suele estar customizada
/etc/lightdm/lightdm.conf N / O Conserva autologin chip y Pocket Home

Avisos normales (Stretch)

Warning: root device  does not exist
Kernel ... ntc-mlc does not match ... flavors (armmp), therefore not writing it to flash
flash-kernel: installing version 4.9.0-19-armmp
Installing new boot.scr

El kernel armmp se instala; U-Boot NTC puede seguir arrancando 4.4.13-ntc-mlc. No bloquea el paso a Buster si SSH funciona.

No uses: sudo flash-kernel -v 4.9.0-19-armmp — -v es verbose, no versión. Correcto: sudo flash-kernel 4.9.0-19-armmp

Paso 2 — Stretch → Buster

wget https://pocketchip.2red.com.es/upgrade-to-buster.sh
chmod +x upgrade-to-buster.sh
sudo ./upgrade-to-buster.sh

El script:

sudo reboot

Verifica: cat /etc/debian_version → 10.x

Preguntas Y/I/N/O durante Buster (dpkg)

Archivo Tecla (CHIP stock)
/etc/security/limits.conf Y (o Enter = N, también OK)
/etc/plymouth/plymouthd.conf N — splash del CHIP
/etc/lightdm/lightdm.conf N — autologin y Pocket Home

Regla: config genérica del sistema → Y. Pantalla / login / splash / Pocket Home → N.

Paso 3 — Post-upgrade Buster

Orden recomendado (si ya pusiste el rc.lua de mackemint a mano, ejecuta igualmente el post-script para PICO-8):

# 1. rc.lua Pocket CHIP (Wi-Fi + Pocket Home al arrancar) — obligatorio en Buster
wget -O ~/.config/awesome/rc.lua \
  https://raw.githubusercontent.com/mackemint/PocketCHIP-buster-update/main/assets/rc.lua

# 2. PICO-8, teclado FN, SSH, paquetes Pocket
wget https://pocketchip.2red.com.es/upgrade-buster-post.sh
chmod +x upgrade-buster-post.sh
sudo ./upgrade-buster-post.sh

sudo poweroff

El post-script:

PICO-8 tras Buster

Síntoma (probado Jul 2026): icono PICO-8 → reloj de carga → vuelve a Pocket Home. Make Music puede ir bien. El binario y el symlink están OK; en Buster Pocket Home no pasa LD_PRELOAD=libcurl.so.3 al lanzar.

Diagnóstico: esto sí funciona en la pantalla del CHIP:

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

Fix — wrapper + actualizar Pocket Home (upgrade-buster-post.sh lo hace automáticamente):

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 /usr/share/pocket-home/config.json. En stock suele ser "shell": "pico8" (no la ruta completa):

sudo sed -i 's|"shell": "pico8"|"shell": "/usr/local/bin/pico8-chip"|g' /usr/share/pocket-home/config.json
grep -A1 -B1 pico8 /usr/share/pocket-home/config.json
killall pocket-home
DISPLAY=:0 pocket-home &

Verificar symlink (sigue haciendo falta):

ls -la /usr/lib/pico-8/pico8 /usr/lib/pico-8/libcurl.so.3

PICO-8 en juego: Enter = pausa · Ctrl+Q = cerrar.

Kernel tras el upgrade

Investigación Jul 2026 — tras completar Buster en hardware real, con varios intentos de flash-kernel y revisión de la documentación comunitaria actual (PocketTRIX, Armbian, macromorgan, nytpu, mackemint).

Estado real en hardware probado

cat /etc/debian_version   # 10.13 ✅
uname -r                  # 4.4.13-ntc-mlc ⚠️ (kernel NTC de Jessie, no armmp)
Capa Estado
Userspace Debian Stretch → Buster ✅ (10.13)
Kernel en marcha 4.4.13-ntc-mlc (Next Thing Co., 2016)
Kernels instalados (dpkg) linux-image-4.4.13-ntc-mlc, linux-image-4.9.0-19-armmp, linux-image-4.19.0-27-armmp
/boot/boot.scr Actualizado por flash-kernel → apunta a armmp
U-Boot NTC en NAND Sigue arrancando el kernel legacy
fw_printenv Falla — env corrupto (Bad CRC en mtd3)
¿Bloquea el uso diario? No — SSH, apt, Pocket Home, Wi‑Fi, PICO-8 OK

Por qué flash-kernel no cambia uname -r

En el Pocket CHIP el arranque depende del U-Boot legacy de Next Thing Co. grabado en NAND, no solo de los ficheros en /boot:

  1. flash-kernel instala vmlinuz, initramfs, DTB y regenera boot.scr en el rootfs (dentro de la partición UBI, mtd4).
  2. boot.scr puede apuntar correctamente al kernel armmp (fk_kvers '4.9.0-19-armmp' o 4.19.0-27-armmp).
  3. U-Boot NTC puede ignorar ese script o usar otra ruta de arranque (SPL, env vars, imagen embebida) y cargar igualmente 4.4.13-ntc-mlc.
  4. Con fw_printenv / fw_setenv rotos (mtd3 Bad CRC) no se puede inspeccionar ni corregir variables de entorno de U-Boot de forma segura.

Avisos normales durante el upgrade (no significan fallo del script):

Warning: root device  does not exist
Kernel ... ntc-mlc does not match ... flavors (armmp), therefore not writing it to flash
flash-kernel: installing version 4.9.0-19-armmp   # o 4.19.0-27-armmp
Installing new boot.scr

Layout NAND relevante (CHIP/Pocket CHIP):

MTD Contenido
mtd3 U-Boot env — frágil; CRC corrupto impide fw_printenv
mtd4 rootfs UBI (UBIFS) — aquí vive /boot
— No hay partición /boot separada como en PC

Conclusión: el upgrade Jessie → Buster actualiza paquetes y userspace, pero no sustituye de forma fiable el kernel NTC en NAND con linux-image-armmp vía apt + flash-kernel.

Lo que ya se probó (sin éxito en boot)

Intento Resultado
flash-kernel tras Stretch (4.9.0-19-armmp) boot.scr OK; uname -r sigue 4.4.13-ntc-mlc
dpkg-reconfigure linux-image-4.9.0-19-armmp + reboot Igual
flash-kernel 4.19.0-27-armmp tras Buster + poweroff Igual
strings /boot/boot.scr | grep armmp Confirma que el script apunta a armmp — U-Boot no lo usa

Comandos de diagnóstico útiles:

dpkg -l 'linux-image*' | grep ^ii
ls -la /boot/vmlinuz* /boot/boot.scr
strings /boot/boot.scr | grep -E 'fk_kvers|vmlinuz|armmp|ntc'
uname -r
sudo flash-kernel    # muestra qué versión intenta instalar

No uses: sudo flash-kernel -v VERSION — -v es verbose, no versión. Correcto: sudo flash-kernel 4.19.0-27-armmp.

kaplan2539/CHIP-Debian-Kernel — no es la solución

mackemint enlaza a kaplan2539/CHIP-Debian-Kernel, pero ese repo:

No instalar en Buster desde ese repo Jessie — riesgo de dependencias rotas sin beneficio real.

Opciones para el kernel (de más segura a más arriesgada)

Opción A — Quedarse en kernel NTC (recomendado si todo funciona)

Opción B — Último reintento flash-kernel in-place (baja probabilidad)

Solo si quieres cerrar el tema antes de pasar a PocketTRIX:

sudo flash-kernel 4.19.0-27-armmp
sync
sudo poweroff    # apagado completo ~10 s, no solo reboot

Tras encender: uname -r. Si sigue en 4.4.13-ntc-mlc, no insistas — el U-Boot NTC no cooperará sin reflashear el bootloader.

Opción C — PocketTRIX / imagen comunitaria (próximo paso planificado)

Para kernel moderno (Debian 13, linux-image-armmp 6.x) hace falta imagen nueva + FEL, no un apt upgrade sobre Buster:

Proyecto Kernel NAND Boot externo Estado
PocketTRIX 6.12+deb13-armmp Experimental (validado mayo 2026, 1× Toshiba 4G MLC) USB/FEL — camino más seguro i3, teclado, Wi‑Fi en desarrollo activo
paulolc/pocketchip-armbian-build Linux 6.18.x + Debian 13 Probado (WIP) SWUpdate / FEL Teclado, Wi‑Fi, X11 OK; touchscreen/GPU Mali no
macromorgan/chip-debroot Mainline armmp custom WIP FEL / USB Requiere compilar kernel con CONFIG_RTL8723BS, CONFIG_KEYBOARD_TCA8418, particiones MTD
Armbian pocketchip-sd 6.6+ mainline Boot desde SD (MMC2) SD obligatoria Evita NAND; requiere mod/hardware extra
macromorgan gist — mainline NAND 5.10-rc NAND manual FEL Autor: "super unstable" — no recomendado
Hotchip Bookworm No in-place USB/SD Alternativa Bookworm boot externo

Ruta recomendada para kernel moderno: probar PocketTRIX por FEL/USB primero; mantener la NAND con Buster+NTC como backup hasta validar. Ver Roadmap — Fase 5.

Antes de flashear PocketTRIX:

  1. FEL + cable listos — Checklist FEL.
  2. Plan B: volver a Jessie con Flash-Chip-Arch opción p → deploy.sh.
  3. UART 3.3 V opcional pero muy útil para depurar boot (PocketTRIX lo recomienda).
  4. Identificar NAND (Toshiba vs Hynix) — Hynix puede necesitar parches extra en kernels < 5.16 (macromorgan/chip-debroot).

Opción D — Boot externo sin tocar NAND Buster

Si quieres Linux moderno sin borrar tu Buster actual en NAND:

Resumen visual

┌──────────────────────────────────────────────────────────────┐
│  Buster + kernel NTC 4.4.13   →  USAR ASÍ (probado, OK)     │
│  Kernel armmp in-place         →  Muy improbable en NAND NTC │
│  Kernel 6.x moderno            →  PocketTRIX / Armbian       │
│                                  (FEL + imagen nueva)        │
└──────────────────────────────────────────────────────────────┘

Decisión del proyecto (Jul 2026)

Decisión Motivo
Buster+NTC como daily driver Todo lo esencial funciona; no arriesgar NAND
PocketTRIX en siguiente sesión Única vía realista a kernel 6.x; probar por FEL/USB
No más flash-kernel agresivo Varios intentos sin cambio en uname -r
No fw_setenv a ciegas Env mtd3 corrupto — puede dejar la NAND irrecuperable

Pantalla: Awesome y Pocket Home (post-Buster)

Tras el upgrade, Awesome 4 (Buster) no entiende el ~/.config/awesome/rc.lua de Jessie (Awesome 3).

Síntoma: error rojo attempt to call a nil value (field 'add_signal') — en la línea 37 de rc.lua está el manejador de errores, no la causa.

Fix correcto — usar el rc.lua de Pocket CHIP para Buster (mackemint/PocketCHIP-buster-update), no el genérico de /etc/xdg/awesome/:

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

Ese rc.lua al arrancar ejecuta:

Si pusiste el rc.lua genérico de Buster (como en nuestra guía inicial), quitaste el error rojo pero dejaste de cargar Wi‑Fi al boot — por eso SSH funcionaba antes del cambio y tras el reboot pareció “roto”.

También incluido en upgrade-buster-post.sh (versión actualizada en la web).

Wi-Fi tras reboot

No es que el rc.lua “apague” el chip Wi‑Fi — al cambiarlo y reiniciar dejaste de ejecutar pocketchip-load y Pocket Home al inicio. La comunidad (mackemint, nytpu) documenta además:

  1. NetworkManager.conf — el RTL8723BS no soporta MAC randomization (ya lo pone upgrade-to-stretch.sh).
  2. wlan0 vs wlan1 — tras upgrade la interfaz puede ser wlan1; ambas pueden salir unmanaged.
  3. Power cycle — a veces hace falta apagado completo (Power ~10 s), no solo reboot, para que el Wi‑Fi arranque (Reddit papasfritas).

Reconectar por terminal:

cat /etc/NetworkManager/NetworkManager.conf   # debe tener wifi.mac-address-randomization
nmcli device status
sudo rfkill unblock all
nmcli radio wifi on
sudo systemctl restart NetworkManager
nmcli device wifi rescan
nmcli device wifi list

Conectar (prueba wlan0 y si falla wlan1):

sudo nmcli device wifi connect "TU_RED" password "CLAVE" ifname wlan0
# o:
sudo nmcli device wifi connect "TU_RED" password "CLAVE" ifname wlan1

Si nmcli muestra unmanaged en wlan0/wlan1, revisa que NetworkManager.conf no se haya sobrescrito en el upgrade. Evita wpa_supplicant en paralelo con NetworkManager (mackemint).

Carga manual mientras arreglas el arranque:

sudo /usr/sbin/pocketchip-load
DISPLAY=:0 pocket-home &

Verificación final (hardware Jul 2026)

Check Resultado
Debian Buster ✅ 10.13
Pocket Home + Wi‑Fi ✅ con rc.lua mackemint
Make Music ✅
PICO-8 desde Pocket Home ✅ pico8-chip + -splore + LD_PRELOAD
Kernel 4.4.13-ntc-mlc (NTC; usable)
SSH + apt ✅
Teclas FN Por verificar
apt autoremove ❌ no ejecutar

PICO-8 en juego: Enter = pausa · Ctrl+Q = cerrar · ver Método Revive — controles.

Qué NO hacer

❌ Por qué
apt dist-upgrade directo Jessie → Buster Rompe dependencias y Pocket Home
apt autoremove tras el upgrade Documentado — borra paquetes que Pocket Home necesita; apt lo sugerirá al final
sudo flash-kernel -v VERSION -v es verbose, no versión — usa sudo flash-kernel 4.19.0-27-armmp
Cerrar SSH sin tmux/screen Proceso interrumpido = sistema a medias
Upgrade sin FEL listo Sin plan B si la NAND queda corrupta
fw_setenv sin saber Puede romper arranque NAND

Si algo sale mal

  1. SSH aún responde — no reinicies a ciegas. Revisa /var/log/apt/term.log.
  2. Pantalla negra pero SSH OK — revisa /etc/X11/xorg.conf; copia desde xorg-buster.conf o reflashea.
  3. No arranca — FEL + Flash-Chip-Arch opción p → deploy.sh.
  4. PICO-8: reloj y vuelve al home — symlink + libcurl (igual que Jessie). Ver PICO-8 tras Buster o upgrade-buster-post.sh.

Alternativa: Pocket-Home Bismuth (más apps, mismo Buster)

Sin reflashear ni cambiar kernel: sustituir el launcher stock por Pocket-Home Bismuth — menú con flechas, carpetas y edición desde la UI.
Guía 10-pocket-home-bismuth.md 🧪 en prueba
Script wget https://pocketchip.2red.com.es/install-bismuth.sh
Rollback sudo apt install --reinstall pocket-home + restaurar config.json

Alternativa: Linux moderno (PocketTRIX y similares)

Si quieres kernel 6.x y Debian reciente, la vía no es seguir con apt en Buster — es flashear una imagen comunitaria por FEL/USB/SD.

Próximo paso planificado en este proyecto: probar PocketTRIX (Debian 13 Trixie, 6.12+deb13-armmp, entorno i3).

Ventaja Detalle
Kernel actual Mainline Debian armmp, no NTC 4.4
Desarrollo activo Validación NAND mayo 2026 (experimental)
Recuperación FEL/USB es el loop seguro; NAND Buster queda como backup hasta confirmar

Otros proyectos: Hotchip (Bookworm, boot externo), paulolc/pocketchip-armbian-build (Armbian 6.18.x).

Detalle completo en Kernel tras el upgrade y Roadmap — Fase 5.

Referencias

Upgrade Jessie → Buster

Launcher comunitario

Kernel y Linux moderno

Resumen en una línea

Jessie OK → apt install tmux → tmux → upgrade-to-stretch → reboot → upgrade-to-buster → reboot → upgrade-buster-post → listo