Files
ARIA 6e87dcf862 fix: address PR review — flash state race, error paths, test robustness, nits
- server.py: claim the flash (state=bootloader) before spawning the task so
  the concurrent-request guard is effective immediately; guard the bundled
  image existence in the flash endpoint; single device.info() call per
  endpoint; 400 for refused flashes (409 stays for already-running);
  remove stale nvcurve-wireview-fw-*.bin temp files at startup
- wireview_firmware.py: drain stderr in its own reader thread (a full pipe
  buffer would have hung the flash until timeout); chunked stdout reads
  instead of per-character read(2); BuildStruct field checks in dataclass
  order
- wireview.py: document the intentional 0xF1 overlap between CMD_BOOTLOADER
  and SCREEN_RESUME_UPDATES (different command namespaces)
- tests: check() now fails loudly under pytest (optional import, standalone
  runs unaffected); explicit reader-thread sync in test_enter_bootloader;
  less brittle flash-progress assertion; self-documenting checksum
  corruption in test_hex_parser
- frontend: refreshFirmware in useCallback + effect deps; NaN% guard on
  flash.progress; explicit clear/keep masks in handleClear; WS firmware
  message reuses WireViewFlashProgress via Pick
- docs: clarify that the dfu-util :leave modifier is what makes the device
  exit the bootloader and reboot; document the 400 vs 409 API contract;
  README now mentions per-pin readings, pin-imbalance gauge and fault
  clearing
2026-10-05 20:40:05 +02:00

145 lines
8.8 KiB
Markdown

# WireView Pro II Setup
NVCurve reads the [Thermal Grizzly WireView Pro II](https://www.thermal-grizzly.com/en/wireview-pro-ii-gpu/s-tg-wv-p2) (12 VHPWR connector monitor) directly over its USB CDC/ACM serial port — **no exporter, no GUI, no kernel module required**.
Before the first use, the host needs a one-time setup: a udev rule so the serial port is accessible under a stable name and left alone by other tools. After that, NVCurve auto-detects the device over USB — the WireView tab appears while the device is connected and disappears when it is unplugged.
## Why a one-time setup is needed
The WireView is an STM32 CDC/ACM virtual serial port (VID `0483`, PID `5740`). Out of the box, Linux:
- creates the port as `root:uucp 0660` with no stable device name, and
- lets **ModemManager** probe every new CDC-ACM port with AT/QCDM commands for up to ~30 s after each plug — it holds the port open and sends bytes the device does not expect.
The udev rule below fixes both: the node becomes `root:dialout 0660`, a stable `/dev/wireview-pro2` symlink is created, and ModemManager is told to ignore the device.
## 1. Install the udev rule
```sh
sudo tee /etc/udev/rules.d/99-wireview.rules > /dev/null <<'EOF'
# WireView Pro II udev rules
#
# Same access policy as wireview-hwmon's 99-wireview-hwmon.rules: the node is
# 0660 root:dialout, and the user logged in at the local seat gets an ACL via
# uaccess. systemd applies that tag on hotplug from 73-seat-late.rules, which
# runs before this 99- file and so never sees it, so each rule also runs the
# uaccess builtin itself. The tag is still needed: logind uses it to move the
# ACL to the new active session on a user switch.
ACTION=="remove", GOTO="wireview_end"
# Normal operation (STM32 CDC/ACM virtual serial port)
SUBSYSTEM=="tty", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", GROUP="dialout", MODE="0660", TAG+="uaccess", RUN{builtin}+="uaccess", SYMLINK+="wireview-pro2"
# Keep ModemManager away: it probes every new CDC-ACM port with AT and QCDM
# commands for about half a minute, holding the port and sending the device
# bytes it does not expect.
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0483", ATTR{idProduct}=="5740", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="tty", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", ENV{ID_MM_PORT_IGNORE}="1"
# DFU bootloader mode (firmware update)
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0483", ATTR{idProduct}=="df11", GROUP="dialout", MODE="0660", TAG+="uaccess", RUN{builtin}+="uaccess"
LABEL="wireview_end"
EOF
```
> [!WARNING]
> The rule sets `GROUP="dialout"`. If the `dialout` group does not exist on your distro, udev silently ignores the rule (the node stays `root:uucp`). Create it first: `sudo groupadd dialout`.
Then reload the rules and apply them to an already-plugged device (a reload alone only affects future hotplugs):
```sh
sudo udevadm control --reload-rules
sudo udevadm trigger
```
## 2. Port access
- **NVCurve web server (systemd):** runs as root, so it can open the port as soon as the rule is in place — nothing else to do.
- **CLI as a regular user:** add your user to the `dialout` group, then log out/in:
```sh
sudo usermod -aG dialout $USER
```
A running process only picks up new groups after a re-login; `sg dialout -c 'nvcurve ...'` works for a one-off.
## 3. Verify
```sh
lsusb | grep 0483 # 0483:5740 present
ls -l /dev/wireview-pro2 # -> /dev/ttyACM0
```
With the device plugged in, start (or restart) the NVCurve server. The **WireView** tab appears in the web UI and `GET /api/wireview` returns the device info and live samples. The tab disappears when the device is unplugged and reappears on re-plug — no restart needed.
## Firmware check and update
The WireView tab has a **Firmware** card that compares the device's firmware (version + build date, read from the device) against the image bundled with NVCurve (`nvcurve/firmware/TG-WV-PRO2-FW.hex`, v05, build `20260902_0741`) and can flash it over USB DFU.
Comparison rules (same as the official client and wireview-linux):
- the image must match the device's product — the Noctua Edition (product `06`) runs the Pro II (`05`) firmware, so a Pro II image is accepted for it;
- an image without a build date of 2026-09-02 or later is refused for a Noctua Edition (that build added Noctua support);
- version first, then build date: a **downgrade** or an **identical** build is refused unless you explicitly confirm it ("Flash anyway"); a newer image offers a normal "Update firmware" button.
Flashing requires:
- the **serial transport** (in hwmon mode the `wireviewd` daemon owns the port, so the card shows a hint instead of a button);
- the `dfu-util` package (`sudo apt install dfu-util` / `sudo dnf install dfu-util` / …) — the card shows a warning when it is missing;
- the udev rule above, which already covers the DFU bootloader (`0483:df11`).
The flash procedure: NVCurve sends the bootloader command over the serial port, the device reboots into its STM32 DFU bootloader (`0483:df11`), the bundled Intel-HEX image is flattened to a raw binary (gaps padded with `0xFF`) and downloaded with `dfu-util -d 0483:df11 -a 0 -s 0x08000000:leave -D <image>`. The `:leave` modifier tells the device to exit the bootloader after the download, so it reboots into the new firmware on its own and the watchdog reconnects it; the card then re-checks and shows the new firmware. Progress is streamed live over the WebSocket.
> [!WARNING]
> Flashing restarts the device into its bootloader and rewrites its flash. A power loss or unplug mid-flash can leave the device unbootable until it is reflashed manually. This is unofficial software, not affiliated with Thermal Grizzly — flash at your own risk.
API:
- `GET /api/wireview/firmware` — device vs. bundled firmware, the verdict (`newer` | `same` | `unknown` | `downgrade` | `product_mismatch` | `too_old_for_noctua`), `dfu-util` availability, and the flash state;
- `POST /api/wireview/firmware/flash` — `{"override": false}`; `override=true` is required for a downgrade or identical build. Returns `400` when the flash is refused (product mismatch, Noctua floor, downgrade/same without `override=true`) and `409` when a flash is already running.
## Pin current imbalance warning
The 12 VHPWR connector is the most fragile part of a PC's power delivery: if one power pin has a bad contact (worn cable, faulty adapter, loose plug), the remaining pins are forced to carry the missing current. Under heavy load this can overheat and melt the connector — in rare cases even start a fire.
NVCurve watches for this: if the current between any two power pins diverges by more than **2 A**, a big warning appears in the app header (visible on every tab, not just WireView) naming the deviating pins (e.g. `Pin 5 (5.6 A) vs Pin 6 (3.5 A)`). It is debounced — the imbalance must persist for several seconds (~7 s) before the warning shows, so single-sample glitches and short load ramps (e.g. AI workloads) do not flash it. When you see it, reduce the load and replace the cable or adapter — do not keep using the connector.
## Alternative: wireview-hwmon kernel module
If the official `wireview-hwmon` kernel module and its `wireviewd` daemon are installed, the daemon owns the serial port and NVCurve automatically reads the sysfs node instead. No udev rule is needed in that case.
## USB device IDs
| Mode | VID | PID | Description |
| --- | --- | --- | --- |
| Normal | `0483` | `5740` | STM32 CDC/ACM virtual serial port |
| DFU bootloader | `0483` | `df11` | STM32 bootloader (firmware updates only) |
## Troubleshooting
### WireView tab does not appear
- `lsusb | grep 0483` — is the device visible at all (cable, USB port)?
- `ls -l /dev/wireview-pro2` — if the node is `root:uucp`, the `dialout` group is missing or the rule did not load: `sudo groupadd dialout && sudo udevadm control --reload-rules && sudo udevadm trigger`.
- Restart the NVCurve server — detection runs at startup, and the watchdog re-checks periodically afterwards.
### `Permission denied` on the port (CLI)
The user must be in the `dialout` group; a running process only picks up new groups after a restart/re-login.
### Device visible but never connects
The firmware occasionally stops answering the RTS welcome handshake (observed after USB state changes, e.g. udev re-triggers or boot) while still answering every data command. NVCurve falls back to the vendor-data reply and retries, but if it still does not connect, reset the USB device — physically unplug/replug, or without reaching for it:
```sh
P=$(readlink -f /sys/class/tty/ttyACM0)
DEV=$(dirname "$(dirname "$(dirname "$(dirname "$P")")")")
sudo bash -c "echo 0 > $DEV/authorized; sleep 1; echo 1 > $DEV/authorized"
```
---
*The udev rule is taken from the wireview-reporter project, which uses the same access policy as the official `wireview-hwmon` module.*