Documentation

Appearance

Connect your product application #

Your product process should speak to a local contract. The supervisor owns cloud transport, credentials, buffering and desired-state reconciliation.

This boundary is useful whether your application is a native daemon, a container you manage, or optional Class Software managed by Dataplicity.

Local data and control path #

The loopback broker listens on 127.0.0.1:18765.

text
POST /v1/streams/{binding_id}
GET  /v1/actions
GET  /v1/settings
POST /v1/settings/{key}/reported

Use the stable binding or setting key defined by the Device Class. Do not bake cloud URLs, organisation API keys or device secrets into the product application.

Desired settings #

The supervisor materialises the current desired settings under:

text
/var/lib/dataplicity/config/current/parameters.json

Managed containers receive the current configuration as a read-only mount, normally at /etc/dataplicity/config through DP_CONFIG_DIR.

Treat desired and reported values as different facts:

  • desired is what the cloud asks the device to use;
  • reported is what the product confirms it has applied.

A product should validate a requested value, apply it safely, and report what actually took effect. It should not claim success merely because the file changed.

Streams and offline behaviour #

Choose buffering based on the data, the product and the storage medium. The default stream buffer is volatile to avoid turning routine telemetry into constant flash writes. Durable SQLite buffering is an explicit OEM choice.

Define:

  • which samples can be dropped or coalesced;
  • which events must survive a restart;
  • maximum offline retention and storage use;
  • what happens when data is too old to be useful;
  • how the product behaves when the cloud never returns.

Exactly-once delivery is not a safe assumption. Use idempotency or domain identifiers where duplicates matter.

Optional Class Software #

Class Software is an OCI application delivery path. The supervisor verifies and reconciles the selected release through a container runtime already qualified for your image.

A Software Build selects the versioned OCI releases a Device Class should run and can also reference an OS image. Class Software is the container part reconciled by the supervisor. Container application and OS-image delivery remain separate operations, so either can be observed and recovered without confusing a container change with a root filesystem change.

A missing runtime must produce an explicit skipped state. Dataplicity must not silently install a container runtime or report success.

Dataplicity OS provides containerd and nerdctl, not Docker Engine. Its managed containers use host networking to reach the broker on the host, while the supervisor invokes the required rootful runtime operations through fixed allowlisted wrappers. Container data and the current settings snapshot remain on dpdata across RAUC slot changes.

Keep hardware safety, authoritative local control loops and boot-critical behaviour outside a cloud-dependent container unless your product has independently engineered that failure mode.

Before release #

Prove one value, one setting and one action on the production image. Then test duplicate delivery, invalid input, a full buffer, reboot during apply, lost cloud connectivity and recovery after the outage.

The exact delivery and retry contract lives in Device data and controls. The software boundary lives in Software and firmware boundaries.