IoT_Master

Phase 1 — Hardware runbook

Step-by-step setup for the core device. Follow this in order. Tick each checkpoint before moving on.

1. Bill of materials

Item	Notes
Raspberry Pi 4B, 8GB RAM	The only supported SBC for v1.
Official Raspberry Pi 5” DSI touchscreen	Connects via DSI ribbon + 4 jumper wires for power.
MicroSD card, 32GB minimum, A1/A2 rated	A2 preferred for random IO. SanDisk Extreme or Samsung Pro Endurance recommended.
Official Raspberry Pi 27W USB-C PSU	For bench setup.
USB-C power bank, ≥10,000 mAh, ≥3 A output	For portable use. See §6 Power.
MicroHDMI → HDMI cable	Backup display during initial setup.
USB keyboard + mouse	First-boot setup. SSH after that.
Ethernet cable	Optional but useful for the very first boot.
Sturdy case with touchscreen mount	A “SmartiPi Touch Pro” or equivalent.

2. Flash Raspberry Pi OS 64-bit

Use Raspberry Pi Imager (latest, on a separate machine).

Choose device: Raspberry Pi 4.
Choose OS: Raspberry Pi OS (64-bit) — Bookworm, with desktop. Not Lite, because the touchscreen needs the desktop session for v1.
Choose storage: the microSD card.
Click the gear / settings icon and pre-configure:
- Hostname: pi-iot-01 (or your chosen scheme).
- Username: e.g. coderra. Set a strong password.
- Wireless LAN: SSID, passphrase, country = GB (or JE if available; GB works fine for the Channel Islands).
- Locale: timezone Europe/Jersey, keyboard gb.
- Enable SSH with password authentication for first boot. We’ll swap to keys in §5.
Write image and verify.

✅ Checkpoint: card writes successfully; Imager confirms verification passed.

3. First boot (headless or HDMI)

Option A — HDMI keyboard + mouse: Plug in microHDMI, USB peripherals, power. Boot to desktop, complete any first-run wizard if it appears.

Option B — headless via Ethernet:

Insert SD card, plug Ethernet, power on.
From a laptop on the same LAN:
```
ssh coderra@pi-iot-01.local
```
If .local resolution fails, find the IP from your router and use that.

Run:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

✅ Checkpoint: SSH reaches the Pi; uname -m reports aarch64; apt is clean.

4. Install and configure the official 5” touchscreen

The official 5” DSI touchscreen needs the DSI ribbon connected to the Pi’s DSI1 connector and four jumper wires for 5V/GND/SDA/SCL (per the screen’s included guide). With Bookworm, it is detected automatically — no manual overlay edits are required for the standard touchscreen.

Power off, connect the screen, power on.
Confirm desktop renders on the 5” panel.
Calibrate touch (settings shortcut on the desktop, or ~/.config/lxsession/... if needed).
Test orientation. If the panel is mounted upside down, in /boot/firmware/config.txt add (under [all]):
```
display_lcd_rotate=2
```
Reboot.

✅ Checkpoint: desktop renders on the 5” panel; touch is responsive; tap accuracy is acceptable.

5. Lock down SSH (key-only)

From your laptop:

ssh-keygen -t ed25519 -C "pi-iot-01" -f ~/.ssh/pi_iot_01
ssh-copy-id -i ~/.ssh/pi_iot_01.pub coderra@pi-iot-01.local

On the Pi, edit /etc/ssh/sshd_config.d/99-iot.conf:

PasswordAuthentication no
PermitRootLogin no

Then:

sudo systemctl restart ssh

Verify you can still log in with the key, and that password login is refused.

✅ Checkpoint: key login works; password login refused.

6. Power bank selection

The Pi 4B can draw up to ~15W under load with a touchscreen attached.

Minimum acceptable power bank:

USB-C output, 5V/3A sustained (≥15W).
Pass-through charging is ideal — lets the Pi keep running while the bank charges from a wall PSU.
Capacity ≥10,000 mAh for ~2–3 hours of classroom use; 20,000 mAh for a full lesson day with margin.
Avoid power banks that auto-shutdown on low draw (some “smart” banks turn off if current dips below ~100 mA).

Test:

Charge bank fully.
Boot the Pi from the bank with the touchscreen on.
Run vcgencmd get_throttled after 5 minutes of normal use.
- 0x0 = healthy.
- Any non-zero value with the under-voltage bit set (0x50000 etc.) means the bank or cable is inadequate.

✅ Checkpoint: Pi boots from the bank, touchscreen runs, no under-voltage flags after 10 minutes of light use.

7. Networking and remote access

Wi-Fi

Already configured by Imager. Verify:

nmcli device status
nmcli -t -f active,ssid dev wifi | grep '^yes'

Bluetooth

bluetoothctl show

Should report Powered: yes.

VNC (optional, for remote desktop)

sudo apt install -y realvnc-vnc-server
sudo raspi-config nonint do_vnc 0

Connect from a laptop with RealVNC Viewer to pi-iot-01.local:5900.

✅ Checkpoint: Wi-Fi connected; Bluetooth powered; VNC reachable from LAN.

8. Folder layout on the device

Create the working tree once:

sudo mkdir -p /opt/iot-platform
sudo chown $USER:$USER /opt/iot-platform
cd /opt/iot-platform
git init

The repository structure planned for this directory is documented in folder-layout.md. Don’t pre-create directories yet — they appear when Phase 2 begins.

✅ Checkpoint: /opt/iot-platform exists, owned by your user, initialised as a git repo.

9. Auto-start strategy (deferred)

Auto-launching the Vue dashboard in kiosk mode on boot is a Phase 5 concern. For Phase 1 we only need the desktop to come up reliably. The current plan (documented here so it is not forgotten) is:

A wayfire/labwc autostart entry that launches Chromium in kiosk mode pointing at http://localhost:8080.
Or a systemd user service with the same effect.

Do not configure auto-start until Phase 5.

10. Phase 1 verification checklist

OS: 64-bit Raspberry Pi OS Bookworm, fully updated.
Hostname set; user account created.
SSH: key-only, password auth disabled.
Wi-Fi: connected and persistent across reboots.
Bluetooth: powered.
Touchscreen: renders and responds to touch.
Power bank: boots and runs without under-voltage warnings for ≥10 min.
/opt/iot-platform exists and is git-initialised.
No additional services installed yet — clean slate for Phase 2.

Once every box is ticked, proceed to implementation-plan.md §Phase 2.