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 missing runtime must produce an explicit skipped state. Dataplicity must not silently install a container runtime or report success.

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.