Skip to content

Commit e44e97b

Browse files
authored
Merge 578ca7b into 13b4788
2 parents 13b4788 + 578ca7b commit e44e97b

10 files changed

Lines changed: 1433 additions & 8 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -405,6 +405,7 @@ jobs:
405405
# workflow, so it doesn't gate the rest of the pipeline.
406406
docker-build:
407407
name: Docker Build & Test
408+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
408409
runs-on: ubuntu-latest
409410
needs: [code-quality, test, rust-tests]
410411
continue-on-error: true
@@ -525,7 +526,7 @@ jobs:
525526
name: Notify
526527
runs-on: ubuntu-latest
527528
needs: [code-quality, test, rust-tests, ui-tests, performance-test, docker-build, docs]
528-
if: always()
529+
if: always() && github.event_name == 'push' && github.ref == 'refs/heads/main'
529530
permissions:
530531
contents: write # required by softprops/action-gh-release
531532
# GitHub Actions does not allow `secrets.X` directly in step-level `if:`
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# RuView declarative node config — read by `ruview node` (harness/ruview/src/node-config.js).
2+
#
3+
# cp nodes.example.yaml ~/.ruview/nodes.yaml # keep the real one OUT of git
4+
# ruview node plan # validate + show what would happen
5+
# ruview node apply --watch # apply to each board as you plug it in
6+
# ruview node status # read-only health of every node
7+
#
8+
# Supported YAML: block maps/lists, [a, b] lists, quoted or plain scalars and
9+
# comments. Anchors, tags, multi-line strings and unknown keys are rejected.
10+
11+
wifi:
12+
ssid: "MyHome-2G" # 2.4 GHz network
13+
# Path only: ruview never reads it, provision.py does. Inline passwords are refused.
14+
password_file: ~/.ruview/wifi-pass # chmod 600; the password, one line
15+
16+
# OTA key (64 hex chars, chmod 600). Without it, provisioning DISABLES remote
17+
# OTA updates and config_push on the node. Create one with:
18+
# (umask 077; set -C; openssl rand -hex 32 > ~/.ruview-ota-psk)
19+
# ota:
20+
# psk_file: ~/.ruview-ota-psk
21+
22+
aggregator:
23+
ip: auto # auto = this machine's private LAN IPv4
24+
port: 5005
25+
26+
firmware:
27+
source: auto # auto: repo build/ unless sources changed | reuse: build/ as-is | bundle: release dir
28+
variant: s3-8mb # s3-8mb | s3-4mb | c6
29+
# bundle: ~/Downloads/esp32-csi-node-firmware-4mb # source: bundle (needs SHA256SUMS)
30+
31+
steps: [device, driver, flash, wifi, validate] # used by `node apply`
32+
33+
validate:
34+
wait_secs: 60 # max wait for the node's first CSI packet after provisioning
35+
udp_secs: 15 # measurement window
36+
min_pps: 20 # CSI rate floor (firmware README acceptance floor)
37+
# max_loss: 0.4 # optional ceiling on CSI sequence loss (0-1)
38+
39+
# Applied to every node unless the node overrides it.
40+
defaults:
41+
edge_tier: 2 # 0=raw, 1=stats, 2=vitals
42+
# channel: 6
43+
# pres_thresh: 50
44+
45+
# Boards that are gone for good. Their node_id (kept in the registry) is
46+
# released so a replacement can take it; plugging a retired board back in is refused.
47+
# retired:
48+
# - "aa:bb:cc:dd:ee:09"
49+
50+
# Boards not listed get the next free node_id; the registry
51+
# (~/.ruview/esp32-setup/devices.jsonl) keeps it stable across runs.
52+
# Set false to refuse unlisted boards.
53+
auto_assign: true
54+
55+
# Matched by MAC (`ruview node apply` prints it). tdm_total = nodes with a tdm_slot.
56+
nodes:
57+
- mac: "aa:bb:cc:dd:ee:01"
58+
node_id: 1
59+
zone: living-room
60+
tdm_slot: 0
61+
# - mac: "aa:bb:cc:dd:ee:02"
62+
# node_id: 2
63+
# zone: bedroom
64+
# tdm_slot: 1
65+
# edge_tier: 1

