docs: Armbian install reference — boot issue, extract approach, xfce/startx config

README.md

@@ -57,6 +57,7 @@ A cyberdeck built from salvaged ASUS K501U laptop components and Orange Pi 3B SB
 - [Port Layout](docs/port-layout.md) - External port placement and allocation
 - [Case Design](docs/case-design.md) - Dimensional constraints, component footprint, floorplan
 - [Initial Bring-up](docs/initial-bringup.md) - First boot and hardware validation
+- [Armbian Install](docs/armbian-install.md) - Armbian on p3 with shared /boot, XFCE via startx
 
 ## Quick Reference
 

docs/armbian-install.md

@@ -0,0 +1,175 @@
+# Armbian Install — Orange Pi 3B (Cyberdeck Multi-Boot)
+
+**Goal:** Armbian (Debian 13 Trixie) on eMMC partition p3 (root_armbian), booting via shared extlinux.conf. Headless default, with XFCE available via `startx` (or `startxfce4`).
+
+## Context
+
+The cyberdeck's eMMC has a four-partition layout with a shared /boot on p1:
+
+```
+mmcblk0 (233GB eMMC user data area)
+├── mmcblk0p1  FAT32  1GB    /boot        (starts at sector 32768)
+├── mmcblk0p2  ext4   85GB   root_opios   (Orange Pi OS Arch — live)
+├── mmcblk0p3  ext4   85GB   root_armbian (Armbian — target)
+└── mmcblk0p4  ext4   ~84GB  root_nixos   (NixOS — future)
+```
+
+Boot is Rockchip-standard user-data-area: PARTITION_CONFIG=0x78, idbloader at sector 64, u-boot.itb at sector 16384, SPI flash erased. u-boot reads extlinux.conf from p1 for the boot menu.
+
+Full walkthrough of the boot architecture and partition setup: `docs/emmc-multiboot.md`.
+
+## Current SD Card Boot Issue
+
+**Symptom:** Armbian 26.2.0 minimal (Debian Trixie, kernel 6.18.30) flashed to SD card — black screen with single underscore cursor, no keyboard response.
+
+**Likely causes (investigation in progress):**
+
+1. **Kernel/framebuffer init failure on the current kernel edge** — Kernel 6.18 is very fresh (Rockchip-current was bumped from 6.12 to 6.18 recently). The framebuffer console initializes (underscore cursor visible) but the display pipeline or USB host may not complete initialization, leaving a dead console.
+
+2. **No serial console to see boot messages** — The underscore cursor tells us the kernel's fbcon is alive, but we can't see *where* it failed. A UART adapter (TTL-to-USB at 1.5M baud on the OPi3B's debug UART pins) would show the actual boot log.
+
+3. **HDMI EDID handshake failure** — Known issue on this board (documented in the bring-up reference). If the kernel's DRM/KMS driver can't negotiate EDID, it may still fail to the fbcon cursor state instead of blanking.
+
+**Alternative approaches being considered:**
+
+1. Skip the SD boot entirely — extract Armbian rootfs and kernel from the downloaded image and install them directly to p3/p1 from within the running Orange Pi OS.
+2. Try the vendor-kernel variant (kernel 6.1.115) which is more stable on RK3566.
+3. Try a desktop image (Ubuntu Resolute Gnome/KDE) instead of minimal — different kernel config, may handle display differently.
+
+## Approach 1: Install Without Boot (From Running OS)
+
+This approach doesn't require the SD card to boot. You extract Armbian's rootfs and kernel from the downloaded image while running Orange Pi OS, then add an extlinux.conf entry.
+
+### 1. Mount the target partitions
+
+```bash
+# Mount the shared /boot (p1) and root_armbian (p3)
+sudo mkdir -p /mnt/armbian_root
+sudo mount /dev/mmcblk0p3 /mnt/armbian_root
+sudo mkdir -p /mnt/armbian_root/boot
+sudo mount /dev/mmcblk0p1 /mnt/armbian_root/boot
+```
+
+### 2. Extract rootfs from the Armbian image
+
+```bash
+# Find the SD card image
+ls -la ~/Downloads/Armbian_*.img*
+
+# Mount the SD image (loopback) to expose its partitions
+sudo kpartx -av ~/Downloads/Armbian_orangepi3b_trixie_current_6.18.30_minimal.img
+# This creates /dev/mapper/loopXp1 (/boot) and /dev/mapper/loopXp2 (rootfs)
+
+# Mount the rootfs partition from the image
+sudo mkdir -p /mnt/armbian_img
+sudo mount /dev/mapper/loopXp2 /mnt/armbian_img
+```
+
+### 3. Rsync rootfs to p3
+
+```bash
+sudo rsync -aHAWX --info=progress2 /mnt/armbian_img/ /mnt/armbian_root/
+```
+
+### 4. Copy kernel, DTB, initrd to shared /boot
+
+```bash
+# Mount the SD image's /boot partition too
+sudo mkdir -p /mnt/armbian_img_boot
+sudo mount /dev/mapper/loopXp1 /mnt/armbian_img_boot
+
+# Copy kernel files
+sudo cp -v /mnt/armbian_img_boot/vmlinuz-* /mnt/armbian_root/boot/
+sudo cp -v /mnt/armbian_img_boot/initrd.img-* /mnt/armbian_root/boot/
+sudo cp -rv /mnt/armbian_img_boot/dtb*/ /mnt/armbian_root/boot/
+```
+
+### 5. Update fstab
+
+Get UUIDs and set up the Armbian root:
+
+```bash
+sudo blkid /dev/mmcblk0p1 /dev/mmcblk0p3
+```
+
+Edit `/mnt/armbian_root/etc/fstab`:
+
+```
+UUID=<boot-UUID>  /boot  vfat  defaults,noatime  0  2
+UUID=<root_armbian-UUID> /     ext4  defaults,noatime  0  1
+```
+
+### 6. Add extlinux.conf entry
+
+Edit `/mnt/armbian_root/boot/extlinux/extlinux.conf` (or create the shared one if it's not auto-generated from Orange Pi OS's):
+
+Add a LABEL block:
+
+```
+LABEL Armbian
+    LINUX /vmlinuz-6.18.30-current-rockchip
+    INITRD /initrd.img-6.18.30-current-rockchip
+    FDT /dtb/rockchip/rk3566-orangepi-3b.dtb
+    APPEND root=UUID=<root_armbian-UUID> ro console=tty1 console=ttyS2,1500000n8 video=HDMI-A-1:1920x1080@60e
+```
+
+The `video=HDMI-A-1:1920x1080@60e` forces the mode even if EDID is missing — needed for the OPi3B HDMI issue.
+
+### 7. Clean up and test
+
+```bash
+sudo umount /mnt/armbian_img /mnt/armbian_img_boot /mnt/armbian_root/boot /mnt/armbian_root
+sudo kpartx -d ~/Downloads/Armbian_orangepi3b_trixie_current_6.18.30_minimal.img
+sudo sync
+```
+
+Reboot. Pick "Armbian" from the u-boot menu.
+
+## Approach 2: Boot Armbian SD Card (Alternative Images)
+
+If you want to get the SD card booting instead:
+
+- **Try the vendor kernel image:** The rolling-release page offers a Debian Trixie Minimal with kernel `6.1.115` (vendor). This is the older, more tested Rockchip BSP kernel — likely more stable.
+- **Try a desktop image:** The Ubuntu Resolute Gnome/KDE images use a different kernel config and might initialize the HDMI display path differently.
+- **Use UART:** The OPi3B has debug UART pins (accessible via UART-to-USB adapter at 1,500,000 baud). This shows the actual boot log — u-boot output, kernel messages, and the panic/hang point — which makes debugging instant instead of guessing from a blank screen.
+
+## Post-Install: XFCE via startx
+
+Once Armbian is booting from eMMC:
+
+### Install XFCE (no display manager)
+
+```bash
+sudo apt update
+sudo apt install xfce4 xfce4-terminal xinit
+```
+
+No display manager (lightdm/gdm/sddm) — the goal is headless boot with XFCE available on demand.
+
+### Configure startx
+
+```bash
+# Create .xinitrc to launch XFCE
+echo "exec startxfce4" > ~/.xinitrc
+```
+
+Then `startx` launches the desktop.
+
+For the rootless-first Armbian setup (default user created on first boot), `~/.xinitrc` goes in the user's home directory. No sudo needed.
+
+## Verification Checklist
+
+- [ ] Armbian boots from u-boot menu
+- [ ] Network works (ethernet or WiFi)
+- [ ] SSH access (check `ip a` for IP, `systemctl status ssh`)
+- [ ] `startx` launches XFCE from the terminal
+- [ ] Keyboard/mouse work in XFCE
+- [ ] eMMC partitions accessible (no stray SD card mounts)
+
+## References
+
+- Armbian OPi3B page: <https://www.armbian.com/boards/orangepi3b>
+- eMMC multi-boot setup: `docs/emmc-multiboot.md`
+- Initial bring-up: `docs/initial-bringup.md`
+- Storage architecture: `docs/storage-architecture.md`
+- OPi 3B bring-up reference: `references/orangepi-3b-bringup.md` (in cyberdeck skill)