Skip to content

Safety

watlowlib drives physical hardware — heaters, ovens, retort controllers, calibration baths. Safety rules are binding; see the Design doc §5b for the authoritative list.

Per-command safety tier

Every Command carries a SafetyTier:

Tier Examples Gate
READ_ONLY process_value, setpoint reads, output_power, alarm status, identity, part number runs freely
STATEFUL reserved (no library command currently uses this tier) runs freely
PERSISTENT every parameter write — including RW runtime-only parameters; PID writes; protocol-mode flip; baud / address change requires confirm=True

Calling a PERSISTENT operation without confirm=True raises WatlowConfirmationRequiredError before any I/O — no bytes go out.

The library treats every write as a state change worth confirming, including RW "runtime only" parameters that don't write EEPROM. That's slightly stricter than the Watlow RWES classification; see Design §5b for the rationale.

Gate order

Session.execute() applies gates in this fixed order:

  1. Safety tier (hard) — PERSISTENT operations need confirm=True.
  2. Protocol (hard) — the active-protocol variant must not be None, else WatlowProtocolUnsupportedError.
  3. Firmware floor (hard, when min_firmware is set) — refuse pre-I/O with WatlowFirmwareError.
  4. Capability priors (soft by default) — emit a one-shot WatlowCapabilityWarning and attempt the command anyway.
  5. Known-denied (hard once observed) — if the per-session availability cache records Availability.UNSUPPORTED for this command, raise pre-I/O without re-probing.
  6. Execute, then map the device response into an availability transition (Std Bus "no such object/attribute/instance" or Modbus IllegalDataAddress flips the cache to UNSUPPORTED).

Why soft-gate on capability priors?

The reverse-engineering sample behind the family / capability tables is small. The cost of a wrong denial (user blocked from a parameter their controller actually supports) is worse than the cost of a failed attempt (one round-trip and a clean typed error). Soft-gating means the device is the source of truth for what's available; the library's prior is just a hint. See Controllers for the "capabilities are priors, not contracts" framing.

Persistent-write helpers

The following maintenance operations are gated as PERSISTENT-or-stronger because they mutate device EEPROM and may force a transport rebind:

Function Notes
change_baud(...) Updates the baud parameter, saves, re-opens the transport at the new rate.
change_modbus_address(...) Updates the Modbus slave address; rebinds the session.
change_stdbus_address(...) Updates the Standard Bus address (1..16); rebinds the session.
change_protocol_mode(...) Flips the controller between Std Bus and Modbus RTU at parameter 17009; verifies post-write at the new framing.

All four require confirm=True. They're exposed both as one-shot port-level helpers (no full Controller lifecycle needed) and via the watlow-configure CLI.

SKU gate on change_protocol_mode

On EZ-ZONE PM SKUs without a Modbus stack (comms position-8 = A, 0, 5, 6, etc.), writing parameter 17009 = "Modbus" succeeds on the wire but the device never starts answering Modbus frames. change_protocol_mode checks the part number's comms code before issuing the write and raises WatlowCapabilityError if the SKU does not include the requested protocol. See Troubleshooting.

Pre-flight validation

Before a write reaches the wire, the registry validates the value against the parameter's range (when range_min / range_max parsed cleanly from the EZ-ZONE register list) and the instance against spec.max_instance. Both checks raise WatlowValidationError pre-I/O — bytes never go out for an obviously-malformed write.

The device performs its own bound check on the wire and answers with WatlowNoSuchObjectError (Std Bus) or WatlowModbusIllegalDataValueError (Modbus) if the host validator missed the violation.

Hardware test tiers

Marker What it does Opt-in env var
hardware Read-only against a connected controller WATLOWLIB_TEST_PORT=/dev/ttyUSB0
hardware_stateful Changes device state (parameter writes) WATLOWLIB_ENABLE_STATEFUL_TESTS=1
hardware_destructive Baud / address change, protocol switch WATLOWLIB_ENABLE_DESTRUCTIVE_TESTS=1

Default pytest runs exclude all three. See Testing.

See also

  • Commands — gate order on every command surface.
  • Controllers — capability flags as priors not contracts.
  • Parameters — RWES → SafetyTier mapping.
  • Maintenance API — persistent-write helpers.
  • Testing — hardware tiers and FakeTransport.
  • Design §5b — full gate-order rationale.