From cf166350f58ef6e35dd8579776d8e98d2b9ff1eb Mon Sep 17 00:00:00 2001
From: Robert McMahon <rjmcmahon@rjmcmahon.com>
Date: Fri, 10 Apr 2026 18:26:19 -0700
Subject: [PATCH] docs: example discovery JSON for Pi (Acroname + sysfs
 Monsoon)

Made-with: Cursor
---
 docs/power-control-and-inventory.md | 79 +++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/docs/power-control-and-inventory.md b/docs/power-control-and-inventory.md
index cc4b21a..f6ceb1b 100644
--- a/docs/power-control-and-inventory.md
+++ b/docs/power-control-and-inventory.md
@@ -113,6 +113,85 @@ The second command should print JSON with top-level keys **`acroname`** and **`m
 
 **Monsoon note:** the HVPM often shows up in **`lsusb`** as **`2ab9:0001`** but **does not create a `/dev/ttyACM*`** (upstream tools use **libusb**, not a serial TTY). FiWiControl counts Monsoon for discovery/inventory using **pyserial when a TTY exists**, and on **Linux** also matches the same VID/PID under **`/sys/bus/usb/devices`**, so **`monsoon`** can still reflect **`lsusb`** even when **`list_ports`** is empty.
 
+### Example: healthy discovery on a Raspberry Pi (lab rig)
+
+Run on the **Pi** (same machine where USB is cabled). **`lsusb`** should show the Monsoon line; **`--discovery-json`** should still list **`monsoon`** even without **`ttyACM`**:
+
+```text
+$ lsusb | grep -i 2ab9
+Bus 005 Device 002: ID 2ab9:0001 Monsoon Solutions Inc. Mobile Device Power Monitor
+```
+
+```bash
+python3 -m fiwicontrol.power --discovery-json
+```
+
+Example output (shape is what matters; **serial numbers** and **counts** will match **your** hardware):
+
+```json
+{
+  "acroname": [
+    {
+      "transport": "USB",
+      "serial_number": 882238458,
+      "module_address": 0,
+      "model_id": 19,
+      "model_name": "USBHub3p",
+      "model_description": "Programmable 8+1 port USB 3.0 Hub: Default module address is 6.",
+      "stem_class": "USBHub3p",
+      "downstream_usb_ports": 8,
+      "hub_port_entities": 12
+    },
+    {
+      "transport": "USB",
+      "serial_number": 3346268699,
+      "module_address": 0,
+      "model_id": 17,
+      "model_name": "USBHub2x4",
+      "model_description": "Programmable 4 port USB Hub: Default module address is 6.",
+      "stem_class": "USBHub2x4",
+      "downstream_usb_ports": 4,
+      "hub_port_entities": 6
+    },
+    {
+      "transport": "USB",
+      "serial_number": 1960815024,
+      "module_address": 0,
+      "model_id": 19,
+      "model_name": "USBHub3p",
+      "model_description": "Programmable 8+1 port USB 3.0 Hub: Default module address is 6.",
+      "stem_class": "USBHub3p",
+      "downstream_usb_ports": 8,
+      "hub_port_entities": 12
+    }
+  ],
+  "monsoon": [
+    {
+      "device": "/dev/bus/usb/5/2",
+      "serial_number": "35004",
+      "vid": 10937,
+      "pid": 1,
+      "manufacturer": null,
+      "product": null,
+      "hwid": "sysfs:5-2"
+    }
+  ]
+}
+```
+
+**How to read this:**
+
+| Field / pattern | Meaning |
+|-----------------|--------|
+| **`acroname`** | One object per **BrainStem module** (hubs/stems). Use **`stem_class`** + **`downstream_usb_ports`** for **`acroname = …`** in the INI (**`Stem:ports`** multiset). |
+| **`monsoon`** | One object per **Monsoon-class** USB device FiWiControl detected. **`device`** may be **`/dev/bus/usb/<bus>/<dev>`** (Linux sysfs path) when there is **no** serial TTY — that is **normal** for HVPM. |
+| **`vid`: `10937`** | Decimal for **`0x2AB9`** (Monsoon vendor ID). **`pid`: `1`** is **`0x0001`**. |
+| **`hwid`: `sysfs:5-2`** | Sysfs device directory name under **`/sys/bus/usb/devices/`** (debugging / correlation with **`lsusb`** bus topology). |
+| **Empty `monsoon`** with Monsoon in **`lsusb`** | Old FiWiControl build (no sysfs fallback), or Monsoon not actually on **this** host’s USB tree. |
+| **`acroname_error` / `monsoon_error`** | Missing **`brainstem`** / **`pyserial`**, or enumeration failure — read the string value. |
+
+Use this JSON to set **`[inventory.host.*]`** **`acroname`** and **`monsoon_count`**, then run **`--verify-inventory`**.
+
 ---
 
 ## Verification checklist (after install)