Skip to content

docs(tutorials): Pi 5 + Hailo cluster rvcsi tutorial#546

Merged
ruvnet merged 2 commits into
mainfrom
docs/pi5-rvcsi-tutorial
May 17, 2026
Merged

docs(tutorials): Pi 5 + Hailo cluster rvcsi tutorial#546
ruvnet merged 2 commits into
mainfrom
docs/pi5-rvcsi-tutorial

Conversation

@ruvnet
Copy link
Copy Markdown
Owner

@ruvnet ruvnet commented May 13, 2026

Summary

Adds docs/tutorials/pi5-cluster-cognitive-rf-observer.md — a
field-tested walkthrough for building a 4-node Raspberry Pi 5 + 2×
Hailo-8 multistatic Wi-Fi CSI cognitive RF observer using rvcsi.

Built against the v0-appliance v0.5.0-cognitive-rf-observer milestone:

  • 4× Pi 5 + 2× Hailo-8 → CSI → 128-d embeddings on-device → cosine
    k-means w/ warm-start → 2nd-order Markov chain → SQLite brain corpus
  • 446k+ fingerprints observed in development
  • 16 stable RF states (IDs preserved across hourly re-clustering)
  • 39% top-1 ceiling on 2nd-order next-state prediction (1.06× gain
    over 1st-order, 16× chance baseline)
  • 34 cog-query subcommands, 4 JSON modes
  • 12-category brain corpus, 15 expected services across 4 hosts

What's in the tutorial

  1. Prerequisites + BOM (~$580 parts + workstation)
  2. Architecture overview (ASCII topology diagram)
  3. Per-node firmware: native ARM nexmon_csi build (cross-compile is a
    documented dead end)
  4. Per-node services (per-host topology table)
  5. Workstation pipeline (3 daemons, 7 timers, brain HTTP service)
  6. Calibration: walk → cluster → warm-start IDs → Markov skill
  7. cog-query CLI: 34 subcommands cheat-sheet
  8. What you can measure
  9. Troubleshooting table (painful lessons captured concretely)
  10. Next steps

Companion gist

Detailed cookbook with every unit file, command, config:
https://gist.github.com/ruvnet/88e7b053c41cb4f4af7a7ec4af873017

Style fit

Mirrors existing docs/tutorials/cognitum-seed-pretraining.md format.

Test plan

  • Render check on GitHub (tables, ASCII diagram alignment)
  • Cross-links resolve (gist, v0-appliance ADR-206, nexmon_csi, hailo.ai)
  • Spot-check recipe steps on a fresh Pi 5

🤖 Generated with claude-flow

ruvnet added 2 commits May 13, 2026 08:43
Field-tested walkthrough for building a 4-node Raspberry Pi 5 + 2×
Hailo-8 multistatic Wi-Fi CSI cognitive RF observer using rvcsi. Built
against the v0-appliance v0.5.0-cognitive-rf-observer milestone — 446k+
observed fingerprints, 16 stable RF states, 2nd-order Markov running at
39% top-1 ceiling (1.06× over 1st-order, 16× chance baseline).

Covers:
  - Pi 5 + Hailo hardware bring-up (BOM ~$580 + workstation)
  - nexmon_csi native ARM build recipe (cross-compile is a dead end)
  - Per-node services + per-host topology (15 expected services across 4 hosts)
  - Workstation pipeline: 3 daemons + 7 timers, brain HTTP + SQLite
  - 12 brain categories from spatial-vitals through rfmem-fleet
  - cog-query CLI: 34 subcommands, 4 JSON modes, --post for 2
  - Calibration recipe: walk → cluster → warm-start IDs → Markov chain
  - 13-axis anomaly detector w/ composite info score (1.0–8.0)
  - Fleet-health triad: check-drift + replica-status + fleet-status
  - Troubleshooting table for the painful lessons (clock skew, cp -r footgun,
    self-loop dominance in Markov argmax, etc.)

Pairs with a detailed cookbook gist (linked from intro + steps 3, 4,
and the Reference section):
https://gist.github.com/ruvnet/88e7b053c41cb4f4af7a7ec4af873017

Co-Authored-By: claude-flow <ruv@ruv.net>
Two amendments per ADR-207's "naming defect — fix immediately regardless"
action item:

1. Intro callout: when the tutorial was first written, "rvcsi" was a
   naming convention only (no upstream library dep). As of 2026-05-13
   the v0-appliance accepted ADR-207 Option D and shipped a Rust
   binary built on the real rvcsi-runtime. Both stacks can coexist on
   a mixed cluster during cutover.

2. Per-node services section: explicit note that cog-csi-emitter +
   cog-csi-adapter + cog-rvcsi-stream are being consolidated into one
   cog-rvcsi-pi Rust binary, with deploy + rollback commands and
   scope (per-Pi cutover, mixed clusters OK).

The tutorial's overall instructions remain correct for both pre- and
post-cutover deployments — fleet-status, the operator surface, and
the architectural model are unchanged.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet ruvnet merged commit b2fe452 into main May 17, 2026
8 of 18 checks passed
@ruvnet ruvnet deleted the docs/pi5-rvcsi-tutorial branch May 17, 2026 21:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants