Skip to content
Open
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -403,6 +403,7 @@ jobs:
# workflow, so it doesn't gate the rest of the pipeline.
docker-build:
name: Docker Build & Test
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
needs: [code-quality, test, rust-tests]
continue-on-error: true
Expand Down Expand Up @@ -523,7 +524,7 @@ jobs:
name: Notify
runs-on: ubuntu-latest
needs: [code-quality, test, rust-tests, ui-tests, performance-test, docker-build, docs]
if: always()
if: always() && github.event_name == 'push' && github.ref == 'refs/heads/main'
permissions:
contents: write # required by softprops/action-gh-release
# GitHub Actions does not allow `secrets.X` directly in step-level `if:`
Expand Down
60 changes: 60 additions & 0 deletions firmware/esp32-csi-node/nodes.example.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# RuView declarative node config — read by `ruview node` (harness/ruview/src/node-config.js).
#
# cp nodes.example.yaml ~/.ruview/nodes.yaml # keep the real one OUT of git
# ruview node plan # validate + show what would happen
# ruview node apply --watch # apply to each board as you plug it in
# ruview node status # read-only health of every node
#
# Supported YAML: block maps/lists, [a, b] lists, quoted or plain scalars and
# comments. Anchors, tags, multi-line strings and unknown keys are rejected.

wifi:
ssid: "MyHome-2G" # 2.4 GHz network
# Path only: ruview never reads it, provision.py does. Inline passwords are refused.
password_file: ~/.ruview/wifi-pass # chmod 600; the password, one line

# OTA key (64 hex chars, chmod 600). Without it, provisioning DISABLES remote
# OTA updates and config_push on the node. Create one with:
# (umask 077; set -C; openssl rand -hex 32 > ~/.ruview-ota-psk)
# ota:
# psk_file: ~/.ruview-ota-psk

aggregator:
ip: auto # auto = this machine's private LAN IPv4
port: 5005

firmware:
source: auto # auto: repo build/ unless sources changed | reuse: build/ as-is | bundle: release dir
variant: s3-8mb # s3-8mb | s3-4mb | c6
# bundle: ~/Downloads/esp32-csi-node-firmware-4mb # source: bundle (needs SHA256SUMS)

steps: [device, driver, flash, wifi, validate] # used by `node apply`

validate:
wait_secs: 60 # max wait for the node's first CSI packet after provisioning
udp_secs: 15 # measurement window
min_pps: 20 # CSI rate floor (firmware README acceptance floor)
# max_loss: 0.4 # optional ceiling on CSI sequence loss (0-1)

# Applied to every node unless the node overrides it.
defaults:
edge_tier: 2 # 0=raw, 1=stats, 2=vitals
# channel: 6
# pres_thresh: 50

# Boards not listed get the next free node_id; the registry
# (~/.ruview/esp32-setup/devices.jsonl) keeps it stable across runs.
# Set false to refuse unlisted boards.
auto_assign: true

