FiWiControl/README.md

FiWiControl

Tools, libraries and statistical software for automating, managing, monitoring and testing Umber Fi‑Wi networks.

Naming: The Git repository and checkout directory are FiWiControl (mixed case). The Python distribution and import package are fiwicontrol (all lowercase, PEP 8) — same project, different casing rules for Git vs Python. Use fiwicontrol for pip install / import, not FiWiControl.

This repository ships that distribution (fiwicontrol on PyPI / pip) with import root fiwicontrol:

1. fiwicontrol.commands — run commands on remote rigs via OpenSSH or ush (Command, CommandManager, ssh_node). Remote Pi bootstrap: python3 -m fiwicontrol.commands <ip> --remote-repo … (see docs/install.md). Must not import fiwicontrol.power.
2. fiwicontrol.lab — USB discovery (Acroname / Monsoon) and configs/*.ini inventory load + verify. Imports fiwicontrol.commands for SSH discovery only.
3. fiwicontrol.power — Power (.on() / .off() / .voltage() / …) via AcronamePower and MonsoonPower, plus a small CLI (--discovery-json, --list-power-devices, --verify-inventory with -c). Re-exports fiwicontrol.lab discovery/inventory for compatibility. May import fiwicontrol.commands and fiwicontrol.lab; the reverse is forbidden.

Near-term focus: PCIe hot-swap testing

A first concrete goal for this stack is to support PCIe hot-swap (hot-plug) testing in the lab: controlled remove / restore of the link, predictable enumeration and driver behavior, and repeatable runs across builds and rigs.

That work fails if the bench is informal—wrong port, wrong power path, or no shared picture of what was connected when. FiWiControl targets that gap by combining documented inventory (INI + --verify-inventory), remote automation (ssh_node, python3 -m fiwicontrol.commands to bring up rigs), and programmable power / USB paths (fiwicontrol.power) so sequences are scripted and checkable before the PCIe harness runs. Longer term, SPC (below) is meant for many hot-plug cycles—spotting drift in failure rates or side metrics—not only general Fi‑Wi bring-up.

Immediate roadmap: ESP32 integration for telemetry (and related rig control)—sensors, counters, and health alongside PCIe and Fi‑Wi runs—and expanded ush orchestration alongside OpenSSH: not only the ush transport already wired through ssh_node, but first-class tooling for benches that standardize on ush. None of that is finished yet beyond today’s ssh_node ush path.

Statistical process control (planned)

The project is intended to grow statistical process control (SPC) support—for example Hotelling-style multivariate monitoring and Shewhart control charts—for lab and field metrics tied to Fi‑Wi rigs (including high-volume PCIe hot-swap campaigns where you need to know if the process is still in control). That code is not in the tree yet; today’s packages focus on automation, inventory, and power/USB control as described above.

Layout

FiWiControl/
├── LICENSE
├── README.md
├── pyproject.toml
├── docs/
│   ├── install.md
│   ├── node-control-asyncio-design.md
│   └── power-control-and-inventory.md
├── src/
│   └── fiwicontrol/
│       ├── commands/
│       │   ├── __init__.py
│       │   ├── __main__.py
│       │   ├── node_control.py
│       │   └── remote_setup.py
│       ├── lab/
│       │   ├── __init__.py
│       │   ├── discovery.py
│       │   ├── inventory_config.py
│       │   └── inventory_verify.py
│       └── power/
│           ├── __init__.py
│           ├── __main__.py
│           ├── acroname.py
│           ├── control.py
│           └── monsoon.py
└── tests/

Requirements

• Python 3.11+
• For sshtype="ssh": passwordless SSH to root@<host> (non-interactive ssh; see docs/node-control-asyncio-design.md).

Install

First-time / new machine: follow docs/install.md → “Bring up systems (new workstation + lab rig)”, then the Workstation and Remote host setup sections.

Full guide (workstation, remote host setup for the Pi, pip install -e, PYTHONPATH=src, scripts/setup_pi_power.sh): docs/install.md.

Minimal editable install from the repo root:

cd ~/Code/FiWiControl
python3 -m pip install -e ".[dev]"
# optional: power / USB discovery (Acroname, Monsoon)
python3 -m pip install -e ".[power]"

Imports:

from fiwicontrol.commands import ssh_node, Command, CommandManager

Tests

After install, use the ordered verification checklist and INI reference in docs/power-control-and-inventory.md (sections “Verification checklist (after install)” and “Lab INI file reference”).

Commands, example pytest output, and unittest entry points for node_control: docs/node-control-asyncio-design.md → section “Running tests” (top-level ## heading near the top of the file).

Whole suite (from repo root; pyproject.toml adds src to PYTHONPATH for pytest):

cd ~/Code/FiWiControl
python3 -m pytest tests/ -q

Example summary when the opt-in live INI test is not enabled ( FIWI_VERIFY_POWER_INI unset — one test skipped):

.....s......................                                                                                          [100%]
27 passed, 1 skipped in 18.20s

Run a single test by id (replace with a name from python3 -m pytest tests/<file>.py --collect-only -q):

python3 -m pytest tests/test_package_layout.py::test_import_subpackages -v

Layout / import smoke (no network):

cd ~/Code/FiWiControl
python3 -m pytest tests/test_package_layout.py -q

Remote integration (needs FIWI_REMOTE_IP and key auth):

cd ~/Code/FiWiControl
FIWI_REMOTE_IP=192.168.1.39 python3 -m pytest tests/test_node_control.py -q

Power / USB inventory (needs brainstem and pyserial, e.g. pip install -e ".[power]"): see docs/power-control-and-inventory.md. Lab layout is configs/default.ini by default (override with -c). configs/clubhouse.ini is an alternate example file.

cd ~/Code/FiWiControl
python3 -m pip install -e ".[power]"
python3 -m fiwicontrol.power --verify-inventory
# or: python3 -m fiwicontrol.power -c configs/clubhouse.ini --verify-inventory

The same check from pytest (set FIWI_VERIFY_POWER_INI=1 or pytest skips the live INI test):

FIWI_VERIFY_POWER_INI=1 python3 -m pytest -q tests/test_inventory_verify_live.py

Remote package sanity (imports + python3 -m fiwicontrol.power --discovery-json) for the host in FIWI_REMOTE_IP (default 192.168.1.39):

python3 -m pytest -q tests/test_remote_power_dependencies.py

Example when SSH and the rig are configured (-v; line spacing may vary):

tests/test_remote_power_dependencies.py::TestRemotePowerDependencies::test_remote_imports_fiwicontrol_power_brainstem_serial PASSED [ 50%]
tests/test_remote_power_dependencies.py::TestRemotePowerDependencies::test_remote_power_module_discovery_json PASSED [100%]

============================== 2 passed in 0.65s ==============================

Remote (Gitea)

git remote add origin "https://git.umbernetworks.com/rjmcmahon/FiWiControl.git"
git push -u origin main

Use a Gitea personal access token as the HTTPS password if prompted.