From 004d55943496c3a32085aaed4662ec348cd35a6f Mon Sep 17 00:00:00 2001
From: BarnacleBoy <barnacleboy.jezzahehn@agentmail.to>
Date: Mon, 1 Jun 2026 00:06:56 +0000
Subject: [PATCH] add initial-bringup doc, link in README, save Armbian URL

---
 README.md               |  1 +
 docs/initial-bringup.md | 87 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 docs/initial-bringup.md

diff --git a/README.md b/README.md
index 73b7fdd..68289ce 100644
--- a/README.md
+++ b/README.md
@@ -65,6 +65,7 @@ A cyberdeck built from salvaged ASUS K501U laptop components and Orange Pi 3B SB
 - [Design Decisions](docs/design-decisions.md) - Build approach, nomenclature, layout
 - [Power System](docs/power-system.md) - IP5389 battery management decision
 - [Port Layout](docs/port-layout.md) - External port placement and allocation
+- [Initial Bring-up](docs/initial-bringup.md) - First boot and hardware validation
 
 ## Quick Reference
 
diff --git a/docs/initial-bringup.md b/docs/initial-bringup.md
new file mode 100644
index 0000000..4de813a
--- /dev/null
+++ b/docs/initial-bringup.md
@@ -0,0 +1,87 @@
+# Initial Bring-up: Orange Pi 3B
+
+Get the board running on Armbian for hardware validation.
+
+## What You Need
+
+| Item | Notes |
+|------|-------|
+| microSD card | 8-32GB Class 10 (SanDisk recommended) |
+| HDMI cable + monitor | 1920×1080 or whatever you have |
+| USB keyboard + mouse | Standard USB-A peripherals |
+| USB-C power supply | 5V/3A — any phone charger you already have works |
+
+## Step 1: Download Armbian
+
+Grab an image from the [Orange Pi 3B page on Armbian](https://armbian.com/boards/orangepi3b).
+
+**Which image?** For initial testing, grab a desktop image (Resolute or Trixie). That way you get HDMI output, a GUI, and network manager for WiFi setup immediately. Minimal/server images are fine if you prefer CLI — but desktop saves fiddling on first boot.
+
+Images are built as recently as May 2026 — freshness is good.
+
+## Step 2: Flash to microSD
+
+**On Linux (Rowan/Lucy):**
+```bash
+# Find your SD card device
+lsblk
+# Flash the image (replace /dev/sdX with your card — be careful!)
+xzcat Armbian_*.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
+```
+
+**On Windows/macOS:** Use [Balena Etcher](https://www.balena.io/etcher/) — GUI, hard to mess up.
+
+## Step 3: First Boot
+
+1. Insert microSD into OPi 3B
+2. Connect HDMI, plug in USB keyboard
+3. Connect USB-C power supply
+4. Board powers on automatically (no power button needed on first boot from SD)
+
+**First boot takes longer** — Armbian runs its first-run setup (resize filesystem, generate SSH keys, etc.). Give it 2-3 minutes.
+
+You'll see:
+- U-Boot splash
+- Kernel boot messages scrolling by
+- Armbian first-run wizard (set root password, create user, configure locale)
+
+## Step 4: Hardware Validation
+
+Once booted, run through these:
+
+- [ ] **HDMI output** — Display at correct resolution? No artifacts?
+- [ ] **USB ports** — Both USB 3.0 ports detect peripherals? Both USB 2.0 ports work?
+- [ ] **Ethernet** — Plug in cable, does `ip a` show a link?
+- [ ] **WiFi** — `nmtui` or desktop network manager — scan and connect?
+- [ ] **Bluetooth** — `bluetoothctl` can scan?
+- [ ] **Audio** — 3.5mm jack output?
+- [ ] **eMMC** — `lsblk` should show `/dev/mmcblk1` (the onboard 256GB eMMC)
+- [ ] **RAM** — `free -h` shows ~7.5GB usable (of 8GB)
+- [ ] **Temperature** — `cat /sys/class/thermal/thermal_zone0/temp` — divide by 1000 for °C. Should idle below 50°C without a heatsink for short tests.
+
+## Step 5 (Optional): Install to eMMC
+
+Once you're happy the board works, you can move Armbian to the eMMC and stop using the SD card:
+
+```bash
+sudo armbian-install
+```
+
+Follow the prompts — select eMMC as the target. This copies the system to onboard storage. After it finishes:
+```bash
+sudo poweroff
+```
+Remove the microSD, power back on. Board boots from eMMC automatically.
+
+## Next Steps After Bring-up
+
+- [ ] Test with your salvaged display + controller board (when it arrives)
+- [ ] Test HDMI A/B switch for internal/external display switching
+- [ ] Start case design with real board measurements
+- [ ] Order remaining parts from BOM
+
+## References
+
+- https://armbian.com/boards/orangepi3b — Armbian images
+- https://docs.armbian.com/User-Guide_Getting-Started/ — Official Armbian guide
+- http://www.orangepi.org/orangepiwiki/index.php/Orange_Pi_3B — Official OPi 3B wiki
\ No newline at end of file