# 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.