# Matched by MAC (`ruview node apply` prints it). tdm_total = nodes with a tdm_slot.
nodes:
- mac: "aa:bb:cc:dd:ee:01"
node_id: 1
zone: living-room
tdm_slot: 0
# - mac: "aa:bb:cc:dd:ee:02"
# node_id: 2
# zone: bedroom
# tdm_slot: 1
# edge_tier: 1
13 changes: 7 additions & 6 deletions harness/ruview/.harness/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
".mcp/servers.json": "fec6075400f8350d8075beac8306690355c4b015425bfd0e5f52966234e9d66f",
"CLAUDE.md": "25f9306b6caae22078cb9375108b6f6bb813d83e617739f6d9372f116b0ede5d",
"LICENSE": "631f94984f626818d42ecf717aa6e8e0afd4f9f355ca706bd2effafbd1416d06",
"README.md": "d761e75678ac48c391b86e9094c207193f01d351235b8c77fc709983e57accd7",
"README.md": "de24e91dc1570896d512cd69da60a3bedca86edb8a8bd5c081881f4533bbe861",
"bin/cli.js": "8ebf6ca4b6d9529a5e338374c19329c1a2fc2f9e52f13b4341928b7168ee461b",
"brain/corpus/core.jsonl": "c0fb7b079ded157059b91601361429944697dae3cc42abc00dfe1a680986b0f4",
"flywheel/evaluations.json": "ac4ff1f897a2444870cd2b8ae8aee8b1578e61467aeca4db57893f41be98a572",
Expand All @@ -32,7 +32,7 @@
"flywheel/genome.json": "75db44a3cab70d9459fc8c07863f640ac1214bfaa243483939e1506d63f51214",
"flywheel/replay.mjs": "0670ca0b03701f4afe0b4bca8a3d58d481676b61a94a5b98c6a425aefb1159ab",
"flywheel/run.mjs": "6d4f97db16900c45367b6538848cbe1915af999e663720dfc51f2bb1698f1cd0",
"package.json": "d6ba81ba3cad035c5ddd17d2d84d1f02a273c6ac588b77c1592497d720803f3c",
"package.json": "96014281a1c3be5c43cb13f0a79bcf2ec425271c37f832ac55e97b2bfb7c104a",
"scripts/sync-skills.mjs": "43715dab61e204dc91bbd61755810e8fdb2f66e2b0c0bd791b4bf48a2e293565",
"scripts/update-manifest.mjs": "8f56764b8f70aed55da0c7e2417ae875b0d58d781d839b6db7f115f08af61e6b",
"scripts/verify-manifest.mjs": "6491a221762efcfeb3e749ecab243b204f17fd5bc871f3d4025597f31b8f0f10",
Expand All @@ -45,16 +45,16 @@
"skills/verify.md": "2d38d240e9810a7827e2ebd3717dc0f85c646cc92e46c3812fe77c5b9eb40b76",
"src/brain.js": "0f16a75aea943acdacc430ff11d5df7ecdec9cca2ab497795ff6f33eaebdfab6",
"src/cli-ui.js": "5ac04c5790f03df708c24a6dd366b51ff33a643691642b689284bcada25c9d9a",
"src/cli.js": "9b604f5c05a9d3338bd56f4386272a2624e7c5ee9676fcbc4bbfff6b86916571",
"src/devices/esp32.js": "21b8c74d9b0a47f52538b5d902faa32ac6f4c58dab94d6612d7fbc89237d8f80",
"src/cli.js": "94fd0631944bec2386bf8f3b2e59abd7058fa4f68bd05943eb2a3cff101dcc74",
"src/devices/esp32.js": "587e875cdaddb7b942c4e2c0521595456894762b842446e553b8c69d2c1ad32f",
"src/devices/esphome.js": "d4429fd09c8d93fdc2e5926305d8193c98e074affc48deabda4b16bb9b620056",
"src/devices/lidar.js": "d9a91e2b6eec21463bbb950fc333e9d0ebd2699a7c533d534323bb4d6a55bd97",
"src/devices/mmwave.js": "2ac0be6c4be3c71d147d4bc57b8fd516d051234a8897295bc9e7f9c36c8ae710",
"src/devices/registry.js": "26725e43adaa908b41462f492c5f6bf63e9193f3ee076e3d64ebaa012b66f6be",
"src/devices/serial-pump.js": "86fd00708c7f74ca004eee1b729821aa10a70bfd394cc556dc0ec4b64b43b149",
"src/doctor.js": "e5feccab91da3fdad16316ed7fd9090218a55b6de48772219ced96a930b87e75",
"src/exec.js": "8889d13b8a8277f322856e743c79ac8f29b707251eaf9757c46d3f745743ae22",
"src/firmware.js": "b0aa0a1e49a75072cb9d0422572152c6552a451e41df264e0489eda22a5d1c62",
"src/firmware.js": "92f95153df552e82a4e101d41c3fbf6405c2f28b6b394c065862572c1fa92b6f",
"src/guardrails.js": "aacc8fa6088f7f1ccea3a0b02171a5c516b95d3416ee3ba87add3879a1d6aaad",
"src/guidance.js": "bd92e27280099246353926390df6913f2577f3811de48e16ac28b59253b55b1f",
"src/hosts/claude-code.js": "2212bc39b49822018800dfe33a471e56bbb4c5233d716bfa7aa4fff77aa23edb",
Expand All @@ -63,6 +63,7 @@
"src/kernel.js": "48dfd218a747dd158f82ae108e7e8ed89a82cd68649214d23266112dc9033f5d",
"src/mcp-http.js": "b72e021ae00d01831ef7184db824f5e85a2b8747e1d8e994b6a1cb1cb4d08945",
"src/mcp-server.js": "5eb8c3431768932c3a85476df032d0608fc7a732ede3d6bdcc8467ca47552666",
"src/node-config.js": "6f53ae40b9ff70a65a350c9379c993cf1227c0998fecc6fa86c3354521f7cab8",
"src/policy.js": "baad5eb8c3eb2e416e0a71b342ad850d7c8413d7d976571ebf596937f69da8e2",
"src/process-runner.js": "49533b038044dfb8bc76ed01c030d06a9856ead0836157fb693e2a7d40f786d6",
"src/redact.js": "ebf1afff46341078706b0401838c53db043603586e280d51ece5cf1feba35189",
Expand All @@ -75,7 +76,7 @@
"src/training.js": "bd8a6c12eba4f9d2f8990fa9692cd04c743ea247f9b13e10f8717ceefcbd09ac",
"src/ui/console-widget.js": "0d2f707d57b5ec54968dee1dc80f31c7db9152dcadfc48700c18379dabb55462"
},
"filesDigest": "c946d18daae8b4cf29a5d79a39d266e2c6b37754d262ba7584c2268f55e5c76f",
"filesDigest": "5b527e8f22c5f082e5b61da1d0d6be54778ad40b02012fe3b878b6db5bd280cb",
"brainDigest": "c0fb7b079ded157059b91601361429944697dae3cc42abc00dfe1a680986b0f4",
"gateFingerprint": "6e53c784eee38310188948fc75fb49e6b4ebc04e247d01b903fa8c8a92d67bdd",
"developmentPins": {
Expand Down
2 changes: 1 addition & 1 deletion harness/ruview/.harness/manifest.sha256
Original file line number Diff line number Diff line change
@@ -1 +1 @@
baa345cff1caafc8d2bf686db32dfd00a812aaf2ccb786d1e6afc54d1c908a07 manifest.json
c4dba7eb06e89bc52b74a77e9a4fc0e7754c10130dcfba8f2fa9fe1d2f163cc5 manifest.json
36 changes: 36 additions & 0 deletions harness/ruview/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,42 @@ panic. A successful write alone is not hardware validation. WiFi provisioning
stays with `provision.py` (see the `provision-node` skill) so credentials never
pass through the harness.

## Declarative node config (`ruview node`)

One file, `~/.ruview/nodes.yaml` (template:
`firmware/esp32-csi-node/nodes.example.yaml`), declares the WiFi network, the
aggregator, the firmware source and every node by MAC: node ID, zone, TDM slot
and provisioning overrides. `ruview node apply` brings an attached board to its
declared state.

```bash
ruview node plan # validate config; nodes, firmware, secrets plan
ruview node status # read-only: per-node CSI rate/loss/RSSI + :8032 status
ruview node apply # read MAC, show the plan, ask "yes" before writing
ruview node apply --watch # each board plugged in: plan → yes → apply
ruview node apply --firmware-only --all --confirm # no questions (scripts); flash + validate, settings kept
```

- **Confirmation:** at a terminal every write is shown first and needs a
typed `yes`. `--confirm` skips the question. Without a terminal (pipes,
`--json`, MCP) and without `--confirm`, only the plan is printed.
- **Matching:** a board is identified by `esptool read_mac`. Listed MACs take
their configured node. Unlisted MACs reuse the node ID they had before, from
`~/.ruview/esp32-setup/devices.jsonl`, or get the next free ID unless
`auto_assign: false`.
- **Secrets:** `wifi.password_file` and `ota.psk_file` are paths (owner-only
files) passed to `provision.py`. The harness never reads them. Inline
passwords and env-var sources are refused.
- **Flashing:** reuses `flash` (checksums, chip check, boot log). `source:
auto|reuse` flashes the repo's ESP-IDF `build/` as an unverified local
build. `auto` refuses a build older than the firmware sources.
- **Validation:** waits for the node's CSI on the aggregator UDP port, then
checks `validate.min_pps` and the optional `validate.max_loss`. This is a
live measurement on this host, so stop the sensing server first (UDP port in
use otherwise).
- **YAML:** a strict subset (no dependency). Anchors, tags, multi-line strings,
flow maps, tabs, duplicate and unknown keys are errors.

## Training (ADR-371)

```bash
Expand Down
2 changes: 1 addition & 1 deletion harness/ruview/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
],
"scripts": {
"test": "node --test --test-concurrency=2 test/*.test.mjs",
"test:security": "node --test test/hosts.test.mjs test/brain.test.mjs test/policy.test.mjs test/spaces.test.mjs test/kernel.test.mjs test/firmware.test.mjs test/training.test.mjs test/devices.test.mjs test/csi-nodes.test.mjs test/remote.test.mjs test/mcp-apps.test.mjs test/cli-ui.test.mjs test/esphome.test.mjs",
"test:security": "node --test test/hosts.test.mjs test/brain.test.mjs test/policy.test.mjs test/spaces.test.mjs test/kernel.test.mjs test/firmware.test.mjs test/training.test.mjs test/devices.test.mjs test/csi-nodes.test.mjs test/remote.test.mjs test/mcp-apps.test.mjs test/cli-ui.test.mjs test/esphome.test.mjs test/node-config.test.mjs",
"doctor": "node ./bin/cli.js doctor",
"mcp": "node ./bin/cli.js mcp start",
"brain:verify": "node ./bin/cli.js brain verify",
Expand Down
126 changes: 126 additions & 0 deletions harness/ruview/src/cli.js
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,15 @@ Firmware (ADR-370, cross-platform esptool):
flash --port <p> --bundle <dir> [--variant ...] [--baud 460800] --confirm
[--boot-log-seconds 15] [--allow-unverified] write flash, then capture boot evidence

Node config (YAML: ~/.ruview/nodes.yaml, see firmware/esp32-csi-node/nodes.example.yaml):
node [plan] validate the config, list nodes, firmware + secrets plan
node status read-only: live CSI per node + each node's :8032 status
node apply [--port P | --all | --watch] [--confirm] bring the board (by MAC) to its config: config steps,
default flash → provision WiFi/NVS → validate
node apply --firmware-only [...] flash + validate; keeps WiFi/node settings
at a terminal: shows the plan and asks "yes" per board; --confirm skips the
question; pipes/--json without --confirm only print the plan

Devices (ADR-373) — run on the machine the hardware is attached to:
devices classify USB serial devices (ESP32, Realtek, mmWave, RPLIDAR)
esp32 [--udp-port 5005] [--seconds 10] [--bind 0.0.0.0] receive + summarize ESP32 / Realtek RAC1 node UDP streams
Expand Down Expand Up @@ -224,6 +233,122 @@ Hosts implemented and tested locally: claude-code (-p), codex (exec)`);
return 0;
}

