Omar SobhandClaude Opus 4.8
d59bbc0ef3
App Lab's own export/import mechanism is a zip whose top dir is the app name. package-onboard-app.sh now emits dist/apess-onboard.zip alongside the bundle — verified to round-trip through `arduino-app-cli app import` (a mac-built zip imports cleanly; no board needed to package). Distribution is now: build → host the zip on apess.redclaw.dev/download → student downloads → App Lab "Import an app" → Run. Replaces the unverified QR path. ONBOARDING updated with the download/import steps + first-Run auto-install note. Co-Authored-By: Claude Opus 4.8 <[email protected]>
79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
# APESS onboarding — fully containerized
|
|
|
|
A team needs two things running: the **APESS stack on their laptop** and the
|
|
**ZeroClaw node on their Uno Q**. Both are containers. Nothing installs to a host.
|
|
|
|
```
|
|
LAPTOP: docker compose up → apess-api + apess-web (deploy/lan)
|
|
BOARD : App Lab → Run → ONE container = daemon + relay + responder
|
|
```
|
|
|
|
Everything a team does — say-hi, the module chat, Refine, Telegram, the LED
|
|
matrix, the I2C scan — runs through this. The board never needs the Zephyr flash
|
|
toolchain or Linux `/dev/i2c`: the matrix is driven by a resident responder and
|
|
I2C is scanned on the MCU (Wire), both over the RouterBridge relay.
|
|
|
|
## 1. Instructor — build + host the app (once)
|
|
|
|
Bake the cloud token + all assets into an App Lab **import archive** (a zip):
|
|
|
|
```sh
|
|
export ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-… # baked into the bundle
|
|
./deploy/uno-q/package-onboard-app.sh # → dist/apess-onboard/ + dist/apess-onboard.zip
|
|
```
|
|
|
|
The bundle contains: the ZeroClaw binary (matrix_text + i2c_scan), the
|
|
single-`default`-agent config (matrix + i2c_scan allowlisted, Telegram-ready),
|
|
the skills, the responder sketch, and the baked token. It ships **without** a
|
|
`.secret_key` (each board mints its own on first Run) and **without** any team's
|
|
Telegram token. The `dist/` output is gitignored (it holds the token).
|
|
|
|
The zip is a standard App Lab export archive (top dir = app name) — verified to
|
|
round-trip through `arduino-app-cli app import`. **Host it for download:**
|
|
|
|
```sh
|
|
# copy dist/apess-onboard.zip to the production static path, e.g.
|
|
# apess.redclaw.dev/download/apess-onboard.zip
|
|
```
|
|
|
|
## 2. Student — bring up their board (fresh OR pre-existing)
|
|
|
|
1. Open **App Lab** on the Uno Q (it ships with the board).
|
|
2. Download the app zip from `apess.redclaw.dev/download/apess-onboard.zip`.
|
|
3. In App Lab → **Import an app** → pick the zip. It's added to your workspace
|
|
with its files, bricks, and libraries.
|
|
4. Click **Run**. The node comes up in one container: on first Run it
|
|
auto-installs the sketch's core + libraries (RouterBridge, ArduinoGraphics),
|
|
flashes the resident responder, launches the cloud agent, mints its
|
|
`.secret_key`, self-registers to the team's APESS laptop, and scrolls a
|
|
**claim code** on the LED matrix.
|
|
|
|
Fresh or pre-existing board is identical — Run is idempotent; it just (re)starts
|
|
the node. (First Run also pulls the ~839 MB `python-apps-base` image — pre-seed
|
|
that on the room's network if 15 teams start at once.)
|
|
|
|
## 3. Student — the wizard (laptop)
|
|
|
|
- Open `http://<laptop>/` → **Start the workshop**.
|
|
- **Phase 1:** team name + members → type the **claim code** the matrix is
|
|
scrolling → board bound (state persists in `localStorage`; a Disconnect button
|
|
is the only thing that drops it).
|
|
- Say hi to the agent, optionally set up **Telegram** (writes the token to the
|
|
node and reloads it), toggle **Voice**.
|
|
- **Phase 2:** open the node, name the domain. Then the modules.
|
|
|
|
## `APESS_URL` — how the board finds the laptop
|
|
|
|
The board self-registers to `APESS_URL` (default `http://apess-api.local:3000`).
|
|
Options, easiest first:
|
|
- **mDNS:** have the `deploy/lan` box advertise `apess-api.local` (zero-config
|
|
for students).
|
|
- **Per-team:** set `APESS_URL` in the app's `.zeroclaw/apess-node.env`, or pass
|
|
`APESS_URL=http://<laptop-ip>:3000` when packaging.
|
|
|
|
## Reachability
|
|
|
|
The laptop's API must reach the board over the workshop WiFi. Verify the AP
|
|
allows **client-to-client** traffic (many guest networks isolate clients). See
|
|
`deploy/lan/README.md`.
|