7.5 KiB
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 (see Workstation below). |
| 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 --setup-remote (PEP 668 / Raspberry Pi OS needs --break-system-packages or FIWI_REMOTE_PIP_FLAGS). See Remote host setup §3–§4 below. |
| 6 | Workstation | Verify (minimal): pytest -q tests/test_package_layout.py, then FIWI_REMOTE_IP=… pytest -q tests/test_node_control.py, then pytest -q tests/test_remote_power_dependencies.py. Default FIWI_REMOTE_IP is 192.168.1.39 if unset. For a full post-install checklist (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]"
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.
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.power --setup-remote 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), orexport 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 --setup-remote 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.power --setup-remote --remote-python ….
5. Verify after install
Quick remote sanity (imports + python -m fiwicontrol.power --discovery-json over SSH; needs FIWI_REMOTE_IP if not 192.168.1.39):
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 ).