e1608: probe and docs for the network scan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/claude/architecture.md

@@ -44,7 +44,9 @@ What feeds `Acquisition` is a `DataSource`, one of the registered *kinds*.
   has neither key, so a legacy session is read as UDPS and nothing existing moves.
 - **The E-1608 kind has three layers, and only the top one knows the framework.** `e1608_link`
   (discovery, handshake, framed TCP commands, the scan socket) and `e1608_device` (typed commands,
-  factory calibration, `decode_scans`) are plain POSIX C++ with no GTK or `DataSource` types;
+  factory calibration, `decode_scans`) are plain POSIX C++ with no GTK or `DataSource` types; discovery is
+  `Scan` (one socket per interface, polled by the caller: the form polls it from a GLib timer on the main
+  thread, the source's lookup goes through `discover_broadcast`);
   `e1608_source` is the `DataSource`; `e1608_kind` and `e1608_panels` are the UI. A change to the wire
   never reaches the UI files.
 - The E-1608 source runs **everything inside `poll()`** on the producer thread: posted commands, the

docs/claude/build-and-run.md

@@ -122,7 +122,8 @@ is exported when the option is absent, so GTK's own choice stands.
 drops the default**: only a run with no `aiN` key gets `ai0=BIP10V`, so `ai1=BIP5V` alone is channel 1
 alone, and a value that is not a range name is a channel that is off), `dir0`..`dir7` `i|o`,
 `plot0`..`plot7`, `plot_counter`, `do_init`, `ao0_init`, `ao1_init`). Either `address` or `mac` is
-required; a MAC with no `address` is looked up by broadcast, or by a sweep of `subnet` (`a.b.c`).
+required; a MAC with no `address` is looked up by a broadcast sent on every interface (`Scan`), or by a sweep of
+`subnet` (`a.b.c`).
 The enabled channels times `scan_rate` must not exceed 250 kS/s. `tools/mock_e1608.py` is a protocol
 mock of the board for development (UDP discovery and handshake, TCP commands, a scan stream with a sine
 per channel, calibration memory, `--port`, `--mac`, `--log FILE`, `--drop-after S` and `--overrun-after S`

docs/claude/probe-readings.md

@@ -1859,11 +1859,12 @@ The UDPS run has no `source-` page in `side_stack`, because the UDPS kind has no
 [e1608] scan socket closed by the board
 [e1608] reconnect: connects=2 connected=1 ok=1
 [e1608] resumed: frames_before=612 frames_after=662 ok=1
+[e1608] scan: found=1 ip=172.21.121.113 mac=00:80:2f:00:16:08 status='1 board found' fill_addr=1 fill_mac=1 rescan_replaced=1 ok=1
 ```
 
 `UDPSCOPE_PROBE_E1608=1500` (the first eight lines; `frames=` and the exact mean vary) and
-`UDPSCOPE_PROBE_E1608_RECONNECT=8000` (the last two) run as `--source e1608` against `tools/mock_e1608.py`
-with the options in `verification.md`. The line between `decode` and `reconnect` is the source's own stderr message
+`UDPSCOPE_PROBE_E1608_RECONNECT=8000` (the next two) run as `--source e1608` against `tools/mock_e1608.py`
+with the options in `verification.md`; `UDPSCOPE_PROBE_E1608_SCAN=1000` (the `scan` line) is a run of its own. The line between `decode` and `reconnect` is the source's own stderr message
 about the drop, not a probe line (its text is the error the source met, once per distinct message). `connected=0` throughout, with
 `actions: skipped (not connected)`, is the no-board run; it is a reading and not a failure, and it also prints
 the one `[e1608] handshake with ...: Connection refused` line, `stream: ... signals=0 expect=1 ... ok=0`,
@@ -1894,6 +1895,16 @@ the one `[e1608] handshake with ...: Connection refused` line, `stream: ... sign
   drop (neither the scan read nor the status check raised it), `resumed: ok=0` is a reconnect that did not restart
   the scan (it also reads 0 when `connects` is still 1, since a frame count that grows on a link that never dropped
   proves nothing).
+- `scan: found=1 ... ok=1`: the form's **Scan network** row against the mock. `found` is the result rows after
+  the first scan; `0` with the second line `did not answer` is an environment with no up, non-loopback
+  broadcast interface that reaches the mock (or a refused broadcast), **not a pass**. `ip` is the listed address
+  of the expected board and `mac` the MAC the probe looked for.
+- `status='1 board found'`: the row's subtitle at the end of the first scan (`N boards found` with more
+  than one). `No board found` with a mock running is the probe's sockets not reaching it.
+- `fill_addr=0`: a click on a result did not set only the address (the MAC or subnet kept a stale value), or it
+  told the dialog something other than once. `fill_mac=0`: the same for **Use MAC**.
+- `rescan_replaced=0`: the results of the first scan were kept or doubled by the second, so `start_scan` did not
+  remove them.
 
 ## `[flatudp]`
 

docs/claude/verification.md

@@ -441,6 +441,13 @@ precedent, not an exception.
   - **a rejected code:** mock `--code 1234`, app `code=7`: one error line, the retries stop.
 - `UDPSCOPE_PROBE_E1608_RECONNECT=8000` -- reads the source after the mock dropped the link and 500 ms
   later checks the frame count moved on. The reading's own entry is in `probe-readings.md`.
+- `UDPSCOPE_PROBE_E1608_SCAN=1000` with `UDPSCOPE_EXIT_AFTER_MS=6500`, run as `--source e1608 --source-opt
+  address=127.0.0.1` against `tools/mock_e1608.py` on its default port 54211 (the form scans that port) -- builds
+  the connection form, presses **Scan network**, expects the mock to be listed, clicks the result (address
+  filled, MAC and subnet cleared), presses **Use MAC** (MAC filled, the others cleared), scans again and checks
+  the results were replaced. `UDPSCOPE_PROBE_E1608_SCAN_MAC` names another board (a real one) instead of the
+  mock's `00:80:2f:00:16:08`. One `[e1608] scan:` line. It needs a non-loopback up interface with a broadcast
+  address; when the board did not answer a second line says so, and the run proves nothing about the scan.
 - `UDPSCOPE_PROBE_FLATUDP=2500` with `UDPSCOPE_EXIT_AFTER_MS`, run as `--source flatudp` against
   `tools/mock_flatudp.py` -- the flat UDP source end to end: a hand-computed codec and decode check and the connect form's validity rules and signal-row editor (both
   need no source; it covers the `w` suffix, the waveform and 256-channel rules, the channel decode and the