‎harness/ruview/.harness/manifest.json‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
".mcp/servers.json": "fec6075400f8350d8075beac8306690355c4b015425bfd0e5f52966234e9d66f",
2424
"CLAUDE.md": "25f9306b6caae22078cb9375108b6f6bb813d83e617739f6d9372f116b0ede5d",
2525
"LICENSE": "631f94984f626818d42ecf717aa6e8e0afd4f9f355ca706bd2effafbd1416d06",
26-
"README.md": "d761e75678ac48c391b86e9094c207193f01d351235b8c77fc709983e57accd7",
26+
"README.md": "14ff0b70ea6b02e63d960a32523299a63e560d31b5fccd292220915e5a9ccf97",
2727
"bin/cli.js": "8ebf6ca4b6d9529a5e338374c19329c1a2fc2f9e52f13b4341928b7168ee461b",
2828
"brain/corpus/core.jsonl": "c0fb7b079ded157059b91601361429944697dae3cc42abc00dfe1a680986b0f4",
2929
"flywheel/evaluations.json": "ac4ff1f897a2444870cd2b8ae8aee8b1578e61467aeca4db57893f41be98a572",
@@ -32,7 +32,7 @@
3232
"flywheel/genome.json": "75db44a3cab70d9459fc8c07863f640ac1214bfaa243483939e1506d63f51214",
3333
"flywheel/replay.mjs": "0670ca0b03701f4afe0b4bca8a3d58d481676b61a94a5b98c6a425aefb1159ab",
3434
"flywheel/run.mjs": "6d4f97db16900c45367b6538848cbe1915af999e663720dfc51f2bb1698f1cd0",
35-
"package.json": "d6ba81ba3cad035c5ddd17d2d84d1f02a273c6ac588b77c1592497d720803f3c",
35+
"package.json": "96014281a1c3be5c43cb13f0a79bcf2ec425271c37f832ac55e97b2bfb7c104a",
3636
"scripts/sync-skills.mjs": "43715dab61e204dc91bbd61755810e8fdb2f66e2b0c0bd791b4bf48a2e293565",
3737
"scripts/update-manifest.mjs": "8f56764b8f70aed55da0c7e2417ae875b0d58d781d839b6db7f115f08af61e6b",
3838
"scripts/verify-manifest.mjs": "6491a221762efcfeb3e749ecab243b204f17fd5bc871f3d4025597f31b8f0f10",
@@ -45,8 +45,8 @@
4545
"skills/verify.md": "2d38d240e9810a7827e2ebd3717dc0f85c646cc92e46c3812fe77c5b9eb40b76",
4646
"src/brain.js": "0f16a75aea943acdacc430ff11d5df7ecdec9cca2ab497795ff6f33eaebdfab6",
4747
"src/cli-ui.js": "5ac04c5790f03df708c24a6dd366b51ff33a643691642b689284bcada25c9d9a",
48-
"src/cli.js": "9b604f5c05a9d3338bd56f4386272a2624e7c5ee9676fcbc4bbfff6b86916571",
49-
"src/devices/esp32.js": "21b8c74d9b0a47f52538b5d902faa32ac6f4c58dab94d6612d7fbc89237d8f80",
48+
"src/cli.js": "94fd0631944bec2386bf8f3b2e59abd7058fa4f68bd05943eb2a3cff101dcc74",
49+
"src/devices/esp32.js": "587e875cdaddb7b942c4e2c0521595456894762b842446e553b8c69d2c1ad32f",
5050
"src/devices/esphome.js": "d4429fd09c8d93fdc2e5926305d8193c98e074affc48deabda4b16bb9b620056",
5151
"src/devices/lidar.js": "d9a91e2b6eec21463bbb950fc333e9d0ebd2699a7c533d534323bb4d6a55bd97",
5252
"src/devices/mmwave.js": "2ac0be6c4be3c71d147d4bc57b8fd516d051234a8897295bc9e7f9c36c8ae710",
@@ -63,6 +63,7 @@
6363
"src/kernel.js": "48dfd218a747dd158f82ae108e7e8ed89a82cd68649214d23266112dc9033f5d",
6464
"src/mcp-http.js": "b72e021ae00d01831ef7184db824f5e85a2b8747e1d8e994b6a1cb1cb4d08945",
6565
"src/mcp-server.js": "5eb8c3431768932c3a85476df032d0608fc7a732ede3d6bdcc8467ca47552666",
66+
"src/node-config.js": "7d76efae4d6214b8f635fb2d9c7efbec0520892b959b7bb035c3b1ad9d22f09e",
6667
"src/policy.js": "baad5eb8c3eb2e416e0a71b342ad850d7c8413d7d976571ebf596937f69da8e2",
6768
"src/process-runner.js": "49533b038044dfb8bc76ed01c030d06a9856ead0836157fb693e2a7d40f786d6",
6869
"src/redact.js": "ebf1afff46341078706b0401838c53db043603586e280d51ece5cf1feba35189",
@@ -75,7 +76,7 @@
7576
"src/training.js": "bd8a6c12eba4f9d2f8990fa9692cd04c743ea247f9b13e10f8717ceefcbd09ac",
7677
"src/ui/console-widget.js": "0d2f707d57b5ec54968dee1dc80f31c7db9152dcadfc48700c18379dabb55462"
7778
},
78-
"filesDigest": "c946d18daae8b4cf29a5d79a39d266e2c6b37754d262ba7584c2268f55e5c76f",
79+
"filesDigest": "06f83e927733f8964056cce94d0790c5631155e9198f31ecb5a9d50ae91cee54",
7980
"brainDigest": "c0fb7b079ded157059b91601361429944697dae3cc42abc00dfe1a680986b0f4",
8081
"gateFingerprint": "6e53c784eee38310188948fc75fb49e6b4ebc04e247d01b903fa8c8a92d67bdd",
8182
"developmentPins": {
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
baa345cff1caafc8d2bf686db32dfd00a812aaf2ccb786d1e6afc54d1c908a07 manifest.json
1+
a0dbdf2751dd2ec155c88e99ecb45436ebecd01c5e41eeb7933fd06c77f3128b manifest.json

‎harness/ruview/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,44 @@ panic. A successful write alone is not hardware validation. WiFi provisioning
140140
stays with `provision.py` (see the `provision-node` skill) so credentials never
141141
pass through the harness.
142142

143+
## Declarative node config (`ruview node`)
144+
145+
One file, `~/.ruview/nodes.yaml` (template:
146+
`firmware/esp32-csi-node/nodes.example.yaml`), declares the WiFi network, the
147+
aggregator, the firmware source and every node by MAC: node ID, zone, TDM slot
148+
and provisioning overrides. `ruview node apply` brings an attached board to its
149+
declared state.
150+
151+
```bash
152+
ruview node plan # validate config; nodes, firmware, secrets plan
153+
ruview node status # read-only: per-node CSI rate/loss/RSSI + :8032 status
154+
ruview node apply # read MAC, show the plan, ask "yes" before writing
155+
ruview node apply --watch # each board plugged in: plan → yes → apply
156+
ruview node apply --firmware-only --all --confirm # no questions (scripts); flash + validate, settings kept
157+
```
158+
159+
- **Confirmation:** at a terminal every write is shown first and needs a
160+
typed `yes`. `--confirm` skips the question. Without a terminal (pipes,
161+
`--json`, MCP) and without `--confirm`, only the plan is printed.
162+
- **Matching:** a board is identified by `esptool read_mac`. Listed MACs take
163+
their configured node. Unlisted MACs reuse the node ID they had before, from
164+
`~/.ruview/esp32-setup/devices.jsonl`, or get the next free ID unless
165+
`auto_assign: false`. Two boards may never share an ID: `plan` and `apply`
166+
both refuse a conflict. A board that is gone for good goes under
167+
`retired:`, which releases its retained ID for a replacement.
168+
- **Secrets:** `wifi.password_file` and `ota.psk_file` are paths (owner-only
169+
files) passed to `provision.py`. The harness never reads them. Inline
170+
passwords and env-var sources are refused.
171+
- **Flashing:** reuses `flash` (checksums, chip check, boot log). `source:
172+
auto|reuse` flashes the repo's ESP-IDF `build/` as an unverified local
173+
build. `auto` refuses a build older than the firmware sources.
174+
- **Validation:** waits for the node's CSI on the aggregator UDP port, then
175+
checks `validate.min_pps` and the optional `validate.max_loss`. This is a
176+
live measurement on this host, so stop the sensing server first (UDP port in
177+
use otherwise).
178+
- **YAML:** a strict subset (no dependency). Anchors, tags, multi-line strings,
179+
flow maps, tabs, duplicate and unknown keys are errors.
180+
143181
## Training (ADR-371)
144182

145183
```bash

‎harness/ruview/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
],
4848
"scripts": {
4949
"test": "node --test --test-concurrency=2 test/*.test.mjs",
50-
"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",
50+
"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",
5151
"doctor": "node ./bin/cli.js doctor",
5252
"mcp": "node ./bin/cli.js mcp start",
5353
"brain:verify": "node ./bin/cli.js brain verify",

‎harness/ruview/src/cli.js‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,15 @@ Firmware (ADR-370, cross-platform esptool):
182182
flash --port <p> --bundle <dir> [--variant ...] [--baud 460800] --confirm
183183
[--boot-log-seconds 15] [--allow-unverified] write flash, then capture boot evidence
184184
185+
Node config (YAML: ~/.ruview/nodes.yaml, see firmware/esp32-csi-node/nodes.example.yaml):
186+
node [plan] validate the config, list nodes, firmware + secrets plan
187+
node status read-only: live CSI per node + each node's :8032 status
188+
node apply [--port P | --all | --watch] [--confirm] bring the board (by MAC) to its config: config steps,
189+
default flash → provision WiFi/NVS → validate
190+
node apply --firmware-only [...] flash + validate; keeps WiFi/node settings
191+
at a terminal: shows the plan and asks "yes" per board; --confirm skips the
192+
question; pipes/--json without --confirm only print the plan
193+
185194
Devices (ADR-373) — run on the machine the hardware is attached to:
186195
devices classify USB serial devices (ESP32, Realtek, mmWave, RPLIDAR)
187196
esp32 [--udp-port 5005] [--seconds 10] [--bind 0.0.0.0] receive + summarize ESP32 / Realtek RAC1 node UDP streams
@@ -224,6 +233,122 @@ Hosts implemented and tested locally: claude-code (-p), codex (exec)`);
224233
return 0;
225234
}
226235

