From ce5df15f72506b8a3c3a7e94af78d91705ef13f2 Mon Sep 17 00:00:00 2001 From: Michael B Reiser Date: Tue, 27 Oct 2026 09:43:12 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs(rig):=20SETUP.md=20=E2=80=94=20arena-s?= =?UTF-8?q?ide=20setup=20notes=20+=20pointer=20to=20rig-nodes=20SETUP.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Machine setup (install recipe, host table, per-host quirks) now lives in rig-nodes, where every rig PC installs from; this page keeps only what exists because of the arena application (Studio ↔ gateway, Web Serial, course repo, the branch-test recipe). Co-Authored-By: Claude Fable 5.1 --- rig/README.md | 2 ++ rig/SETUP.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 rig/SETUP.md diff --git a/rig/README.md b/rig/README.md index 42909b42..1e7f813f 100644 --- a/rig/README.md +++ b/rig/README.md @@ -1,5 +1,7 @@ # ROS 2 bridge proof of concept (LAB-303) +> **Setting up a machine?** Install recipe, host table and per-machine quirks: [`reiserlab/rig-nodes` → `SETUP.md`](https://github.com/reiserlab/rig-nodes/blob/main/SETUP.md). What this workspace adds on top (Studio ↔ gateway, Web Serial, course repo): [`SETUP.md`](SETUP.md) here. + A bounded spike, not a product: can the web runner's bridge be a ROS 2 node graph while the **unmodified Arena Studio** keeps connecting to `ws://localhost:8765`, the **run log stays the same file every reader already accepts**, and the devices (FicTrac, Kinefly, BIAS) sit behind diff --git a/rig/SETUP.md b/rig/SETUP.md new file mode 100644 index 00000000..ee01dc75 --- /dev/null +++ b/rig/SETUP.md @@ -0,0 +1,48 @@ +# Setting up this rig workspace (arena side) + +Machine setup, the install recipe, the host table and every per-machine quirk live in +**[`reiserlab/rig-nodes` → `SETUP.md`](https://github.com/reiserlab/rig-nodes/blob/main/SETUP.md)**: +rig PCs install the shared package set with or without the web tools, so that is where an +install problem is recorded and looked up. Update your machine's row there after every install +or QC pass. This page holds only what exists because of the arena application. + +## What this workspace adds on top of the package set + +- `cd rig && pixi install --locked` installs the package set pinned in `rig/pixi.toml` + (environments: `default` String topics, `typed` adds `rig_interfaces`, `viz` adds Foxglove, + `dev` swaps the pins for a sibling `../../rig-nodes` checkout). Run every `pixi run …` from + `rig/`, not the repository root: the root has its own `pixi.toml` for the web tools and + `pixi run` there provisions that workspace instead. +- `pixi run rig` is the one command a rig PC runs (router + FicTrac adapter + the Studio + gateway; `--bias`, `--scanimage`, `--kinefly`, `--foxglove` add nodes; `--sim` and the + `*-sim` flags add simulators). The gateway serves `ws://localhost:8765`, which is what the + Studio connects to. Bridge 3.4 (`pixi run bridge` at the repository root) is the legacy path + for course rigs and must be stopped first; both want 8765. +- Harness: `pixi run test` (and `pixi run -e typed test`) runs the whole graph with simulators + and the Studio emulator; it is also the cross-repository smoke for the installed package set. + +## The Studio and the gateway + +- **Production Studio** is `https://reiserlab.github.io/webDisplayTools/arena_studio.html`; it + connects to `ws://localhost:8765` from the Run view (bridge Connect) or the Console. Hard-refresh + after a release and check the footer version. Never open `/next/` on a rig PC mid-experiment. +- **A branch test without Pages:** `python3 -m http.server 8080` from the repository root, then + `http://localhost:8080/arena_studio.html?mode=run`. Without an arena controller the Studio + connects and shows FicTrac frames but applies nothing; `rig/tests/studio_emulator.py` speaks + the Studio's exact conversation (hello, config, log_control, epochs, log_export) and is the + no-browser check. +- **Web Serial** needs Chrome or Edge and a user click on the port picker; everything else + (bridge connect, metadata, Run) is scriptable. On Windows the G6 controller enumerates as + "USB Serial" (`COMn`). +- **Course repo:** run logs commit to the configured course repository only when a token is + stored (⚙ Settings → GitHub); without one, `pixi run export` asks the running gateway for the + run's log. Token types: `docs/development/data-repo-token-runbook.md`. +- **Protocols and patterns** for a rig live in the course repo under `protocols//` + with colocated `*_patterns/`; the Studio's session rig must match the arena the SD card's + patterns were made for (a 4×10 firmware build rejects every 2×10 pattern). + +## Records + +Dated results from past sessions on each machine (kept as records; the living summary is the +rig-nodes host table): `windows-results-ww18-2026-10-15.md`, `scanimage-day-2026-10-16.md`, +`SCANIMAGE-DAY.md`, `WINDOWS-TEST.md`, and the okey-cokey PC notes that land with PR #269. From 02ede33b5d73d6f5cec890d3b99b19d241b9ecf3 Mon Sep 17 00:00:00 2001 From: Michael B Reiser Date: Tue, 27 Oct 2026 15:16:52 -0400 Subject: [PATCH 2/2] rig/SETUP.md: dev environment uses git source deps; telemetry-ring note from the ww18 QC Co-Authored-By: Claude Fable 5.1 --- rig/SETUP.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/rig/SETUP.md b/rig/SETUP.md index ee01dc75..cdf4f2a9 100644 --- a/rig/SETUP.md +++ b/rig/SETUP.md @@ -10,7 +10,7 @@ or QC pass. This page holds only what exists because of the arena application. - `cd rig && pixi install --locked` installs the package set pinned in `rig/pixi.toml` (environments: `default` String topics, `typed` adds `rig_interfaces`, `viz` adds Foxglove, - `dev` swaps the pins for a sibling `../../rig-nodes` checkout). Run every `pixi run …` from + `dev` swaps the pins for git source dependencies on rig-nodes `main`, so no sibling checkout is needed). Run every `pixi run …` from `rig/`, not the repository root: the root has its own `pixi.toml` for the web tools and `pixi run` there provisions that workspace instead. - `pixi run rig` is the one command a rig PC runs (router + FicTrac adapter + the Studio @@ -31,6 +31,11 @@ or QC pass. This page holds only what exists because of the arena application. connects and shows FicTrac frames but applies nothing; `rig/tests/studio_emulator.py` speaks the Studio's exact conversation (hello, config, log_control, epochs, log_export) and is the no-browser check. +- **Controller telemetry is a per-browser setting.** With Debug ▾ → Telemetry ring off, + `run_metadata.telemetry` is `"off"`, no `cc`/`cf`/`cs` rows reach the gateway, and + `scripts/runlog-check.py` reports `no stream_schema` / `no trial_quality event`. Turn it on + before a QC run; the first run after enabling it drains the ring's backlog (the check then + counts controller 0x70s from before the run), so judge the second run (ww18, 2026-10-27). - **Web Serial** needs Chrome or Edge and a user click on the port picker; everything else (bridge connect, metadata, Run) is scriptable. On Windows the G6 controller enumerates as "USB Serial" (`COMn`).