Documentation

Appearance

What exactly runs on my device? #

First identify the agent generation and install mode. A modern full installation separates rescue access from an optional management supervisor. A modern rescue-only installation deliberately omits that supervisor. A legacy installation uses the classic remote-access agent and has neither the modern supervisor nor its local product broker.

Use Choose the right agent path if you do not already know which one is installed. Your own product application remains separate in every model.

Depending on the features you use, the device can contain four distinct layers:

  1. your Linux operating system and product application;
  2. the Dataplicity agent/supervisor for connectivity and fleet operations;
  3. the local product interface/runtime used to exchange streams, settings, actions, and other product data;
  4. an optional Software-managed application workload if you choose to distribute an OCI container through a Device Class.

You do not need layer 4 to use Customer Portal or to expose product data.

The modern full architecture #

text
+--------------------------------------------------+
| Your Linux device                                |
|                                                  |
|  Your product application                       |
|  - systemd service / container / other runtime  |
|             |                                    |
|             | selected product data/controls     |
|             v                                    |
|  Local Dataplicity product interface             |
|             |                                    |
|  Dataplicity agent / supervisor                  |
|             | outbound secure connection         |
+-------------|------------------------------------+
              v
        Dataplicity cloud

The diagram is the modern full path. It does not describe a legacy or rescue-only device. The important point is that Dataplicity sits beside your product application unless you deliberately choose to manage one of its container workloads through Software. For the component responsibilities and failure boundaries, read Modern agent architecture.

The on-device Dataplicity services #

The rescue or legacy path is responsible for the device identity and remote operating connection. On a modern full installation, the separate supervisor owns desired-state and product integration work.

That includes, depending on configuration and permissions:

  • device identity and connection state;
  • Remote Shell and support access;
  • file operations;
  • local information used by fleet operations and Pulse;
  • job execution;
  • logs and diagnostics integration;
  • communication with the connected-product runtime on the modern supervisor path.

Dataplicity's architecture uses an outbound connection from the device. You do not normally expose an inbound management port on the customer network.

The product interface #

If you use Device Class streams, settings, actions, or Product Applications, your product software needs a local integration point.

The role of that interface is intentionally narrow: exchange the stable product contract between your application and Dataplicity.

For example:

text
Your tank application        Dataplicity contract
---------------------        --------------------
sensor reading        --->   level_percent stream
calculated volume     --->   volume_litres stream
alarm state           --->   alarm_state stream
                      <---   alarm_threshold setting
                      <---   run_diagnostics action

Your application decides how the setting is validated and applied and what run_diagnostics actually does.

Software-managed application workloads #

A Device Class can optionally define an OCI container workload that Dataplicity installs and versions on compatible devices. In the Software workspace, a Container is one application workload. A Build selects the desired combination of container versions and, optionally, an OS image. Delivery shows application and OS outcomes, including the staged rollout required before a managed OS image is released.

This is useful when:

  • your application already fits a container runtime;
  • you want one declared workload version per product class;
  • Dataplicity should manage release of that workload;
  • you are building a new product and prefer a reference runtime rather than maintaining a separate deployment system.

It is not required when your application already runs correctly under systemd, Docker, Greengrass, balena, or another supervisor.

See Configure container software, Software Builds and cohorts, and Software Delivery.

Privilege and safety #

The device agent should not become an unrestricted root backdoor simply because you need one privileged operation.

Where privileged operations are required, prefer explicit, narrow permissions for the specific commands/files that need elevation. Product behaviour that must enforce safety or business rules should stay in the product application rather than relying on remote shell or a generic privileged action.

Resource and flash considerations #

Embedded Linux devices vary widely. When qualifying Dataplicity for a constrained product, measure:

  • steady-state memory and CPU;
  • disk footprint;
  • local queue/write behaviour;
  • reconnect behaviour on weak links;
  • interaction with watchdogs and startup ordering;
  • log retention and rotation;
  • the effect of any optional container runtime.

If flash endurance matters, keep high-frequency application state in the storage model designed for your product. Do not turn the Dataplicity integration into a high-write application database.

What happens at boot? #

The Dataplicity device component starts as part of the Linux service lifecycle and re-establishes its outbound connection independently of the product application's customer-facing state.

Your product should remain safe if Dataplicity cannot start or cannot reach the cloud. That is an important architectural rule: the cloud may add management and customer experience, but local product safety and essential operation should not depend on Internet availability.

What should I inspect before production rollout? #

On representative hardware, verify:

  1. clean boot with and without Internet access;
  2. your product application starts normally if Dataplicity is unavailable;
  3. reconnect after network loss;
  4. reboot/restart behaviour;
  5. CPU/RAM/storage impact;
  6. permissions used by diagnostics/jobs/actions;
  7. local product-data behaviour during a long outage;
  8. uninstall/disable behaviour for your offboarding plan.