236+
/** `ruview node [plan|status|apply]` — declarative node config (node-config.js). */
237+
async function nodeConfig(rest, flags) {
238+
const action = rest[0] && !rest[0].startsWith('--') ? rest[0] : 'plan';
239+
if (!['plan', 'status', 'apply'].includes(action)) {
240+
console.error('Usage: ruview node [plan|status|apply] [--config ~/.ruview/nodes.yaml] [--port P | --all | --watch] [--firmware-only] [--confirm] [--json]');
241+
return 2;
242+
}
243+
const flow = action === 'apply' && flags['firmware-only'] === true ? 'firmware' : 'apply';
244+
const [fl, { OPERATOR_DEPS }, { captureEsp32 }] = await Promise.all([import('./node-config.js'), tools(), import('./devices/esp32.js')]);
245+
const asJson = flags.json === true || !process.stdout.isTTY;
246+
const out = (kind, res) => (asJson ? pjson(res) : console.log(fl.formatNodes(kind, res)));
247+
let config;
248+
try {
249+
config = fl.loadNodeConfig(typeof flags.config === 'string' ? flags.config : fl.DEFAULT_CONFIG_PATH);
250+
} catch (e) {
251+
if (!(e instanceof fl.NodeConfigError)) throw e;
252+
out('error', { ok: false, reason: e.reason, detail: e.message, errors: e.errors });
253+
return 2;
254+
}
255+
// cwd first (an explicit checkout wins), then the checkout this CLI ships in,
256+
// so `ruview node` works from any directory.
257+
const repoRoot = OPERATOR_DEPS.findRepoRoot() || OPERATOR_DEPS.findRepoRoot(ROOT);
258+
const tty = process.stderr.isTTY && !asJson;
259+
const deps = {
260+
exec: OPERATOR_DEPS.exec, python: OPERATOR_DEPS.python, fetch: OPERATOR_DEPS.fetch,
261+
capture: (args) => captureEsp32(args), repoRoot, env: process.env,
262+
log: (msg) => { if (tty) process.stderr.write(` … ${msg}\n`); },
263+
};
264+
265+
if (action === 'plan') { const res = fl.planNodes(config, { repoRoot }); out('plan', res); return res.ok ? 0 : 1; }
266+
if (action === 'status') {
267+
const res = await withProgress(`Listening on UDP :${config.aggregator.port}`, config.validate.udp_secs, () => fl.nodeStatus(config, deps));
268+
out('status', res); return res.ok ? 0 : 1;
269+
}
270+
271+
// apply: one port, every ESP32 candidate (--all), or each new one (--watch).
272+
// --confirm writes without asking. Otherwise a person at a terminal sees the
273+
// plan and must type yes; pipes/--json/MCP only ever get the plan (fail closed).
274+
const confirm = flags.confirm === true;
275+
const interactive = !confirm && !asJson && process.stdin.isTTY === true && process.stderr.isTTY === true;
276+
const askYes = async (question) => {
277+
const { createInterface } = await import('node:readline/promises');
278+
const rl = createInterface({ input: process.stdin, output: process.stderr });
279+
try { return /^(y|yes)$/i.test((await rl.question(question)).trim()); }
280+
catch { return false; } // Ctrl+C / closed stdin = no
281+
finally { rl.close(); }
282+
};
283+
const one = async (port) => {
284+
if (confirm) {
285+
const res = await fl.applyBoard(config, { port, flow, confirm: true }, deps);
286+
out(action, res);
287+
return res.ok;
288+
}
289+
const plan = await fl.applyBoard(config, { port, flow, confirm: false }, deps);
290+
if (interactive && plan.ok) delete plan.next;
291+
out(action, plan);
292+
if (!plan.ok || !interactive) return plan.ok;
293+
const parts = plan.steps.filter((x) => ['flash', 'wifi'].includes(x)).map((x) => (x === 'flash' ? 'firmware' : 'WiFi/node settings'));
294+
const what = `write ${parts.join(' + ') || 'nothing'} to`;
295+
if (!(await askYes(` ? ${what} ${plan.mac} (node ${plan.node_id}) on ${port}? Type yes to continue [y/N] `))) {
296+
console.error(' skipped — nothing was written');
297+
return true;
298+
}
299+
const res = await fl.applyBoard(config, { port, flow, confirm: true,
300+
expectedIdentity: { mac: plan.mac, nodeId: plan.node_id } }, deps);
301+
out(action, res);
302+
return res.ok;
303+
};
304+
const candidates = async () => {
305+
const { scanDevices } = await import('./devices/registry.js');
306+
const scan = await scanDevices(OPERATOR_DEPS);
307+
if (!scan.ok) {
308+
// Name the interpreter: an unrelated active venv shadowing python3 is the usual cause.
309+
const py = OPERATOR_DEPS.python() || 'python3';
310+
throw new fl.NodeConfigError(scan.reason, scan.reason === 'pyserial_missing'
311+
? `${py} has no pyserial; run \`${py} -m pip install pyserial esptool\` or put a venv that has them first on PATH`
312+
: (scan.remedy || 'serial scan failed'));
313+
}
314+
return scan.devices.filter((d) => d.likelyRoles.includes('esp32')).map((d) => d.port);
315+
};
316+
try {
317+
if (typeof flags.port === 'string') return (await one(flags.port)) ? 0 : 1;
318+
if (flags.watch === true) {
319+
if (!confirm && !interactive) { console.error('node: --watch needs a terminal (asks per board) or --confirm'); return 2; }
320+
const done = new Set();
321+
let stop = false; let failures = 0;
322+
process.once('SIGINT', () => { stop = true; });
323+
console.error(`Watching for ESP32 boards (${flow}). Plug them in one at a time; Ctrl+C to finish.`);
324+
while (!stop) {
325+
const ports = await candidates();
326+
for (const p of done) if (!ports.includes(p)) done.delete(p); // unplugged → socket reusable
327+
const next = ports.find((p) => !done.has(p));
328+
if (!next) { await new Promise((r) => setTimeout(r, 1000)); continue; }
329+
await new Promise((r) => setTimeout(r, 1000)); // let the port settle
330+
if (!(await one(next))) failures += 1;
331+
done.add(next);
332+
console.error('→ unplug it and plug in the next board');
333+
}
334+
return failures ? 1 : 0;
335+
}
336+
const ports = await candidates();
337+
if (flags.all === true) {
338+
if (!ports.length) { console.error('node: no ESP32 candidates found (ruview devices)'); return 1; }
339+
let ok = true;
340+
for (const p of ports) ok = (await one(p)) && ok;
341+
return ok ? 0 : 1;
342+
}
343+
if (ports.length !== 1) { console.error(`node: found ${ports.length} ESP32 candidates (${ports.join(', ') || 'none'}); pass --port, --all or --watch`); return 2; }
344+
return (await one(ports[0])) ? 0 : 1;
345+
} catch (e) {
346+
if (!(e instanceof fl.NodeConfigError)) throw e;
347+
out('error', { ok: false, reason: e.reason, detail: e.message });
348+
return 1;
349+
}
350+
}
351+
227352
/** tiny flag parser: --k v / --k=v / --flag (boolean) */
228353
function parseFlags(rest) {
229354
const f = {};
@@ -291,6 +416,7 @@ export async function run(args, opts = {}) {
291416

292417
switch (cmd) {
293418
case 'doctor': return doctor(flags);
419+
case 'node': return nodeConfig(rest, flags);
294420
case 'skills': console.log(listSkills().join('\n') || '(none)'); return 0;
295421
case 'skill': {
296422
const n = rest[0];

‎harness/ruview/src/devices/esp32.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,7 @@ export class NodeStats {
258258
this.nodes.set(key, n);
259259
}
260260
n.packets[pkt.kind] = (n.packets[pkt.kind] || 0) + 1;
261+
if (sender) n.address = sender; // last sender: lets callers reach the node (e.g. :8032)
261262
if (pkt.kind === 'csi') {
262263
n.rssiSum += pkt.rssi; n.rssiCount += 1;
263264
trackSequence(n, pkt.seq);
@@ -290,6 +291,7 @@ export class NodeStats {
290291
return {
291292
source: n.source,
292293
nodeId: n.nodeId,
294+
...(n.address ? { address: n.address } : {}),
293295
packets: n.packets,
294296
csiRateHz: Number((csi / seconds).toFixed(2)),
295297
csiLossFraction: received ? Number((n.seqGaps / received).toFixed(4)) : null,

0 commit comments

Comments
 (0)