🚀 PocketTRIX NAND
Guía para instalar PocketTRIX (Debian 13 + kernel mainline + i3) en la NAND del Pocket CHIP, sin depender del pendrive para el arranque diario.
Estado: ✅ Probado en hardware — Septiembre 2026. Unidad Toshiba 4G MLC (
400000-4000-500), host Arch/Omarchy, UART CH341.
Importante: esto borra Jessie/Buster de la NAND. Ten plan B: imagen USB PocketTRIX o reflasheo stock (Método Revive).
Qué conseguimos
| OS | Debian 13 (Trixie) armhf |
| Kernel | 6.12.x+deb13-armmp |
| UI | i3 + teclado Pocket CHIP |
| Arranque | Desde NAND (sin pendrive) |
| Usuario | chip — en el primer boot suele pedir crear contraseña |
| Mod | En i3, Mod = Alt (izquierda del espacio) |
Por qué no es un flash “de una sola pasada”
En Toshiba MLC, Linux rechaza UBI “normal” (ubi: refuse attaching … MLC NAND). PocketTRIX usa SLC-on-MLC: la partición UBI lleva slc-mode y se escribe con helpers .slc-mode (~2× tamaño físico).
Hay tres capas distintas:
| Paso | Qué escribe | Comando típico |
|---|---|---|
| 1. Boot area | SPL, U-Boot, kernel, DTB, initrd (primeros ~80 MiB) | nand-flash-bootloader-slc o el full flash |
| 2. Rootfs por fastboot | Imagen UBI sparse desde U-Boot | nand-flash-legacy-slc |
| 3. Rootfs por rescue | ubiformat + ubiupdatevol desde Linux |
nand-rescue-install-usb-slc |
En la unidad de prueba, el paso 2 dejó ECC en UBI (PEB 3) y el kernel caía a (initramfs). El paso 3 por USB sí dejó Debian usable. Asume que el rescue USB es parte del camino, no un accidente.
NAND (simplificado)
├── 0x00000000 … ~80 MiB boot (SPL / U-Boot / zImage / DTB / initrd)
└── 0x05000000 … fin UBI rootfs (Debian)
Requisitos
| Host | Arch / Omarchy / CachyOS (no WSL) |
| Repo | pocketchip-debian-builder (rama con soporte NAND SLC) |
| UART | Adaptador 3.3 V (p. ej. CH341) en /dev/ttyUSB0, jumper en TTL |
| FEL | Micro-USB OTG al PC + botón FEL o puente FEL↔GND |
| Pendrive | ≥2 GB con espacio libre — va al USB host del Pocket en el rescue |
| NAND | Validado: Toshiba 4G MLC. Otras (Hynix, etc.) no están confirmadas aquí |
lsusb en FEL debe mostrar 1f3a:efe8.
Flujo recomendado (resumen)
- Construir imagen USB PocketTRIX y probarla por FEL/USB (Wi‑Fi, teclado, i3).
- Construir artefacts NAND SLC (
uboot-legacy-mlc-pc-slc+nand-image-mlc-pc-slc). - Pocket en FEL + UART →
CONFIRM_NAND_WRITE=YES make nand-flash-legacy-slc. - Si al arrancar hay ECC / UBIFS error → rescue USB (abajo).
- Primer boot: crear password de
chip, Wi‑Fi, SSH.
Todas las escrituras destructivas exigen CONFIRM_NAND_WRITE=YES y flags --i-understand-… del script.
1. Build en el host (Arch)
Upstream oficial + patches locales si hace falta (GCC reciente, sys/sysmacros.h, initrd lean, PATH de update-initramfs).
cd ~/pocketchip-debian-builder # o tu clone
export UPSTREAMS_DIR=~/upstreams
export PATH="$PWD/build/host-tools/bin:$PATH"
# Cross soft-float para U-Boot legacy CHIP
paru -S --needed arm-linux-gnueabi-binutils arm-linux-gnueabi-gcc
sudo pacman -S --needed mtd-utils android-tools uboot-tools sunxi-tools
make uboot-legacy-mlc-pc-slc
sudo env UPSTREAMS_DIR="$UPSTREAMS_DIR" \
NAND_UBOOT_DIR="$PWD/build/u-boot-legacy-mlc-pc-slc" \
NAND_FORMATS=toshiba-4g-mlc \
NAND_SLC_MODE=1 \
NAND_BUILD_DIR="$PWD/build/nand-slc" \
NAND_IMAGE_DIR="$PWD/build/nand-slc/images" \
./scripts/build-nand-image.sh
Trampa del initrd (SLC)
En modo SLC, write.slc-mode ~duplica el uso físico. La ventana hasta UBI (0x02400000 → 0x05000000) solo aguanta ≤ ~20 MiB lógicos de initrd.
MODULES=most + gzip puede salir ~26 MiB → NAND write to offset 5400000 failed -5. Solución: initrd lean (MODULES=list + ofpart/sunxi_nand/ubi/ubifs) ≈ 9 MiB. Si el script dice “complete” pero UART muestra written: ERROR, no está bien — rehace la imagen.
2. Flash boot + UBI (fastboot)
Pocket en FEL, UART conectado, jumper FEL quitado tras entrar en modo FEL (según tu flujo habitual):
cd ~/pocketchip-debian-builder
export PATH="$PWD/build/host-tools/bin:$PATH"
CONFIRM_NAND_WRITE=YES make nand-flash-legacy-slc
Solo refrescar boot (sin tocar UBI):
CONFIRM_NAND_WRITE=YES make nand-flash-bootloader-slc
Apaga, enciende sin FEL. Mira UART:
- Arranque OK hasta multi-user → listo.
(initramfs)+ECC error/cannot read … LEB→ sigue al rescue.
3. Rescue USB (el que funcionó aquí)
g_ether (rescue por red) falló en esta unidad. Vía USB:
# En el PC — construir initramfs rescue que lee del stick
make nand-rescue-initramfs-usb-slc
# Preparar pendrive montado (p. ej. /run/media/$USER/…)
sudo ./scripts/prepare-nand-rescue-usb.sh /ruta/al/mount
sync
# Desmontar con seguridad
Físicamente:
- Pendrive con
pocketchip/rootfs.ubifs(~787 MB en la prueba). - Stick en el USB host del Pocket (puerto de la carcasa), no el OTG de FEL.
- OTG/micro-USB al PC en FEL.
- UART al PC.
CONFIRM_NAND_WRITE=YES make nand-rescue-install-usb-slc
El rescue formatea UBI y escribe el volumen desde el mismo stack sunxi_nand/UBI que usará el sistema en runtime. Cuando termine: apaga, quita FEL, enciende normal.
4. Primer arranque
- Puede pedir crear contraseña para
chip(passwd). - Terminal i3: Alt + Enter.
- Chuleta en dispositivo: Alt + Shift + / o comando
cheat. - Documento de atajos: atajos-teclado.html.
Ajustes útiles post-install (SSH):
sudo timedatectl set-timezone Europe/Madrid
# En ~/.config/i3/config — fuente más legible en la barra:
# font pango:DejaVu Sans Mono 10
i3-msg reload
5. Wi‑Fi que “no encuentra la red” (r8723bs)
El Pocket CHIP solo ve 2.4 GHz. Con Debian 13 + driver r8723bs es habitual:
- NetworkManager tarda ~30–40 s al boot
- De pronto: Activation failed: the Wi‑Fi network could not be found
- El perfil guardado existe, pero el scan no ve el SSID
Recuperación rápida (en el Pocket)
| Cómo | Comando / atajo |
|---|---|
| Atajo i3 | Alt + Shift + u |
| CLI | wifi-fix o lab wifi |
| Con SSID | wifi-fix 'MOVISTAR_XXXX' |
wifi-fix hace: desbloquear radio → iw reg set ES → reiniciar NetworkManager → si no hay APs, recargar r8723bs → rescan → nmcli con up del perfil guardado.
Si sigue fallando
- Comprueba que el router emite 2.4 GHz (no solo 5 GHz) y acércate.
- Lista redes:
nmcli dev wifi rescan; nmcli dev wifi list - Último recurso: reboot (a menudo el driver vuelve).
- Sin Wi‑Fi: consola por UART (CH341 TTL, 115200) — mismo cableado que el flash NAND.
Autologin + i3
Para que tras reboot entre solo al escritorio:
# /etc/systemd/system/[email protected]/autologin.conf
[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin chip --noclear %I $TERM
Con POCKETCHIP_BOOT_TO_I3=1 en /etc/default/pocketchip-ui, el login en tty1 lanza i3.
6. Perfil homelab / cyberdeck
Objetivo: el Pocket como mando del lab (SSH, Ember, agentes), no como daily driver.
Ember universal (em)
CLI ligero contra https://ember.2red.com.es (misma verdad que Cursor):
| Comando | Qué hace |
|---|---|
em health |
Ping API |
em focus --local |
¿En qué enfocarse? |
em list --status inbox |
Inbox |
em add "idea" |
Capturar |
lab status / lab focus / lab wifi |
Atajos homelab |
Config: ~/.ember/remote.env (EMBER_API_URL + Basic auth). Binarios en /usr/local/bin (em, ember-deck, lab).
Atajos i3: Alt+e focus · Alt+Shift+i inbox · Alt+o overview.
SSH a hosts del lab
Plantilla en el dispositivo (~/.ssh/config o Include):
Host gitea
HostName gitea.2red.com.es
User lunch
Host ember-host
HostName ember.2red.com.es
User lunch
# Host proxmox
# HostName 192.168.1.10
# User root
Host *
ServerAliveInterval 30
ServerAliveCountMax 4
Luego: ssh gitea, o lab ssh para listar Host definidos. Añade Proxmox/NAS/Coolify según tu red.
Claves: preferible ssh-copy-id desde el Pocket (o copiar ~/.ssh/id_ed25519.pub) para no depender de contraseñas en pantalla pequeña.
Menú mental del cyberdeck
| Quiero… | Acción |
|---|---|
| Ideas / focus | Alt+e o em focus |
| Wi‑Fi caído | Alt+Shift+u / wifi-fix |
| Entrar a un host | ssh gitea (etc.) |
| Consola sin Wi‑Fi | UART CH341 @ 115200 |
Errores que vimos (y qué significan)
| Síntoma | Causa | Qué hacer |
|---|---|---|
NAND write … failed -5 en offset initrd |
Initrd demasiado grande en SLC | Rebuild con MODULES=list, ≤20 MiB |
ubi: refuse attaching … MLC |
UBI sin slc-mode |
Usar path SLC del builder |
ECC error PEB / cae a initramfs tras full flash |
UBI escrita por fastboot ilegible para Linux | Rescue USB |
g_ether no arranca en rescue |
Frecuente en este hardware | Rescue por stick |
Script “complete” pero UART written: ERROR |
Bug antiguo de detección | No confiar; mirar UART siempre |
| Wi‑Fi network could not be found | Scan r8723bs vacío / AP solo 5 GHz |
wifi-fix / Alt+Shift+u · reboot |
Relación con Revive (Jessie/Buster)
| Camino | Cuándo |
|---|---|
| Método Revive + Buster | Quieres stock usable, PICO-8, bajo riesgo |
| Esta guía (PocketTRIX NAND) | Quieres Debian 13 + kernel 6.x en NAND y aceptas FEL/UART/rescue |
No mezclar: PocketTRIX reemplaza el stack NTC en NAND. Para volver atrás, reflashea stock con Flash-Chip-Arch.
Límites conocidos
- Validado solo en Toshiba 4G MLC de la unidad del proyecto.
- Capacidad usable ~mitad (SLC-on-MLC).
- GPU Mali / touchscreen: según build upstream; no es el foco de esta guía.
- El builder vive en GitHub (m4xx3d0ut); aquí solo documentamos el camino que funcionó.
Referencias
- Upstream: m4xx3d0ut/pocketchip-debian-builder —
docs/nand.md - FEL hardware: 03-fel-checklist.md
- Roadmap: 06-roadmap.md — Fase 5
- Atajos i3: atajos-teclado.html