65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# @ruv/rvcsi
|
|
|
|
Node.js bindings (napi-rs) for **rvCSI** — the edge RF sensing runtime: ingest
|
|
WiFi CSI from files / Nexmon dumps, validate and normalize it, run reusable DSP,
|
|
emit typed presence / motion / quality / anomaly events, and export temporal
|
|
embeddings to an RF-memory store. See [ADR-095](../../../docs/adr/ADR-095-rvcsi-edge-rf-sensing-platform.md)
|
|
and [ADR-096](../../../docs/adr/ADR-096-rvcsi-ffi-crate-layout.md).
|
|
|
|
> This package wraps the Rust crates in `v2/crates/rvcsi-*`. The Rust side does
|
|
> all the work (parsing, validation, DSP, events, embeddings); this is a thin,
|
|
> safe JS surface — nothing crosses the boundary except validated/normalized
|
|
> objects (delivered as JSON the SDK parses for you).
|
|
|
|
## Build
|
|
|
|
The native addon is produced from the `rvcsi-node` Rust crate:
|
|
|
|
```bash
|
|
# from v2/crates/rvcsi-node
|
|
npm install # installs @napi-rs/cli
|
|
npm run build # -> rvcsi-node.<triple>.node + binding.js + binding.d.ts
|
|
```
|
|
|
|
(`cargo build -p rvcsi-node` also compiles the addon as a `cdylib`; `napi build`
|
|
additionally emits the platform loader and `.d.ts`.)
|
|
|
|
## Usage
|
|
|
|
```js
|
|
const { RvCsi, inspectCaptureFile, eventsFromCaptureFile, nexmonDecodeRecords } = require('@ruv/rvcsi');
|
|
|
|
// One-shot: summarize a capture
|
|
const summary = inspectCaptureFile('lab.rvcsi');
|
|
console.log(summary.frame_count, summary.channels, summary.mean_quality);
|
|
|
|
// One-shot: replay a capture into events
|
|
for (const e of eventsFromCaptureFile('lab.rvcsi')) {
|
|
console.log(e.kind, e.timestamp_ns, e.confidence);
|
|
}
|
|
|
|
// Streaming
|
|
const rt = RvCsi.openCaptureFile('lab.rvcsi');
|
|
let frame;
|
|
while ((frame = rt.nextCleanFrame()) !== null) {
|
|
// frame.validation is 'Accepted' | 'Degraded' | 'Recovered' — never 'Pending'/'Rejected'
|
|
if (frame.quality_score > 0.5) { /* ... */ }
|
|
}
|
|
const events = rt.drainEvents();
|
|
console.log(rt.health());
|
|
|
|
// Decode raw Nexmon records (the napi-c shim format) straight from a Buffer
|
|
const fs = require('fs');
|
|
const frames = nexmonDecodeRecords(fs.readFileSync('nexmon.bin'), 'wlan0', 1);
|
|
```
|
|
|
|
TypeScript types ship in `index.d.ts` (`CsiFrame`, `CsiWindow`, `CsiEvent`,
|
|
`SourceHealth`, `CaptureSummary`, `ValidationStatus`, `CsiEventKind`, ...).
|
|
|
|
## What's here vs. not (yet)
|
|
|
|
Implemented: file/replay + Nexmon sources, the validation pipeline, the DSP
|
|
stages, window aggregation + the event state machines, RuVector-style RF-memory
|
|
export. Not yet wired into this addon: live radio capture, the WebSocket daemon,
|
|
and the MCP tool server — those come with `rvcsi-daemon` / `rvcsi-mcp`.
|