Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
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
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": "ae06aa31b2e1f93902a8a05070b5248327bc3aa17219ea4611d29a95ea7efc11",
"README.md": "a5b814493c3f6fd847de7dc0a8f66e95f4f5c2f7c6715e5957aa4cb5a4ac1855",
"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": "d1d313a9e57244c817d688918c150c46aaf7aeb50ca65c0d982690e302ef7fdd",
"package.json": "46fc4d0bf96b782164bc9c24e9fbe6a8c176495cd1e83fd03a1766cc88850732",
"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": "bb7989f4660566cd016a0cb3c44b6e816d19618ed94337398488732056e8202b",
"src/devices/esp32.js": "21b8c74d9b0a47f52538b5d902faa32ac6f4c58dab94d6612d7fbc89237d8f80",
"src/cli.js": "9f2fcb67faa9540c6335d36edb284dcb1e9a22e185445307eaf6695efc635f01",
"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": "a38e9ea3da8b60ffff662c73525418b4e6ffe58f7c1a0797b82defdda4908457",
"src/firmware.js": "5a9b8d38e92280b1e46dd16b19222d9529e16b2bed9134fbb0d9dea44b033c12",
"src/guardrails.js": "aacc8fa6088f7f1ccea3a0b02171a5c516b95d3416ee3ba87add3879a1d6aaad",
"src/guidance.js": "1e0ccee808a736319b3f8257a3fc4fc0f8d9f8956970887d597870bb8d615949",
"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": "ed7e9e83668dace777b71af2fa475f153a2793a826ae446047e9103aba95539e",
"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": "edc6be28115ad21f18954066e989a6b4aaae2137b2f4e6d6571312beef610288",
"filesDigest": "c5afe0760a50ee0be0c086f1c92138f10b7937b416d23468a6559c943573eeea",
"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 @@
0517e22827b8acc7d8550e1e560e4f13ca79397977c52c30cf23770dead2327a manifest.json
729e0fb4349c429ea448e867eb203329cb0f314affeb85e87b0b88990450ad60 manifest.json
36 changes: 36 additions & 0 deletions harness/ruview/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,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/*.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
125 changes: 125 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,121 @@ 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 }, 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 +415,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
3 changes: 2 additions & 1 deletion harness/ruview/src/firmware.js
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,8 @@ export function summarizeBootLog(text) {
const lines = String(text).split(/\r?\n/);
const csi = lines.filter((l) => /CSI cb|csi_collector/.test(l)).length;
const panic = lines.some((l) => /Guru Meditation|abort\(\) was called|Backtrace:/.test(l));
const version = (/(?:RuView|esp32-csi-node)[^\n]*?v?(\d+\.\d+\.\d+)/i.exec(text) || [])[1] || null;
// Banners: "esp32-csi-node v0.8.1", "RuView … 0.8.1", "ESP32-S3 CSI Node (ADR-018 / ADR-110) — v0.8.15".
const version = (/(?:RuView|esp32-csi-node|CSI Node)[^\n]*?v?(\d+\.\d+\.\d+)/i.exec(text) || [])[1] || null;
return {
lines: lines.filter(Boolean).length,
csiCallbacks: csi,
Expand Down
Loading