apress/deploy/uno-q/REQUIREMENTS.md

# APESS 2026 Workshop — Laptop Prerequisites

**"Design the Agent Your Building Deserves" · 27 July · a 5-hour build session.**
Do these **before you arrive** so we spend the session building, not installing.

> Companion docs: [`WORKSHOP-FLOW.md`](./WORKSHOP-FLOW.md) (what you'll do) ·
> [`ONBOARDING.md`](./ONBOARDING.md) (how the board comes up).

---

## How it runs (so the prerequisites make sense)
Each team runs the **whole platform on its own laptop** — a small Docker stack (web + API) that
comes up with **one command**. Your **Arduino Uno Q** plugs into that same laptop over **USB**.
Everything on your **laptop** is **localhost**: the browser, the API, and the board all talk on your
machine. Once the stack is up and the board is plugged in, it **auto-connects to your team — no
codes, no accounts.** The one thing that leaves the box: the **board** reaches its **AI cloud brain
over the venue WiFi** — but *we* pre-join each board to that network before you get it, so there's
nothing for you to set up.

> **Most teams are on Windows 11** (a few Macs). Both work the same way; the only difference is the
> command you run to attach the board — see the Windows / macOS notes below.

So each team needs **one "board laptop"** with a few things pre-installed. Extra teammates just
need a browser pointed at that laptop.

---

## TL;DR
- **Board laptop:** install **Docker**, **adb**, and **git**; pull the workshop bundle ahead of time.
- **Everyone else:** a modern browser is enough.
- **No accounts, no API keys** — the AI cloud access is baked into the board app.

---

## What the workshop provides (do NOT install)
- **Arduino Uno Q (4 GB)** board + **USB-C cable** — one per team.
- **ADXL355 accelerometer(s)** + wiring — the FabLab kit.
- **Cloud AI access** — baked into the board app. **No Anthropic/Claude account needed.**
- **Boards pre-joined to the venue WiFi** — the board uses it only to reach the AI cloud; you don't
  configure any network.
- The **web app** itself (you run it locally from the bundle below).

---

## The team "board laptop" — pre-install these (large downloads, do them at home)
1. **Docker** — Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux).
   Verify: `docker run hello-world` succeeds.
2. **adb** (Android platform-tools) — the USB bridge to the board.
   Verify: `adb version` prints a version. (macOS: `brew install android-platform-tools`.)
3. **git** — to fetch the workshop bundle. Verify: `git --version`.
4. **~10 GB free disk** — Docker images (web + API) + the board's App Lab base image (~0.9 GB).
5. **The workshop bundle, pre-fetched** so you're not downloading on the WiFi at 14:00:
   ```sh
   git clone <workshop-repo-url>        # [instructor: final repo/bundle URL]
   cd <repo>/deploy/lan
   docker compose up -d --build         # pre-build the images once, at home
   docker compose down                  # then stop until the day
   ```
   (Also pre-pull the App Lab base image on the board — it's fetched on first Run.)

### On Windows 11 (most teams)
- **Docker Desktop** with the **WSL2 backend** (enable it in the installer). `docker run hello-world`.
- **adb** — download **Android SDK platform-tools for Windows**, unzip it, and add the folder to your
  **PATH** (so `adb version` works in a new terminal). *Run adb on Windows itself — not inside WSL.*
- **Git for Windows** — gives you `git` + `curl` (used by the stack).
- **Uno Q USB driver** — plug the board in; Windows usually installs a driver automatically. It's
  working when **`adb devices`** lists the board as `device` (see the check below). If it shows
  nothing or `unauthorized`, reinstall the driver / re-plug and accept any prompt on the board.
- To attach the board you'll run **`connect-board.bat`** (double-click) or **`connect-board.ps1`** —
  both live in `deploy\lan\`.

### On macOS (a few teams)
- Docker Desktop, `brew install android-platform-tools` (adb), `git`. Attach with
  `./deploy/lan/connect-board.sh`.

### First check: does adb see your board?
The #1 thing to get right up front. Plug the Uno Q in over USB and run:
```
adb devices
```
You want a line ending in **`device`**, e.g. `65301572   device`. If it's empty, `offline`, or
`unauthorized`: re-plug, try a different USB port/cable, and on Windows reinstall the USB driver.
**Get this working before the day** — everything else assumes adb sees the board.

## Everyone else on the team
- A **current browser** (Chrome/Edge recommended; Firefox works). That's it — you'll open the board
  laptop's local URL.

---

## What you'll do on the day (no accounts, no claim codes)
1. **Bring the stack up:** `cd deploy/lan && docker compose up -d` → open **`http://localhost:8090/`**.
2. **Get the board app:** in Team Registration, click **Download the board app** (served by your own
   stack), then on the Uno Q: **App Lab → Import an app → pick the zip → Run.** `[instructor: confirm the App Lab access flow for the room]`
3. **Attach the board:** plug the Uno Q into the board laptop over USB, then:
   - **Windows:** double-click **`deploy\lan\connect-board.bat`** (or run `.\connect-board.ps1 -Watch`
     to keep it auto-attaching on re-plug).
   - **macOS:** run **`./deploy/lan/connect-board.sh`** (or `--watch`).
4. **It just connects:** type your team name and the board **auto-binds to your team** — no code.
   Unplug/replug is handled automatically; a **Disconnect / Reconnect** control is there if you need it.
5. **Build:** walk Modules 1–3, submit your Agent Design Document.

---

## Pre-flight self-check (before you travel)
- [ ] **(Board laptop)** `docker run hello-world` works.
- [ ] **(Board laptop)** `adb version` and `git --version` work.
- [ ] **(Board laptop)** Ran `docker compose up -d --build` once (images built) and opened `localhost:8090`.
- [ ] Laptop charged + charger packed (5-hour session).
- [ ] A current browser.

---

## No accounts to create
- ❌ No Anthropic / Claude account or API key — the cloud key is baked into the board app.
- ❌ No claim codes — in this local USB setup the board auto-connects.
- ✅ Everything is localhost; nothing depends on the room WiFi.

---

## Notes for the curious (why these specific tools)
- **Docker** runs the web + API stack in one command, identically on every laptop.
- **adb** carries the board over USB; the API (in a container) reaches it via `host.docker.internal`.
- The web runs on **`:8090`** (not `:8080`) because `:8080` is the board's own port, forwarded over adb.

---

## Instructor checklist (finalize before publishing to students)
- [ ] **The workshop bundle URL** (git repo or a downloadable archive) students clone/pull.
- [ ] **Pre-built image distribution** — consider publishing `apess-web`/`apess-api` to a registry (or a
      USB `docker load` bundle) so teams `docker compose up` without a source build on the day.
- [ ] **Exact Arduino App Lab access** on the Uno Q for the room (and whether it needs any login).
- [ ] **Pre-seed** the ~0.9 GB App Lab base image locally so 9 teams don't each pull it live.
- [ ] Decide whether `connect-board.sh --watch` runs via a small launchd/systemd unit (hands-free re-plug).