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 (what you'll do) · 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:

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