8.9 KiB

Raw Blame History

Installing FiWiControl

Repository: FiWiControl (checkout directory, mixed case).
Python package / pip name: fiwicontrol (lowercase). See the Naming paragraph at the top of README.md if that split is confusing.

Requirements: Python 3.11+. For SSH automation to rigs, passwordless root@<host> — see docs/node-control-asyncio-design.md.

Bring up systems (new workstation + lab rig)

Use this order the first time you (or someone else) joins the project or replaces a machine. Replace 192.168.1.39 with your rig’s IP when needed.

Step	Where	What to do
1	Workstation	Clone this repo and `cd` into it.
2	Workstation	Python 3.11+ and an editable install: `python3 -m pip install -e ".[dev]"`, then `python3 -m pip install -e ".[power]"` if you use Acroname/Monsoon or remote power tests. Add `".[flows]"` / `".[spc]"` when you use `fiwicontrol.flows` or `fiwicontrol.spc` (see Workstation below and `docs/flows.md` / `docs/spc.md`).
3	Workstation → rig	Passwordless SSH as root: `ssh -o BatchMode=yes root@192.168.1.39 true` must exit 0 with no password prompt. On the rig, install your workstation’s public key in `/root/.ssh/authorized_keys` and ensure `sshd` allows `root` with pubkey auth.
4	Rig (e.g. Pi)	`git clone` the same repo where you will run power/discovery (often `/root/Code/FiWiControl`). Your `--remote-repo` path must match.
5	Workstation	From your clone, run `python3 -m fiwicontrol.commands` with the Pi IP and `--remote-repo` (PEP 668 / Raspberry Pi OS needs `--break-system-packages` or `FIWI_REMOTE_PIP_FLAGS`). See Remote host setup below (numbered subsections 3 and 4: install `fiwicontrol[power]` on the rig, then align `python3` with `pip`).
6	Workstation	Verify (minimal): `python3 -m pytest -q tests/test_package_layout.py`, then `FIWI_REMOTE_IP=… python3 -m pytest -q tests/test_node_control.py`, then `python3 -m pytest -q tests/test_remote_power_dependencies.py`. Default `FIWI_REMOTE_IP` is `192.168.1.39` if unset. Full tree: `python3 -m pytest tests/ -q` (expect one skipped test unless `FIWI_VERIFY_POWER_INI=1`). For INI / `--verify-inventory`, see `docs/power-control-and-inventory.md` → “Verification checklist (after install)”.

SSH user: ssh_node ( sshtype="ssh" ) always uses an explicit root@<ipaddr> (or whatever ssh_session user is set to). It does not open ssh 192.168.1.39 with your local login name, so your manual tests should use root@… as well.

After a git pull on the rig: if the Pi uses an editable pip install -e, pull there before expecting new Python code on the node.

Workstation (e.g. Fedora): recommended install

From your clone of this repo, use an editable install so python3 -m fiwicontrol…, pytest, and import fiwicontrol.* work from any working directory (use a venv if you prefer not to touch system Python):

cd ~/Code/FiWiControl
python3 -m pip install -U pip setuptools wheel
python3 -m pip install -e ".[dev]"

Add power / USB dependencies when you work with Acroname or Monsoon discovery locally:

python3 -m pip install -e ".[power]"

Or in one line:

python3 -m pip install -e ".[dev,power]"

Flows (async iperf over SSH, SciPy / Matplotlib stack) and SPC (Shewhart / Hotelling T² helpers) are separate optional extras:

python3 -m pip install -e ".[flows]"   # NumPy, SciPy, Matplotlib — see docs/flows.md
python3 -m pip install -e ".[spc]"     # NumPy, SciPy — see docs/spc.md

Or combined with dev and power:

python3 -m pip install -e ".[dev,power,flows,spc]"

Why this is the default: you avoid remembering PYTHONPATH=src, IDEs and python -m behave predictably, and it matches how pyproject.toml / pytest are meant to be used.

Without a local install (one-off)

If you have not run pip install -e ., you can still run modules from the repo root:

cd ~/Code/FiWiControl
PYTHONPATH=src python3 -m pytest tests/test_package_layout.py -q
PYTHONPATH=src python3 -m fiwicontrol.power --discovery-json

This is easy to forget after you cd elsewhere, so prefer an editable install for day-to-day work.

