# 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)

---

## Session Log — 2026-06-07 Boot Recovery

### Background
Orange Pi OS Arch was booting from eMMC (3-OS multi-boot layout, PARTITION_CONFIG=0x78). An Armbian 26.2.0 minimal (Debian Trixie, kernel 6.18.30) SD card was inserted to test booting. The Armbian image produced a black screen with underscore cursor on HDMI and hung. Upon removing the SD card, the eMMC no longer booted — same black screen / cursor symptom.

### What Happened
The Armbian SD card's u-boot wrote bootloader data to two places:
1. **SPI NOR flash** — overwrote the previously-erased SPI chip, changing the boot priority back to SPI-first
2. **eMMC bootloader sectors** (0-32767) — overwrote the existing idbloader at sector 64 and u-boot.itb at sector 16384 with Armbian's versions

### Recovery Attempts

| Step | Result |
|------|--------|
| SPI erase via maskrom (`rkdeveloptool ef`) | Success (resolved by switching to a better USB-A-to-A cable) |
| eMMC bootloader rewrite — wrote Orange Pi OS's `idbloader.img` to sector 64 and `u-boot.itb` to sector 16384 from within SD-booted OPi OS | RKNS magic verified at sector 64 |
| PARTITION_CONFIG check | **0x78** — verified with `mmc extcsd read` via `mmc-utils` installed on OPi OS Arch. The register was not changed. |
| Full boot cycle (no SD) | Still hangs: black screen + underscore cursor |

### Diagnostic Signals
- **Green LED:** flashes a quick heartbeat pattern before the hang — the kernel starts booting (extlinux.conf is found, the kernel loads and begins executing) but doesn't complete init
- The underscore cursor is the kernel's framebuffer console — it initialized fbcon but never reached userspace

### Still Pending (next session)
1. **Check extlinux.conf on eMMC p1** — mount `/dev/mmcblk0p1` from the SD-booted system and verify the `LINUX`, `INITRD`, `FDT` paths exist and `root=PARTUUID=` matches p2's PARTUUID
2. **Check rootfs health on p2** — mount `/dev/mmcblk0p2` and verify filesystem integrity (look for corruption from all the power cycles / failed boots)
3. **Check kernel + initrd file existence on p1** — the files that extlinux.conf references might have been deleted or corrupted during the Armbian u-boot write
4. **Try a kernel panic capture** — add `panic=10` to the APPEND line in extlinux.conf to see if the kernel panics on a missing rootfs before the display driver initializes