131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# PCIe fronthaul hot-swap harness — setup
|
||
|
||
This guide gets you from a **clean workstation + lab INI** to running `**scripts/system/pcie_hotswap_harness.py`** with a valid `**FabricDefinition**` JSON.
|
||
|
||
**Examples use `configs/default.ini`** (repo lab template). Set `**FIWI_LAB_INI**` or pass `**-c**` when your site file lives elsewhere.
|
||
|
||
**Related:** `**docs/fabric-builder.md`** (interactive `**fabric build**`), `**docs/system-test-scripts.md**` (includes `**dump_concentrator.py**` — local CPU / PCIe Wi‑Fi / `**lspci**` / DMI snapshot), `**docs/power-control-and-inventory.md**` (INI reference).
|
||
|
||
---
|
||
|
||
## 1. Software
|
||
|
||
From the FiWiControl repo root:
|
||
|
||
```bash
|
||
python3 -m pip install -e ".[dev]"
|
||
python3 -m pip install -e ".[power]" # BrainStem / Acroname on the machine that runs discovery
|
||
```
|
||
|
||
Python **3.11+**.
|
||
|
||
---
|
||
|
||
## 2. Lab INI
|
||
|
||
Use `**configs/default.ini`** as the reference layout (or your own copy). Set `**FIWI_LAB_INI**` so tools find it without repeating `**-c**`.
|
||
|
||
You need at least:
|
||
|
||
- `**[site]**` (optional name)
|
||
- `**[machine.<id>]**` — `**ipaddr**`, `**sshtype**`, `**usb**` (`**local**` vs `**remote**`), expected `**acroname**` / `**monsoon**` (same contract as `**python3 -m fiwicontrol.power --verify-inventory**`)
|
||
- `**[fabric]**` — harness merge and JSON generation:
|
||
- `**fabric_id**`
|
||
- `**concentrator**` — `**[machine.*]**` section id (or unique `**machine.name**`, `**label**`, `**machine.type**`) for **harness SSH** (the host where `**lspci`** / concentrator checks run — usually the concentrator workstation, not an RRH-only Pi).
|
||
|
||
Optional per-RRH rows for the **non-interactive** JSON generator (see §4):
|
||
|
||
```ini
|
||
[fabric.rrh.rrh-01]
|
||
acroname_port = 0
|
||
acroname_module_serial = 12345678 # optional if only one hub on USB
|
||
patch_panel_port = 101 # optional
|
||
```
|
||
|
||
Verify inventory when the bench is wired:
|
||
|
||
```bash
|
||
python3 -m fiwicontrol.power --verify-inventory -c configs/default.ini
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Produce fabric JSON (pick one path)
|
||
|
||
### Path A — Interactive (no `[fabric.rrh.*]` required)
|
||
|
||
On a host that **sees the Acroname hub over USB**, run:
|
||
|
||
```bash
|
||
python3 -m fiwicontrol.fabric build -o configs/my-fabric.json -c configs/default.ini
|
||
```
|
||
|
||
Answer prompts for hub module, ports, and `**radio_id**` per port. This writes JSON including `**discovery_fingerprint**` and `**lab_ini**`.
|
||
|
||
### Path B — Non-interactive INI → JSON
|
||
|
||
Add one `**[fabric.rrh.<radio_id>]**` section per RRH with at least `**acroname_port**`, and `**acroname_module_serial**` when multiple BrainStem modules appear on the USB bus for the host that runs `**fabric_realize.py**`. Then:
|
||
|
||
```bash
|
||
python3 scripts/system/fabric_realize.py -c configs/default.ini --json > configs/my-fabric.json
|
||
python3 scripts/system/fabric_realize.py -c configs/default.ini --json -o configs/my-fabric.json
|
||
```
|
||
|
||
(JSON is written to **stdout** unless you pass `**-o PATH`**; status lines go to **stderr**.)
|
||
|
||
Optional `**--strict-ini`** matches `**--verify-inventory**` before writing; `**--force**` continues on mismatch.
|
||
|
||
---
|
||
|
||
## 4. Check USB fingerprint vs JSON
|
||
|
||
```bash
|
||
python3 -m fiwicontrol.fabric status -f configs/my-fabric.json
|
||
```
|
||
|
||
Exit **0** only when `**READY`** (USB fingerprint matches the JSON).
|
||
|
||
---
|
||
|
||
## 5. Run the harness
|
||
|
||
From the repo root (script adds `**src**` to `**PYTHONPATH**`):
|
||
|
||
```bash
|
||
# Dry-run structure + INI merge (default lab INI if present)
|
||
python3 scripts/system/pcie_hotswap_harness.py --fabric-json configs/my-fabric.json --dry-run
|
||
|
||
# Require READY before starting
|
||
python3 scripts/system/pcie_hotswap_harness.py --fabric-json configs/my-fabric.json --strict-fabric-ready --dry-run
|
||
|
||
# Override concentrator SSH for this run (e.g. point at a different host than [fabric] / JSON)
|
||
python3 scripts/system/pcie_hotswap_harness.py --fabric-json configs/my-fabric.json --rig-ip 192.168.1.39 --dry-run
|
||
```
|
||
|
||
`**--lab-ini PATH**` — use when your JSON was built against another file and you want this INI merged at harness time.
|
||
|
||
`**--no-lab-ini**` — skip merging `**[fabric]**` from INI (JSON only).
|
||
|
||
`**--dry-run**` — the harness does **not** toggle Acroname power; it exercises SSH and concurrency. Programmable power behavior is described under **DESIGN_GAPS** in the harness module docstring.
|
||
|
||
---
|
||
|
||
## 6. SSH
|
||
|
||
Same rules as the rest of FiWiControl: non-interactive `**ssh root@<host>`**. Optional `**FIWI_SSH_CONFIG**`: `**docs/node-control-asyncio-design.md**`.
|
||
|
||
---
|
||
|
||
## 7. Where things live
|
||
|
||
|
||
| Piece | Location |
|
||
| ------------------- | ------------------------------------------------------ |
|
||
| Lab INI | `**configs/*.ini**`, `**FIWI_LAB_INI**` |
|
||
| Fabric JSON | Your `**-o**` path (e.g. `**configs/my-fabric.json**`) |
|
||
| Interactive builder | `**python3 -m fiwicontrol.fabric build**` |
|
||
| INI-only generator | `**scripts/system/fabric_realize.py**` |
|
||
| Harness | `**scripts/system/pcie_hotswap_harness.py**` |
|
||
|
||
|