Shared contracts and gateway setup

The canonical LaundryMachine and field-profile contracts live in the platform source. Executable gateway code, profile snapshots and tests live in the public equipment-gateway source. Dataplicity-OS provides the host image, containerd/nerdctl and RAUC lifecycle.

Machine capabilities

Every canonical property and action declares supported, unsupported or unknown. Supported values carry provenance, capability version and freshness. Machine-native, inferred, externally sensed and simulated evidence remain distinct. An absent observation differs from an unsupported property; stale readings do not become an available-machine claim.

The contract includes identity, availability, operating state, programme/stage, remaining time, door/lock, price/credit, faults, out-of-service and counters. Canonical actions include vend, start, add time, free vend, reset, out-of-service, pricing and programme/options. Only explicitly supported actions are configured on the Device Class, with confirmation and typed correlation inputs. Existing authorised-action permissions and audit remain authoritative.

The bundled native and pulse simulators intentionally expose different subsets. The pulse simulator cannot infer a machine acknowledgement or cycle start from a dispatched pulse. Its unknown outcome exercises reconciliation.

Field-device profiles

EnergyMeter, FlowMeter, TemperatureSensor, AmbientSensor and LeakSensor use generic profiles independent of the laundry application. A profile specifies exact model and revision applicability, transport, address, register/function, datatype, byte/word order, scale/offset, engineering unit, polling, freshness, validity and semantic mapping. Profiles also declare equipment-neutral command steps: digital input/output, pulse/count, register read/write and bounded serial transfer. Physical Modbus actuation requires an evidence-backed profile; physical pulse outputs require a controller-owned timer rather than a relay held by a host sleep. Raw physical serial/OEM adapters remain separately gated.

Registers are zero-based Modbus protocol addresses. Profiles on one serial bus require unique addresses and consistent serial settings. CRC, timeout, disconnected, invalid, missing and stale states are explicit. Raw observations retain the exact versioned conversion profile (including piecewise calibration tables) and its digest, so later edits do not reinterpret earlier evidence. The bundled meter profiles are fictional simulators, not purchasable-device recommendations.

Managed runtime

1. Create the operator's Product Instance and equipment records using the normal Product Application setup path.
2. Select a checksum-verified, registered equipment-gateway Software release. Source availability alone does not mean a release has been published.
3. Configuration schema version 2 declares equipment IDs, installed adapter plugins and their options. Set the instance and equipment IDs; validate it with the package's --check command before starting the workload.
4. Bind read-only configuration, the existing agent socket directory and only explicitly approved isolated serial devices. Grant the actual numeric host socket and serial groups; do not assume a particular GID.
5. Bind application state from /var/lib/dataplicity/equipment-gateway on dpdata to /var/lib/equipment-gateway. Keep the database, WAL and SHM files together.
6. Start and update the workload through the normal Software lifecycle.

The optional dataplicity-equipment-host OS recipe prepares storage after dpdata mounts. Application source remains in the gateway repository. No extra agent or standalone laundry supervision service is required.

Command certainty

Commands arrive through the agent's Product Runtime socket. The gateway verifies instance/equipment routing, expiry, cancellation and typed inputs before dispatch. It durably reserves an invocation and immutable physical-effect identity before calling an adapter. Duplicate commands, including a new invocation for the same equipment/effect/action, return the recorded outcome. A crash during dispatch leaves an unknown outcome.

Accepted means command acceptance only. Service started and completed need their own machine evidence. During agent/network loss, the gateway retains outcomes and later reports them through the existing durable event API. It never replays a physical command automatically. Journal capacity fails closed; unresolved evidence must not be deleted to make room for more transactions.

Reuse acceptance

The same gateway executable/container accepts either the LaundryMachine simulator configuration or config.access-control.example.json. The latter loads a non-laundry AccessController profile and exercises digital observation, a timed relay pulse, and register read/write through the same generic primitive engine, command journal and agent API. It requires no runtime changes and makes no physical compatibility claim.

LaundryMachine semantics reside in the equipment adapter and Device Class; Product Processes interpret orders and delivery. Core runtime configuration, storage and APIs use equipment/effect IDs and opaque correlation metadata. Generic state events are equipment.state; they do not assert business delivery. The unreleased development prototype's old journal schema fails closed if reused; retain its evidence and review a migration rather than deleting the database.