Summary (workstation): use editable install on your main dev box; use PYTHONPATH=src when you deliberately skip a local install.

Remote host setup

End-to-end steps for a lab rig (e.g. Raspberry Pi 5) that ssh_node and fiwicontrol.power talk to over ssh root@<ip>. Same SSH user and rules as in docs/node-control-asyncio-design.md (passwordless BatchMode=yes).

1. SSH from your workstation

ssh -o BatchMode=yes -i ~/.ssh/id_ed25519 root@192.168.1.39 true

(no output, exit 0). If this fails, fix keys and /root/.ssh/authorized_keys on the rig first.

On some Linux workstations, OpenSSH aborts before connecting with Bad owner or permissions on …/ssh_config.d/… (for example Fedora’s 20-systemd-ssh-proxy.conf). FiWiControl’s pytest session sets FIWI_SSH_CONFIG to a minimal client file under tests/fixtures/ so ssh -F skips the system /etc/ssh/ssh_config. For ad hoc runs (inventory, scripts), export FIWI_SSH_CONFIG to that same file, or to your own minimal ssh_config that does not Include the broken drop-in.

2. Repo on the remote

The Pi needs a git checkout of FiWiControl (same tree you pushed). Example for root:

# on the Pi (as root)
mkdir -p /root/Code
cd /root/Code
git clone <YOUR_FIWICONTROL_REPO_URL> FiWiControl

Use your team’s real clone URL. --remote-repo below must be that directory (e.g. /root/Code/FiWiControl).

3. Install `fiwicontrol[power]` on the remote from Fedora

Your Fedora machine must already run python3 -m fiwicontrol.power (usually pip install -e . from your local clone — see above).

Then:

cd ~/Code/FiWiControl
python3 -m fiwicontrol.commands 192.168.1.39 --remote-repo /root/Code/FiWiControl --break-system-packages

Raspberry Pi OS / Debian (PEP 668): system Python blocks pip install without --break-system-packages. Prefer the --break-system-packages flag above.

Do not pass a separate token after --pip-flags if it starts with -- (argparse will treat it as another option). Use either:

--break-system-packages, or
--pip-flags=--break-system-packages (equals form), or
export FIWI_REMOTE_PIP_FLAGS='--break-system-packages' and omit --pip-flags.

Wrapper: scripts/setup_pi_power.sh sets PYTHONPATH=src on Fedora if needed, then runs python3 -m fiwicontrol.commands (--setup-remote-style args) using FIWI_REMOTE_IP and FIWI_REMOTE_REPO:

cd ~/Code/FiWiControl
chmod +x scripts/setup_pi_power.sh   # once
export FIWI_REMOTE_IP=192.168.1.39
export FIWI_REMOTE_REPO=/root/Code/FiWiControl
export FIWI_REMOTE_PIP_FLAGS='--break-system-packages'
./scripts/setup_pi_power.sh

(You can extend the script or pass -- args if you add --break-system-packages to the script later.)

4. Python on the remote (one interpreter for pip and for SSH)

If pip show fiwicontrol reports Location: …/python3.11/… but plain python3 on the rig is a different version, imports over SSH will fail even though the package is installed. Install and run with the same binary, or on Fedora set:

export FIWI_REMOTE_PYTHON=python3.11   # or full path, e.g. /usr/bin/python3.11

That variable is read by discover_devices_remote_async, tests/test_remote_power_dependencies.py, and python3 -m fiwicontrol.commands … --remote-python … (remote setup).

5. Verify after install

Quick remote sanity (imports + python3 -m fiwicontrol.power --discovery-json over SSH; needs FIWI_REMOTE_IP if not 192.168.1.39):

python3 -m pytest -q tests/test_remote_power_dependencies.py

Full checklist for a new machine (local discovery, ssh root@…, remote fiwicontrol, INI editing, --list-power-devices, --verify-inventory, optional pytest): docs/power-control-and-inventory.md → “Verification checklist (after install)”.

INI layout ([site], [node.*], [inventory.host.*], acroname / monsoon_count): same doc → “Lab INI file reference”.

Quick import check

python3 -c "import fiwicontrol.commands, fiwicontrol.power; print('ok')"

With only [dev] installed, fiwicontrol.power still imports; hardware discovery needs [power] ( brainstem, pyserial ).

8.9 KiB Raw Blame History Unescape Escape