Introducing a new way to review your PRs.

Read the announcement

ruvnet / ruview

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / scripts-data-training-operations

Scripts, Data, Training, and Operations

Overview

This area is the repository's operational surface: executable scripts for collecting CSI and ground-truth data, training and benchmarking models, replaying proof artifacts, simulating ESP32 firmware under QEMU, publishing releases, and exposing sensing data to HomeKit/MCP/CLI consumers. The root Makefile is the short entrypoint: install targets delegate to install.sh, verification targets delegate to verify, Rust build/test targets run under v2/, and run targets start the archived Python API, static UI server, or Docker stack.

install.sh is a profile-driven bootstrapper. It detects OS, RAM/disk/GPU, Python/Rust/wasm-pack/Docker/Node/ESP-IDF/OpenBLAS, and WiFi or ESP32-capable hardware, then recommends or runs one of the verify, python, rust, browser, iot, docker, field, or full profiles. The profile selection controls dependency installation and build actions: verify installs numpy/scipy and runs verify; rust builds and tests v2; browser and field build the WASM crate; iot builds the ESP32 aggregator crate; docker builds the Docker image. deploy.sh is the separate production cloud deploy orchestrator: it checks AWS/kubectl/helm/terraform/docker credentials, applies Terraform from terraform/, pushes Docker images to ECR, applies Kubernetes manifests from k8s/, installs Prometheus/Grafana/Fluentd monitoring, validates ingress health, and prints CI/CD secret requirements.

Data collection starts with radio or camera capture scripts. scripts/collect-training-data.py listens for ESP32 UDP packets and writes data/recordings/<session>.csi.jsonl plus .csi.meta.json sidecars and manifest.json. It understands ADR-018 raw CSI packets (0xC5110001) and ADR-069 feature-vector packets (0xC5110003), normalizes raw I/Q pairs into amplitude subcarriers, stamps receive time when firmware has no timestamp, and can record one or two UDP ports, repeated scenarios, or manifest-only scans. scripts/collect-ground-truth.py captures webcam frames through MediaPipe PoseLandmarker, maps the 33 MediaPipe landmarks to 17 COCO keypoints, starts/stops a synchronized CSI recording through /api/v1/recording/start|stop on the sensing server, and writes data/ground-truth/keypoints_<ts>.jsonl. When passed a bundle from scripts/calibrate-camera-room.py, it calls scripts/calibration_lib.py to add keypoints_room bearing rays, camera_origin_room, calibration_id, and transceiver geometry to every camera label.

The calibration flow is split deliberately. scripts/calibrate-camera-room.py detects checkerboard corners in fixed wall and floor photos, computes or loads intrinsics, solves a joint two-checkerboard camera-to-room transform, collects ESP32 transceiver positions from a JSON file or tape-measure prompts, and saves a bundle under data/calibration/. scripts/calibration_lib.py owns the math and artifact schema: checkerboard room points, intrinsics, two-board PnP solving, bundle hashing, and conversion of normalized image keypoints into room-frame unit bearing rays. Because a single 2D keypoint only defines a ray, not a metric 3D point, downstream training must preserve the raw image coordinates and treat room-frame rays as projective labels.

Reference labels and replay rows are built from independent window loggers. scripts/radar_window_logger.py parses MR60BHA2/ESPHome serial logs or raw-log replays into fixed radar-window JSONL with health, presence, distance_cm, room, zone, and source.verified/simulated. scripts/input_activity_logger.py is a Windows-only occupied-only reference that records idle time via GetLastInputInfo; recent input emits health: ok, presence: true, while no input emits health: unknown and can never label an empty room. scripts/build_replay_rows.py converts sensing-server FANN shadow feature captures into replay rows by joining them to radar/input windows, operator-declared empty sessions, or incumbent labels. Its output rows carry room, session, split, condition, features, incumbent_probability, synthetic, timestamp, and label_source so replay reports can distinguish measured accuracy from incumbent imitation.

The live sensing bridge for demos and agents is file-based. scripts/c6-presence-watcher.py receives the ESP32-C6 60-byte rv_feature_state UDP struct, verifies CRC32, applies a PrivacyClass gate, drives a legacy HomeKit motion toggle file (/tmp/ruview-motion), writes /tmp/ruview-state.json with motion/occupancy/anomaly state, and writes /tmp/ruview-last-feature.json as the richer state consumed by scripts/ruview-sensing-server.py. The watcher enforces hysteresis thresholds and rolling occupancy windows before crossing the HAP boundary. scripts/ruview-sensing-server.py serves the subset of the RuView sensing-server HTTP API used by tools/ruview-mcp: /health, /api/v1/sensing/latest, edge registry, vitals, BFLD last-scan/subscribe, and semantic events. scripts/hap-test-sensor.py exposes a single test HomeKit bridge using /tmp/ruview-state.json or the legacy toggle file; scripts/ruview-hap-bridge.py exposes production multi-room child accessories by discovering /tmp/ruview-state.<room>.json files.

