Documentation

Appearance

What exactly runs on my device? ​

At minimum, Dataplicity runs its device agent to establish the secure outbound connection and provide the device-side capabilities you enable. Your own product application remains separate.

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. optional Dataplicity-managed class software if you choose to distribute an OCI workload through a Device Class.

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

The normal 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 important point is that Dataplicity sits beside your product application unless you deliberately choose to let Dataplicity manage that application as class software.

The agent ​

The agent is responsible for the device's Dataplicity connection and the local capabilities associated with that connection.

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.

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.

Dataplicity-managed class software ​

A Device Class can optionally define an OCI/container workload that Dataplicity installs and versions on compatible devices.

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 Build a class container.

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.