flatudp: vector rows as channels or as a waveform, a re-openable source, probes for both

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

docs/claude/build-and-run.md

@@ -140,20 +140,27 @@ concatenated in declaration order, no header, no padding). The datagram carries
 settings are the whole contract: `port` 44488, `bind`, `multicast` and `iface` (a group to join and the local
 interface for it), `rate` (the sender's cycle rate in Hz; **required**, it sizes the ring and the ingest
 decimation and spaces the samples within a frame), `endian` `little|big`, and `signals`
-`name:type[count],...` with types `uint8/16/32/64`, `int8/16/32/64`, `float32`, `float64` (a count above 1
-makes a vector signal: one channel whose `count` values per datagram are consecutive samples, as a UDPStreamer
-block signal), e.g. `Trigger:uint8,Ia:float32,Wave:float32[16]`. A datagram of any other size than
+`name:type[count][w],...` with types `uint8/16/32/64`, `int8/16/32/64`, `float32`, `float64`, e.g.
+`Trigger:uint8,Ia:float32,Wave:float32[16]`. A count above 1 makes a vector signal, shown one of two ways: by
+default as `count` **channels** `Wave[0]`..`Wave[15]` of one sample per cycle each (batched like any scalar
+list); with a trailing `w` (`Wave:float32[16]w`) as ONE **waveform** channel receiving `count` consecutive
+samples per cycle at `rate * count`, as a UDPStreamer block signal. A waveform row needs a count above 1, a
+list with one holds only waveform rows of one count (no zero-padding of scalars), and a list may make at most
+256 channels (a scalar 1, a `channels` row `count`, a waveform 1). A datagram of any other size than
 the list implies is dropped and counted as stale; each distinct wrong size is reported once on stderr as
 `[flatudp] ...`. Loss is never reported: the stream has no counter. `tools/mock_flatudp.py` is a sender for
 a signal spec (`--rate`, `--signals`, `--big-endian`, `--gap S,D`, `--bad-every S`, `--multicast G --mcast-if A`,
 `--log FILE`).
 
 ```sh
-python3 tools/mock_flatudp.py --port 44588 --rate 1000 --signals Trigger:uint8,Ia:float32,Wave:int16[4] &
+python3 tools/mock_flatudp.py --port 44588 --rate 1000 --signals 'Trigger:uint8,Ia:float32,Wave:int16[4]' &
 ./build/udpscope --source flatudp --source-opt port=44588 --source-opt rate=1000 \
-  --source-opt signals=Trigger:uint8,Ia:float32,Wave:int16[4]
+  --source-opt 'signals=Trigger:uint8,Ia:float32,Wave:int16[4]'
 ```
 
+(Quote the `signals` value: zsh globs the `[4]`. The mock takes the same text with or without the trailing `w`;
+the datagram is the same, `w` only says how the app shows it.)
+
 `tools/mock_udpstreamer.py` has waveform-injection options used by the probes:
 
 - `--square-harmonics N` shapes `square`: `N` odd harmonics of the ideal step's Fourier