The JavaScript WiFlow training family uses collected JSONL and the vendored ruvllm infrastructure. scripts/wiflow-model.js implements the pure-JS WiFlow-style CSI-to-17-keypoint model: temporal causal convolutions, batch norm, spatial/attention stages, adaptive pooling/decoder utilities, COCO keypoint constants, bone priors, deterministic PRNG helpers, and FLOP estimates. scripts/train-wiflow.js is the broad pipeline for raw or feature CSI: it loads CSI JSONL, windows per node, runs contrastive pretraining, supervised pose training, LoRA room adaptation, quantization, and exports SafeTensors, config, JSON model, quantized blobs, LoRA adapters, RVF JSONL, and training-metrics.json under the configured output directory. scripts/train-wiflow-supervised.js expects paired CSI+camera keypoint JSONL, trains a scaled TCN pose regressor through contrastive/supervised/refinement phases, and writes wiflow-v1.json, training-log.json, and holdout evaluation JSONL. scripts/train-camera-free.js adds Cognitum Seed supervision: it probes HTTPS Seed sensor endpoints, combines CSI with PIR/BME/RSSI/vitals/input-derived signals, trains presence/pose heads without camera labels, exports the same SafeTensors/config/model/quantized/LoRA/RVF/metrics family, and optionally benchmarks the result.

Python/Rust training and cloud helpers are more task-specific. scripts/gcloud-train.sh provisions a temporary GCP GPU VM, installs Rust and libtorch, uploads local data/config or runs a sweep, builds the Rust wifi-densepose-train binary, downloads artifacts, and tears down the VM unless --keep-vm is set. scripts/mac-mini-train.sh is a local M4 Pro workflow that clones/updates the repo, copies pretrain-*.csi.jsonl from a Windows host over Tailscale, runs train-ruvllm.js and benchmark-ruvllm.js, syncs results back, and optionally publishes to HuggingFace. tools/…/train.ts and tools/…/train-count.ts expose count-cog training as detached cargo run -p wifi-densepose-train -- --task count jobs, with logs stored under ~/.ruview/jobs by default.

Benchmarking is split between live-model benchmarks and curated external reproductions. scripts/benchmark-model.py loads ONNX models with onnxruntime, builds synthetic or .csi.jsonl sliding-window inputs, reports latency percentiles, throughput, model size, parameter/FLOP estimates, and optional PCK/MPJPE. scripts/benchmark-wiflow.js benchmarks the pure-JS WiFlow model's parameter count, FLOPs, quantized memory size estimates, batch latency, output range, variance, and bone violations. scripts/presence_benchmark.py joins verified radar windows to CSI presence predictions and performs leave-one-room-out threshold selection, reporting MEASURED only when labels are verified and predictions are non-synthetic. scripts/track_benchmark.py scores per-person counts, detection, tracking, identity switches, fragmentation, and position error while preserving an explicit ambiguous reference-window class.

benchmarks/wiflow-std/ is the WiFlow-STD reproduction workspace. _bench_common.py centralizes the upstream import shim, mmap patch for >1 GB .npy files, legacy checkpoint key remapping, model loading, seeding, and canonical PCK/MPJPE evaluation. eval_repro.py runs the released checkpoint on the released Kaggle split; onnx_bench.py, quantize_bench.py, eval_ort_accuracy.py, and static_ptq_bench.py export and quantify ONNX/INT8 variants; generate_corruption_masks.py regenerates committed corruption masks; remote/ contains single-file runners for the GPU retraining and sweep host. benchmarks/…/RESULTS.md is the evidence ledger and records that the shipped checkpoint is refuted as-is, retraining after repairing corrupt data approximately reproduces the paper, and ONNX/static-PTQ trade size for slower CPU latency.

QEMU and firmware validation scripts form an end-to-end simulated hardware harness. scripts/qemu-cli.sh is the unified shell entrypoint for install, single-node test, mesh, swarm, snapshot, chaos, fuzz, NVS matrix, and health commands. scripts/qemu-esp32s3-test.sh builds firmware with sdkconfig.qemu, merges bootloader/partition/app binaries into qemu_flash.bin, injects optional NVS at 0x9000, runs qemu-system-xtensa -machine esp32s3, captures UART output, and calls scripts/validate_qemu_output.py. That validator checks boot, NVS, frame generation, edge pipeline, vitals/presence/fall serialization, frame rate, and crash signatures, returning graded exit codes. scripts/qemu-mesh-test.sh uses root-created Linux TAP/bridge networking, per-node NVS from firmware provision.py, and a Rust aggregator before scripts/validate_mesh_test.py. scripts/qemu_swarm.py generalizes this via YAML presets in scripts/swarm_presets/, including topology, node roles, TDM slots, aggregator port, and assertions such as all_nodes_boot, tdm_no_collision, and frame_rate_above. Snapshot and chaos variants use QEMU monitor sockets plus scripts/inject_fault.py to save/restore VM state or inject faults such as VM pauses, ring floods, corrupt CSI frames, and NVS corruption.

