Shared contracts and gateway setup

Reference lab status: A physical CM5 and T600 DevKit have completed Stripe test-card authorisation, simulated vend and automatic capture against a production-hosted application. Real-machine actuation and live unattended payments require separate qualification. Follow the test checkout walkthrough for the exercised 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

The public equipment-gateway releases provide native AMD64 and ARM64 OCI archives. Use the checksum published with the selected release to verify the downloaded archive.

The gateway polls observations in bounded round-robin passes and preserves their original timestamps. Missing measurements remain unknown; reporting cached values again does not make them fresh. Capability inventory is republished every 30 seconds in bounded chunks. Outgoing events are bounded to 48 KiB. A profile that exceeds the limit is rejected before hardware is opened; use separate instruments for large measurement banks.

Before installation, confirm that the release is available in your Software catalogue. If it is unavailable, contact your vendor to arrange it. Then configure and commission the workload on representative hardware.

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. Version 0.2.7 returns a matching journaled outcome before checking a deadline for a new effect, and reports command results before publishing outcome events. Reporting failures therefore preserve the original result for recovery. 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 with other equipment

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. If an existing journal has an incompatible schema, preserve its evidence and review a migration before restarting the workload.