FiWiControl/README.md

FiWiControl

Tools and libraries for managing 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, with asyncio streaming, timeouts, repeats (Command), and a small registry (CommandManager). Implementation: src/fiwicontrol/commands/node_control.py.
2. fiwicontrol.power — discovery plus Power (.on() / .off() / .voltage() / .current() / .watts()) delegating to AcronamePower and MonsoonPower. May import fiwicontrol.commands; the reverse is forbidden.

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
│       │   └── node_control.py
│       └── power/
│           └── __init__.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).

Layout / import smoke (no network):

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

Remote integration (needs FIWI_REMOTE_IP and key auth):

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

Power / USB inventory (needs brainstem and pyserial, e.g. pip install -e ".[power]"): see docs/power-control-and-inventory.md for what must be installed on the remote (e.g. Pi) and how discovery over SSH works. configs/clubhouse.ini lists expected Acroname hubs as Stem:ports (downstream USB count) and monsoon_count per [inventory.host.*]. Compare live discovery to the INI (local host + SSH to the Pi for remote rows):

cd ~/Code/FiWiControl
python -m pip install -e ".[power]"
python -m fiwicontrol.power --verify-inventory configs/clubhouse.ini

The same check from pytest (skipped unless enabled):

FIWI_VERIFY_POWER_INI=1 pytest -q tests/test_inventory_verify_live.py

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

pytest -q tests/test_remote_power_dependencies.py

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.