Commands¶

Every Alicat command is one Command subclass — a frozen dataclass carrying metadata (name, token, response mode, firmware / device-kind / media / capability gates, destructive flag) plus pure encode / decode methods. The metadata is load-bearing: the Session reads every gate before dispatching, so commands fail fast with typed errors rather than silently producing a bad wire payload.

This page is a catalogue by module. See Design §5.4 for the command layer's architecture, §5.5–§5.8 for request/response modelling, and the individual module docstrings for the authoritative per-command detail. Full API reference is in the api pages.

Anatomy of a command¶

from alicatlib.commands import Command, ResponseMode, Capability
from alicatlib.devices.kind import DeviceKind
from alicatlib.devices.medium import Medium

Key Command fields:

Every Command operates through Session.execute(spec, request) (async) or session.execute(spec, request) (sync facade). The request is a typed per-command dataclass; the response is a typed result model. Neither the session nor the command layer does any raw-string juggling at the public surface.

Commands by module¶

Gas — commands/gas.py¶

media=GAS on all three. GasState response model carries the selected gas, selected code, and optional save flag echo.

Units — commands/units.py¶

DCU and FPF also run as a post-??D* sweep in the factory to bind data-frame fields to their active Unit and populate DeviceInfo.full_scale.

Setpoint — commands/setpoint.py¶

Setpoint range validation runs pre-I/O: FlowController.setpoint consults DeviceInfo.full_scale[lv.statistic] and raises AlicatValidationError on out-of-range values. Bidirectional devices accept [-fs, +fs]; unidirectional accept [0, +fs] (negative on unidirectional hits the BIDIRECTIONAL capability gate first). See safety.md for the V1_V7 / pre-9v00 caveat.

Loop control — commands/loop_control.py¶

Controller sessions cache LV at startup so setpoint range-checks against the right statistic's full-scale.

Control — commands/control.py¶

Both live on the shared _ControllerMixin, so PressureController inherits them without duplication.

Valve — commands/valve.py¶

VD decoder accepts 1–4 fixed-width percentage columns; physical valve count is a capability question, not a column-count one.

Data readings — commands/data_readings.py¶

DCA accepts both the 2-field real-10v20 reply shape (<uid> <averaging_ms>) and the primer's 3-field shape with echoed statistic code; the facade re-populates the statistic from the request.

Tare — commands/tare.py¶

AUTO_TARE disable form emits ZCA 0 (3-token reply) — the primer's ZCA 0 0 rejects with ? on real 10v20. See design §15.3.

Tare preconditions (no flow for flow tare, line depressurized for pressure tare) are caller responsibility; see safety.md.

Display — commands/display.py¶

unlock_display is the safety escape for a locked device — always callable. See safety.md for the V1_V7 display-lock recovery note.

User data — commands/user_data.py¶

Value is validated pre-I/O: ASCII only, length-bounded, no \r / \n. Empty-slot reply is 1-field (<uid>); decoder returns slot=-1 and the facade refills from the request.

Analog output — commands/output.py¶

Totalizer — commands/totalizer.py¶

T / TP reset encoders always emit the numeric totalizer argument so the wire form cannot degrade into bare T\r / TP\r, which are reserved for TARE_FLOW / TARE_GAUGE_PRESSURE. The invariant is pinned by dedicated unit tests.

Polling — commands/polling.py¶

POLL_DATA decodes through the cached DataFrameFormat. REQUEST_DATA has a unique wire shape — the reply carries no unit-ID prefix; invalid statistics return a column-width run of dashes per slot and surface as None in MeasurementSet.

Streaming — commands/streaming.py¶

Mode-transition bytes for streaming are not normal commands — start-stream is {uid}@ @\r and stop-stream is @@ {uid}\r, both written directly under the port lock from StreamingSession. See streaming.md for the full flow.

System / identification — commands/system.py¶

These are session-private in normal use — the factory runs them once at open. Users generally don't hit VE / ??M* / ??D* directly, but they're part of the public catalog for test fixtures and diagnostic scripts.

Destructive commands¶

Every command with destructive=True requires confirm=True at the facade layer and raises AlicatValidationError pre-I/O otherwise. See safety.md for the full list and rationale. The library never ships "off by default" destructive paths that activate on a single keyword argument — destructive means confirm=True in the caller, every call site, every time.

Experimental commands¶

Commands marked experimental=True emit a DeprecationWarning-style warning on use and may change in wire shape or return type before being promoted to stable. None ship in v1.0; the flag exists so future Tier-3 commands can land behind it.

Adding a new command¶

Per design §5.4, adding a command is ~50 lines and localised:

1. Declare the request / response dataclasses in the relevant alicatlib.commands.<module> file.
2. Declare the Command subclass with its metadata gates.
3. Implement encode(ctx, request) -> bytes and decode(response, ctx) -> Resp.
4. Add the facade method on the correct Device subclass.
5. Add the sync wrapper on the parallel alicatlib.sync.device class. Parity tests fail CI if this is skipped.
6. Write a FakeTransport fixture test; see testing.md.

No manager / recorder / sink changes are needed — sample flattening reads DataFrame.as_dict(), which is schema-stable across commands.