Proof and release scripts package evidence instead of model training. Root verify is the multi-phase trust kill switch: v1 Python proof hash, production mock/random scan, Rust workspace tests, PyO3 compile, ADR-125 HAP/MCP identity-risk invariant over scripts/ruview-sensing-server.py and scripts/c6-presence-watcher.py, published crates, npm package, Docker multi-arch manifest, and embedded HOMECORE binary. scripts/prove.sh is the public proof harness with hard gates and explicit CLAIMED-vs-MEASURED output. scripts/verify-cir-proof.sh and scripts/verify-calibration-proof.sh build Rust proof runners and compare canonical hashes unless the committed hash is still a placeholder. scripts/generate-witness-bundle.sh and scripts/witness-adr-115.sh assemble tarball directories with ADR snapshots, proof logs, Rust test logs, manifests, source hashes, optional benchmark/integration evidence, and a generated VERIFY.sh. scripts/csi-data-policy-check.sh is the repository guard that blocks tracked/staged raw CSI (*.csi.jsonl, *.csi.meta.json) and oversized JSONL unless explicitly allowlisted by scripts/csi-data-policy.allow or acknowledged via a baseline.

Publishing and release scripts move already-built artifacts. scripts/publish-huggingface.py and scripts/publish-huggingface.sh validate expected files under dist/models, retrieve a HuggingFace token from GCP Secret Manager or a passed token, create/update the model repo, upload the folder, and tag the version. scripts/release-v0.5.4.sh copies ESP32 build binaries into dist/v0.5.4-esp32, writes SHA256SUMS.txt, reports sizes, and prints exact flash/tag/GitHub release commands. scripts/run-ruforecast-benchmarks.sh is a reproducible CPU-only evidence runner: it refuses dirty worktrees unless allowed, pins the Rust toolchain, captures system metadata and SHA256s, runs Criterion benches for forecast crates, and writes an evidence directory under target/ruforecast-evidence/. scripts/…/run_zeroshot_eval.py separately compares public Chronos/TimesFM zero-shot checkpoints against BIDMC windows and baselines without fine-tuning.

The tools/ directory contains publishable or offline operational tools. tools/ruview-mcp is the @ruvnet/rvagent MCP server: src/index.ts registers canonical underscore-named tools for CSI latest, pose/count inference, registry, count training, jobs, BFLD, presence, and vitals; src/config.ts reads RUVIEW_SENSING_SERVER_URL, RUVIEW_API_TOKEN, cog binary paths, and jobs directory; it supports stdio by default and opt-in Streamable HTTP with token/origin/body-size protections. tools/ruview-cli exposes similar functionality as a JSON-printing Node CLI. tools/bfi is a bounded Linux BFI capture/decoder/quality harness for owned AP/client links, with strict PCAP/radiotap/VHT/HE support and no production inference. tools/bfi_learning prepares private RAC1 captures or public NTU-Fi/BFI datasets, trains bounded baselines, records manifests/hashes outside git, and explicitly separates unlabeled private captures from identity-labeled public datasets. tools/w1700k contains C/Python diagnostics and vendor bridge files for the W1700K integration.

The small data/clone-data.rvf file is the only covered repository data artifact read as part of this area; generated recordings, model outputs, benchmark evidence, and cloud/downloaded datasets are intentionally treated as external or under dist/, target/, /tmp, private data directories, or ignored results. templates/…/weaver.yaml and templates/registry/rust/semconv.rs.j2 are the OpenTelemetry semantic-convention generation templates for the sensing server's generated Rust semconv module.

Coupling

Risks

  • scripts/csi-data-policy-check.sh documents an existing raw-CSI incident under data/recordings/ and v2/data/recordings/. Without an explicit CSI_POLICY_BASELINE, scanning the tracked tree is expected to fail; with an overly broad baseline or allowlist, new person-data captures could be hidden instead of blocked.
  • scripts/collect-ground-truth.py permits --allow-no-csi; if used outside debugging, it writes camera keypoints without a paired CSI recording, and those files are useless or misleading for supervised CSI training.
  • scripts/calibration_lib.py only converts 2D keypoints into room-frame bearing rays. If downstream training treats keypoints_room as metric 3D coordinates, pose models will learn physically false labels.
  • scripts/ruview-sensing-server.py intentionally has bearer-token auth disabled for the dev bridge. Running it on a non-local network with scripts/c6-presence-watcher.py exposes live occupancy/vitals-style data from /tmp/ruview-last-feature.json without authentication.
  • scripts/qemu-mesh-test.sh requires root to create TAP/bridge interfaces and deletes TAPs/bridges during cleanup. Running it on a shared host with overlapping interface names such as tap0 or qemu-br0 can disrupt unrelated networking.
  • benchmarks/…/RESULTS.md records that upstream WiFlow artifacts have import bugs, checkpoint/code key mismatches, corrupted Kaggle windows, and post-training evaluation crashes. Treat any new benchmark number from benchmarks/wiflow-std/* as invalid unless it states the exact repair path, masks, split, and checkpoint provenance.
  • scripts/publish-huggingface.sh embeds the retrieved HuggingFace token into an inline Python heredoc. Although it does not intentionally print the token, shell tracing or process/log capture around this script could expose credentials; prefer scripts/publish-huggingface.py --token or environment-scoped secret handling for sensitive releases.