7.8 KiB

Raw Permalink Blame History

FiWiControl — system architecture

This document is the top-level design for the FiWiControl Python distribution (fiwicontrol). It ties together packages, data artifacts, runtime contexts, and how this repo supports the Umber Fi‑Wi system described in the architecture spec (read-only reference: html/Fi-Wi-L4S.html in this repository — open in a browser; do not treat this Markdown file as a substitute for the full spec).

Related: docs/fdir.md (fault detection, isolation, recovery), README.md (package list), docs/install.md (install, security, environment variables).

1. Purpose and scope

1.1 What FiWiControl is

FiWiControl provides concentrator- and lab-oriented automation: remote command execution (ssh / ush), USB power and discovery (Acroname / Monsoon), lab INI inventory, fabric definitions (RRH ↔ USB port bindings + fingerprint), fronthaul and telemetry models, optional iperf flows and SPC, and system harness scripts under scripts/system/.

It does not implement the Fi‑Wi datapath, Wi‑Fi MAC, or L4S queueing algorithms. Those belong to the system architecture in html/Fi-Wi-L4S.html (e.g. dual-loop control, queue structure, dynamic point selection, PCIe fronthaul). FiWiControl aligns lab and deployment practice with that architecture by making inventory, power paths, and fronthaul physical state observable and scriptable.

1.2 What “production ready” means here

Production ready for this repo means: clear contracts, predictable failure modes, documented exit codes and logs (see docs/fdir.md), tests for import and core logic, and explicit non-goals (e.g. not a medical or life-safety product — README.md). It does not imply formal certification of the Fi‑Wi network product; that remains a broader system concern.

2. Alignment with `html/Fi-Wi-L4S.html` (conceptual map)

The HTML spec covers motivation, dual-loop control, queues, RRH redundancy, dynamic point selection, power/thermal considerations, and PCIe fronthaul (including PCIe hot swap). FiWiControl maps to those themes only on the control-plane / operations side:

Spec theme (HTML)	FiWiControl role
Concentrator vs RRH split	`fiwicontrol.fabric`: concentrator SSH target + RRH list; `fiwicontrol.radio`: logical RRH aggregate; `fiwicontrol.fronthaul`: link identity.
Fronthaul (PCIe)	`telemetry.fronthaul`, `scripts/system/pcie_hotswap_harness.py`, `docs/pcie-hotswap-setup.md` — lab exercise and metadata, not wire-protocol implementation.
Inventory / “what is connected”	`fiwicontrol.lab`, `fiwicontrol.power`, *`[fabric]` / `[fabric.rrh.]` INI, `FabricDefinition` JSON, `discovery_fingerprint`**.
Remote operation of rigs	`fiwicontrol.commands` (`ssh_node`, `Command`, `CommandManager`).
Measurement / campaigns	`fiwicontrol.flows`, `fiwicontrol.spc`, harness scripts.

If a capability appears in the HTML spec but not in this table, assume it is out of scope for FiWiControl until a package or script explicitly addresses it.

3. Layered architecture

┌─────────────────────────────────────────────────────────────┐
│  scripts/system/*  (harnesses, CLIs — not default pytest)    │
└───────────────────────────┬─────────────────────────────────┘
                            │ import
┌───────────────────────────▼─────────────────────────────────┐
│  fiwicontrol.fabric | .power | .commands | .flows | .spc …   │
└───────────────────────────┬─────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   fiwicontrol.lab    fiwicontrol.radio   fiwicontrol.telemetry
   (INI, discovery)   (RadioHead,         (schemas, e.g.
                       FrontHaul)          FrontHaulTelemetry)
        │                   │
        └─────────┬─────────┘
                  ▼
          fiwicontrol.commands  (SSH / ush — fiwicontrol.power may use for remote discovery)

3.1 Dependency rules (hard)

fiwicontrol.commands must not import fiwicontrol.power (breaks layering).
fiwicontrol.lab may use commands only for SSH-assisted discovery where needed.
fiwicontrol.power may import commands and lab; the reverse is forbidden.

These rules keep optional hardware stacks (BrainStem, etc.) from becoming core dependencies of the command layer.

4. Persistent artifacts

Artifact	Typical location	Role
Lab INI	`configs/*.ini`, `FIWI_LAB_INI`	Machines, USB expectations, `[fabric]` / `[fabric.rrh.*]`.
Fabric JSON	Operator-chosen path (e.g. `configs/my-fabric.json`)	`FabricDefinition`: `rrhs`, `discovery_fingerprint`, concentrator fields.
Patch panel map	`*_panel.json` beside INI or `--patch-panel-json`	BDF → label for concentrator reports.

Merge rule: Harnesses and APIs often load JSON first, then merge the same lab INI so operators can override concentrator or per-RRH fields without editing JSON (ini_merge).

5. Runtime contexts

Developer workstation — editable install, pytest, fabric build, fabric_realize.py.
Umber concentrator — intended deployment host for automation aligned with the spec.
Lab rig (e.g. Pi) — SSH target; may run remote discovery for usb=remote rows.

Passwordless root@<host> SSH (or equivalent) is assumed for automation; see docs/node-control-asyncio-design.md.

6. Observability and FDIR

Structured fabric checks: Fabric.binding_cache_status, python3 -m fiwicontrol.fabric status, Fabric.realize(strict=…).
Logging: FDIR-related messages use the prefix [FiWi-FDIR] (see fiwicontrol.fabric.fdir and docs/fdir.md).
CLI exit codes: fabric_realize.py documents codes in --help epilog; full table in docs/fdir.md.

7. Documentation index

Document	Contents
`docs/fdir.md`	Fault detection, isolation, recovery; exit codes; operator responses.
`docs/install.md`	Install, environment variables, security boundaries.
`docs/fabric-builder.md`	Interactive bind → JSON.
`docs/power-control-and-inventory.md`	INI reference, verification.
`docs/node-control-asyncio-design.md`	`ssh_node`, asyncio, timeouts.
`docs/system-test-scripts.md`	Harness patterns, `fabric_realize` summary.
`docs/pcie-hotswap-setup.md`	PCIe harness setup.
`docs/flows.md`, `docs/spc.md`	Optional packages.
`html/Fi-Wi-L4S.html`	Fi‑Wi system architecture (authoritative product/spec narrative).

8. Revision

When packages or scripts gain new failure modes or exit codes, update docs/fdir.md and this file’s §6 / §7 as needed. When the Fi‑Wi product architecture changes, update html/Fi-Wi-L4S.html through your normal spec process (FiWiControl docs only reference it, per project policy).

7.8 KiB Raw Permalink Blame History Unescape Escape