Added documentation to creating new devices and protocols

1 files changed, 146 insertions, 0 deletions

diff --git a/docs/developer-new-protocols.md b/docs/developer-new-protocols.md
new file mode 100644
index 0000000..724bdc7
--- /dev/null
+++ b/docs/developer-new-protocols.md
@@ -0,0 +1,146 @@
+# Adding a new serial protocol
+
+A "protocol" here means a wire format `SerialDevice` (`devices/serial_device.py`)
+can speak to a serial instrument — SCPI, Mark-10, Modbus RTU, CML are the
+existing ones, living in `api_layers/protocols/`. This is narrower than
+[developer-new-devices.md](developer-new-devices.md): you're adding a new
+option to the existing "Serial / UART" device type's Protocol/Format
+dropdown, not a whole new device class. If your hardware isn't
+serial-based, or doesn't fit the "poll a channel map" shape at all, write a
+new `BaseDevice` instead.
+
+## The interface
+
+Every protocol subclasses `BaseProtocol` (`api_layers/protocols/base_protocol.py`),
+which already handles the connection, the background poll thread, and the
+simulate/real split — you only implement three methods:
+
+```python
+class BaseProtocol(ABC):
+    @abstractmethod
+    def _poll(self) -> Dict[str, float]:
+        """Read the instrument once, return {channel_id: value}."""
+
+    @abstractmethod
+    def _simulate(self, t: float) -> Dict[str, float]:
+        """Return plausible fake values at elapsed time t (seconds)."""
+
+    @abstractmethod
+    def write(self, channel_id: str, value) -> bool:
+        """Send a command. Return False for unknown/read-only channel_id."""
+```
+
+`BaseProtocol.__init__(port, baud, poll_interval=0.1, simulate=True)` gives
+you `self._ser` (a `pyserial` `Serial`, only when not simulating — opened by
+the base class's `connect()`, don't open it yourself), `self._io_lock` (hold
+this around every `self._ser` read/write — the poll thread and any
+synchronous `write()` calls share the same serial handle), and `self.read()`
+which any caller uses to get the latest `_poll()`/`_simulate()` result
+(cached, not blocking).
+
+## Two real shapes to copy from
+
+**Fixed channel set, gauge reports its own units — `api_layers/protocols/mark10.py`.**
+The instrument always exposes the same channels; you don't need per-channel
+configuration. `_poll()` sends `?\r`, parses `<value> <unit>` with a regex,
+tracks the unit so it can be exposed via a `current_unit` property (this is
+what lets the Mark-10 gauge's live lb/kgF/N/ozF switch propagate through to
+plot axis labels — see `devices/serial_device.py:145-152` and
+`core/acquisition.py`'s `channel_unit_changed` signal). Good template when
+your instrument has a small, fixed, well-known channel set.
+
+**Configurable per-channel queries — `api_layers/protocols/scpi.py`.**
+Channels are a list of small dataclasses (`SCPIChannel(channel_id, name,
+query, unit, scale, write_cmd)`) the *operator* fills in per-instrument,
+since SCPI query strings vary by model. `_poll()` iterates the list, sends
+each query, parses the numeric response. Good template when the channel map
+can't be known ahead of time — the corresponding config panel
+(`_SCPIPanel` in `serial_device.py`) is an editable table, not static text.
+
+Pick whichever shape matches your instrument; most new protocols are one or
+the other.
+
+## Wiring it into SerialDevice
+
+Five places in `devices/serial_device.py`, all keyed by a short format
+string you choose (e.g. `"mymeter"`):
+
+**1. Register the format** (`_FORMAT_LABELS`, line ~41 — human label → key)
+and add the key to `_PROTOCOL_FORMATS` (line 53, marks it as an
+instrument protocol rather than a generic key:val/csv/json stream) and
+`_STACK_IDX` (line 77 — index into the config-widget stack, see step 4):
+```python
+_FORMAT_LABELS["My Meter"] = "mymeter"
+_PROTOCOL_FORMATS.add("mymeter")
+_STACK_IDX["mymeter"] = 5   # next free index
+```
+(these are module-level dict/set literals in the real file — in practice
+you edit the literals directly rather than mutating at import time, but the
+effect is the same.)
+
+**2. Channel configs** — add a branch in `_build_channel_configs()`
+(around line 289, `elif fmt == "scpi": ...`) returning the
+`List[ChannelConfig]` for your format, same pattern as the Mark-10 branch
+(fixed list) or SCPI branch (built from user-entered channel dicts).
+
+**3. Layer construction** — add a branch in `_make_layer()` (around line
+364) that imports and instantiates your protocol class:
+```python
+elif fmt == "mymeter":
+    from api_layers.protocols.my_meter import MyMeterLayer
+    return MyMeterLayer(self._port, self._baud, simulate=self.simulate)
+```
+
+**4. Config widget panel** — add a `_MyMeterPanel(QWidget)` class (near
+`_Mark10Panel`/`_SCPIPanel`, line ~601+) — static info text if your channel
+set is fixed (copy `_Mark10Panel`), an editable table if it's configurable
+(copy `_SCPIPanel`). Instantiate it alongside the others in
+`SerialConfigWidget._build()` and add it to `self._proto_stack` (line ~501)
+at the index you picked in `_STACK_IDX`.
+
+**5. Save/restore** — if your protocol has operator-configured state (like
+SCPI's channel list), add a branch to `get_save_config()` (~line 561) and
+accept the matching kwarg in `SerialDevice.__init__`/`reconfigure()`. Fixed-
+channel protocols like Mark-10 need nothing here (`elif fmt == "mark10":
+pass  # no extra config`).
+
+## Things that aren't obvious from the abstract methods
+
+**`_poll()` runs on a background thread** (`BaseProtocol._poll_loop`) — don't
+touch Qt widgets from it. Return the dict; `SerialDevice.read_channels()` on
+the main-thread-adjacent acquisition poll picks it up via `self.read()`.
+
+**Units live on the *device's* `ChannelConfig`, not the protocol layer**,
+if you want live unit changes to reach the plot. The protocol layer just
+exposes whatever it parsed (e.g. `current_unit` property); `SerialDevice.
+read_channels()` is what copies it onto `ChannelConfig.unit` each read —
+see the Mark-10 branch at `devices/serial_device.py:145-152` for the exact
+pattern, including the comment explaining why this alone isn't sufficient
+(the unit-change-to-plot-axis propagation is a separate mechanism in
+`core/acquisition.py`).
+
+**Discard vs. keep unit suffixes.** `api_layers/arduino_layer.py`'s generic
+key:val/csv parser strips anything after a numeric value ("0.04 V" → 0.04)
+and throws the unit away — that's correct for the generic Arduino stream,
+but if your protocol's whole value is "parse a unit that can change live",
+don't reuse that parser; write your own regex like Mark-10's `_RESP_RE`
+that captures the unit instead of discarding it.
+
+**Write-only "action" channels** (zero a gauge, cycle units, enable a
+motor) are just channels with `writable=True` and no corresponding read —
+see Mark-10's `zero`/`cycle_units` or CML's `ME`/`MD`/`ST` channels in
+`_build_channel_configs()`. `write()` dispatches on `channel_id` same as any
+other write.
+
+## Checklist
+
+1. New file `api_layers/protocols/my_protocol.py`, subclass `BaseProtocol`,
+   implement `_poll()`, `_simulate()`, `write()`.
+2. Register the format string in `serial_device.py`'s `_FORMAT_LABELS`,
+   `_PROTOCOL_FORMATS`, `_STACK_IDX`.
+3. Add branches in `_build_channel_configs()` and `_make_layer()`.
+4. Add a config panel class, wire it into `SerialConfigWidget._proto_stack`.
+5. If there's operator-configured state, add it to `get_save_config()` /
+   `__init__` / `reconfigure()`.
+6. Simulate first (`simulate=True` is the default) — `_simulate()` needs to
+   produce plausible values before you ever touch real hardware.