diff --git a/README.md b/README.md index 2cedd7c..9a90c09 100644 --- a/README.md +++ b/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 diff --git a/docs/armbian-install.md b/docs/armbian-install.md new file mode 100644 index 0000000..ffce925 --- /dev/null +++ b/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 vfat defaults,noatime 0 2 +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= 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: +- 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) \ No newline at end of file