Build a customer-operated telemetry product

This walkthrough is for a product whose main customer value is a number: temperature, pressure, flow, signal strength, current, speed, vibration, or another numeric measurement.

It takes one representative Linux device through the complete path from a working local reading to a customer-operated product in your Customer Portal. The example is a fictional cold-room monitor publishing temperature, but the contract works for other numeric telemetry.

You finish with:

• a product Device Class
• a stable numeric stream with meaningful units and history
• explicit warning state instead of an unexplained number
• one safe operation or persistent setting where the product needs it
• a customer page designed around identity, freshness, current state, and trend
• the first device allocated and verified by customer role

Before you start

You need:

• a supported Linux device with a working sensor application
• the Dataplicity agent and access to Device Classes
• a customer and portal administrator test account
• an agreed unit, plausible range, and reporting cadence

If hardware is not ready, attach fridge-temp-sim or hvac-sim from the class Software tab. The simulator proves stream, layout, allocation, and portal behavior. It does not prove a real probe, installation, or control loop.

Part 1: Define what the number means

Write the product contract before creating a stream:

Decision	Cold-room example
Customer quantity	Air temperature
Unit	°C
Plausible range	-30 to 30
Expected cadence	Every 30 seconds
Useful history	24 hours for shift review
Warning state	High or low threshold exceeded
Missing meaning	Probe or publisher unavailable
Stale meaning	Device online, but no recent product sample

Use a name the customer recognises. cold_room_temp_c is a better contract than modbus_register_40112. Keep the implementation detail inside the device adapter.

Do not make a customer infer warning state from a chart. Publish explicit boolean state such as temperature_high and temperature_low when the decision depends on thresholds.

Part 2: Create the product Device Class

1. Open Engineering > Device classes.
2. Choose New device class.
3. Name it Cold Room Monitor.
4. Select the representative hardware architecture.
5. Describe the supported sensor and runtime combination.
6. Create the class.

On UI Components, add:

Product concept	Class definition
Current reading	cold_room_temp_c numeric stream, unit °C
History	Chart based on cold_room_temp_c
Explicit state	temperature_high and temperature_low booleans
One-off operation	Run probe test trigger action
Persistent preference	Temperature setpoint or reporting interval with safe bounds

Only expose a setpoint when the device genuinely controls it. A monitor that cannot alter the physical process should not present a control-looking setting.

Fast path: use an example

1. Open the class Software tab.
2. Choose Add container.
3. Keep Use an example selected.
4. Select Fridge temperature (sim) (fridge-temp-sim) or HVAC (sim) (hvac-sim).
5. Choose Add example.
6. When a published release exists, attach can create and ship the current Software set automatically. Otherwise create firmware after a release is available.
7. Use Pin to tags for a tagged staging cohort, or Make current for the class default.

The same Software workflow attaches a telemetry example and shows whether its Software set is shipping. The illustrative class shown here uses different example containers.

Production path: publish from your runtime

Your sensor application may stay under systemd, Docker, Podman, or its current supervisor. Create a small publisher that validates the reading and sends it to the local agent broker:

POST http://127.0.0.1:18765/v1/streams/cold_room_temp_c

{
  "sequence": 1,
  "timestamp_ms": 1710000000000,
  "body": { "value": 3.8 },
  "metadata": { "source": "temperature-adapter" }
}

The publisher contains no Dataplicity cloud credential. The agent authenticates delivery. The class stream's History setting controls retention; a publisher storageProfile does not override it.

Part 3: Connect the representative device

1. Open Engineering > Devices.
2. Choose Add device and select Cold Room Monitor.
3. Copy the current class-specific installer command.
4. Run it on the representative Linux device.
5. Wait for the new device to become Online.
6. Confirm the publisher or simulator is running.
7. Confirm the stream unit, cadence, and current value.
8. Compare at least one cloud value with the local sensor application.

Treat the real installer command as a secret. Do not place it in documentation, screenshots, source control, or tickets.

Test representative minimum, normal, and maximum values. A page designed only against 3.8 °C can fail badly when the product reports -29.7 °C, 0, or an invalid spike.

Part 4: Design the customer's page

Open UI Designer and arrange:

1. customer-readable product name, site, and serial
2. device connectivity and last report
3. current measurement with unit and data freshness
4. explicit normal, high, low, or fault state beside the value
5. history over the period used for the operating decision
6. one bounded action or setting, only when the customer should use it
7. support context

Use a metric for the current reading and a chart only when history changes a decision. Do not add every signal the device can publish. The customer product page is an operating surface, not an engineering telemetry dump.

Preview:

• no sample yet
• device online but reading stale
• device offline
• normal value
• high and low warning values
• invalid or implausible value
• action requested and awaiting confirmation
• viewer role with controls absent

Part 5: Create the first customer

1. Open Customer journey > Customer Portal.
2. Confirm branding, sign-in copy, and support link.
3. Open Customer journey > Customers.
4. Create the downstream customer and first administrator.
5. Sign in to the portal and create the network representing the real operating location, such as Distribution Centre 4.
6. Invite one read-only viewer for boundary testing.

Create the downstream customer in the OEM workspace before allocating the first telemetry device.

The network is the current portal placement boundary. It can represent a building, room, cabinet, vehicle, or another customer location.

Part 6: Allocate and place the device

1. Return to Engineering > Devices.
2. Find the verified Cold Room Monitor.
3. Choose Allocate to customer.
4. Select the intended customer and confirm.
5. Sign in to the Customer Portal as the administrator.
6. Open Inventory.
7. Assign the device to Distribution Centre 4.

Allocation is the audited ownership handover. Complete sensor, stream, and layout verification before moving the unit.

The customer administrator places the allocated telemetry device in the operating location where their users will find it.

Part 7: Verify the customer experience

Viewer

• sees only the intended customer locations and devices
• can identify the physical product
• sees current value, unit, freshness, warning state, and useful history
• cannot run actions or change settings
• cannot see OEM logs, Remote Shell, software, or fleet-wide controls

Operator

• sees only controls required for the operating job
• cannot enter values outside the documented setting bounds
• receives useful pending, success, or failure state after an action

Admin

• can place devices only within permitted customer networks

Test another customer account and prove the device, location, and telemetry are absent.

Part 8: Add operations without cluttering the customer page

The OEM engineering workspace is where you add:

• logs from the sensor application
• monitors for device connectivity and customer-impacting state
• alerts and incident handling
• Device Class Pulse for peer drift
• Fleet Jobs and remote access for bounded support work
• class Software when Dataplicity should version and release the application

The customer page should continue to show product state and permitted controls, not OEM diagnostics.

Production handover gate

• [ ] The value matches a trusted local reading.
• [ ] Unit, precision, cadence, and plausible range are documented.
• [ ] Missing, stale, offline, warning, and invalid states differ.
• [ ] History uses the period relevant to the customer's job.
• [ ] Viewer roles have no actions or settings.
• [ ] Every control is supported, bounded, and validated on the device.
• [ ] The device reconnects after power and network loss.
• [ ] Another customer cannot see the device or its telemetry.
• [ ] OEM support can diagnose the product without exposing engineering tools.
• [ ] Probe replacement and recalibration procedures are documented.

Related

• Build your first connected product
• Device Classes
• Device class streams
• Design the customer product UI
• Example simulators
• Customer Portal
• Monitors and alerts