/** `ruview node [plan|status|apply]` — declarative node config (node-config.js). */
async function nodeConfig(rest, flags) {
const action = rest[0] && !rest[0].startsWith('--') ? rest[0] : 'plan';
if (!['plan', 'status', 'apply'].includes(action)) {
console.error('Usage: ruview node [plan|status|apply] [--config ~/.ruview/nodes.yaml] [--port P | --all | --watch] [--firmware-only] [--confirm] [--json]');
return 2;
}
const flow = action === 'apply' && flags['firmware-only'] === true ? 'firmware' : 'apply';
const [fl, { OPERATOR_DEPS }, { captureEsp32 }] = await Promise.all([import('./node-config.js'), tools(), import('./devices/esp32.js')]);
const asJson = flags.json === true || !process.stdout.isTTY;
const out = (kind, res) => (asJson ? pjson(res) : console.log(fl.formatNodes(kind, res)));
let config;
try {
config = fl.loadNodeConfig(typeof flags.config === 'string' ? flags.config : fl.DEFAULT_CONFIG_PATH);
} catch (e) {
if (!(e instanceof fl.NodeConfigError)) throw e;
out('error', { ok: false, reason: e.reason, detail: e.message, errors: e.errors });
return 2;
}
// cwd first (an explicit checkout wins), then the checkout this CLI ships in,
// so `ruview node` works from any directory.
const repoRoot = OPERATOR_DEPS.findRepoRoot() || OPERATOR_DEPS.findRepoRoot(ROOT);
const tty = process.stderr.isTTY && !asJson;
const deps = {
exec: OPERATOR_DEPS.exec, python: OPERATOR_DEPS.python, fetch: OPERATOR_DEPS.fetch,
capture: (args) => captureEsp32(args), repoRoot, env: process.env,
log: (msg) => { if (tty) process.stderr.write(` … ${msg}\n`); },
};

if (action === 'plan') { const res = fl.planNodes(config, { repoRoot }); out('plan', res); return res.ok ? 0 : 1; }
if (action === 'status') {
const res = await withProgress(`Listening on UDP :${config.aggregator.port}`, config.validate.udp_secs, () => fl.nodeStatus(config, deps));
out('status', res); return res.ok ? 0 : 1;
}

// apply: one port, every ESP32 candidate (--all), or each new one (--watch).
// --confirm writes without asking. Otherwise a person at a terminal sees the
// plan and must type yes; pipes/--json/MCP only ever get the plan (fail closed).
const confirm = flags.confirm === true;
const interactive = !confirm && !asJson && process.stdin.isTTY === true && process.stderr.isTTY === true;
const askYes = async (question) => {
const { createInterface } = await import('node:readline/promises');
const rl = createInterface({ input: process.stdin, output: process.stderr });
try { return /^(y|yes)$/i.test((await rl.question(question)).trim()); }
catch { return false; } // Ctrl+C / closed stdin = no
finally { rl.close(); }
};
const one = async (port) => {
if (confirm) {
const res = await fl.applyBoard(config, { port, flow, confirm: true }, deps);
out(action, res);
return res.ok;
}
const plan = await fl.applyBoard(config, { port, flow, confirm: false }, deps);
if (interactive && plan.ok) delete plan.next;
out(action, plan);
if (!plan.ok || !interactive) return plan.ok;
const parts = plan.steps.filter((x) => ['flash', 'wifi'].includes(x)).map((x) => (x === 'flash' ? 'firmware' : 'WiFi/node settings'));
const what = `write ${parts.join(' + ') || 'nothing'} to`;
if (!(await askYes(` ? ${what} ${plan.mac} (node ${plan.node_id}) on ${port}? Type yes to continue [y/N] `))) {
console.error(' skipped — nothing was written');
return true;
}
const res = await fl.applyBoard(config, { port, flow, confirm: true,
expectedIdentity: { mac: plan.mac, nodeId: plan.node_id } }, deps);
out(action, res);
return res.ok;
};
const candidates = async () => {
const { scanDevices } = await import('./devices/registry.js');
const scan = await scanDevices(OPERATOR_DEPS);
if (!scan.ok) {
// Name the interpreter: an unrelated active venv shadowing python3 is the usual cause.
const py = OPERATOR_DEPS.python() || 'python3';
throw new fl.NodeConfigError(scan.reason, scan.reason === 'pyserial_missing'
? `${py} has no pyserial; run \`${py} -m pip install pyserial esptool\` or put a venv that has them first on PATH`
: (scan.remedy || 'serial scan failed'));
}
return scan.devices.filter((d) => d.likelyRoles.includes('esp32')).map((d) => d.port);
};
try {
if (typeof flags.port === 'string') return (await one(flags.port)) ? 0 : 1;
if (flags.watch === true) {
if (!confirm && !interactive) { console.error('node: --watch needs a terminal (asks per board) or --confirm'); return 2; }
const done = new Set();
let stop = false; let failures = 0;
process.once('SIGINT', () => { stop = true; });
console.error(`Watching for ESP32 boards (${flow}). Plug them in one at a time; Ctrl+C to finish.`);
while (!stop) {
const ports = await candidates();
for (const p of done) if (!ports.includes(p)) done.delete(p); // unplugged → socket reusable
const next = ports.find((p) => !done.has(p));
if (!next) { await new Promise((r) => setTimeout(r, 1000)); continue; }
await new Promise((r) => setTimeout(r, 1000)); // let the port settle
if (!(await one(next))) failures += 1;
done.add(next);
console.error('→ unplug it and plug in the next board');
}
return failures ? 1 : 0;
}
const ports = await candidates();
if (flags.all === true) {
if (!ports.length) { console.error('node: no ESP32 candidates found (ruview devices)'); return 1; }
let ok = true;
for (const p of ports) ok = (await one(p)) && ok;
return ok ? 0 : 1;
}
if (ports.length !== 1) { console.error(`node: found ${ports.length} ESP32 candidates (${ports.join(', ') || 'none'}); pass --port, --all or --watch`); return 2; }
return (await one(ports[0])) ? 0 : 1;
} catch (e) {
if (!(e instanceof fl.NodeConfigError)) throw e;
out('error', { ok: false, reason: e.reason, detail: e.message });
return 1;
}
}

