# 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 **`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):

```bash
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:

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

Or in one line:

```bash
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:

```bash
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

```bash
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`**:

```bash
# 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:

```bash
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`**:

```bash
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:

```bash
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`**):

```bash
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

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

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