/** tiny flag parser: --k v / --k=v / --flag (boolean) */
function parseFlags(rest) {
const f = {};
Expand Down Expand Up @@ -291,6 +416,7 @@ export async function run(args, opts = {}) {

switch (cmd) {
case 'doctor': return doctor(flags);
case 'node': return nodeConfig(rest, flags);
case 'skills': console.log(listSkills().join('\n') || '(none)'); return 0;
case 'skill': {
const n = rest[0];
Expand Down
2 changes: 2 additions & 0 deletions harness/ruview/src/devices/esp32.js
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ export class NodeStats {
this.nodes.set(key, n);
}
n.packets[pkt.kind] = (n.packets[pkt.kind] || 0) + 1;
if (sender) n.address = sender; // last sender: lets callers reach the node (e.g. :8032)
if (pkt.kind === 'csi') {
n.rssiSum += pkt.rssi; n.rssiCount += 1;
trackSequence(n, pkt.seq);
Expand Down Expand Up @@ -290,6 +291,7 @@ export class NodeStats {
return {
source: n.source,
nodeId: n.nodeId,
...(n.address ? { address: n.address } : {}),
packets: n.packets,
csiRateHz: Number((csi / seconds).toFixed(2)),
csiLossFraction: received ? Number((n.seqGaps / received).toFixed(4)) : null,
Expand Down
Loading