Build a customer-operated level monitor

This walkthrough takes one working Linux level monitor through the complete product path: stable sensor input, Device Class, level display, customer-safe controls, first customer allocation, and verification in your Customer Portal.

Use it for silos, tanks, bins, wells, batteries, and other products where the customer needs to understand a bounded quantity. The example product is a fictional SiloSentry Monitor, but the path is the same for a tank or well.

You finish with:

• one representative device online in the OEM engineering workspace
• a reusable Device Class that defines the level-monitor product
• a customer page showing identity, connectivity, freshness, level, history, threshold state, and permitted controls
• one downstream customer with the monitor allocated to the correct location
• a viewer and operator proving the portal boundary

Dataplicity does not turn an uncalibrated sensor into a trustworthy measurement. The hardware adapter, calibration method, safe ranges, and device-side control logic remain part of your product.

Before you start

You need:

• a supported Linux device with the Dataplicity agent
• a level sensor or a staging simulator
• access to Engineering > Device classes
• access to Software, UI Components, and UI Designer
• access to Customer journey > Customer Portal and Customers
• a customer email address that is not your OEM operator account

If the real sensor is not ready, use grain-silo-sim, tank-level-sim, or water-table-sim to prove the complete product and portal path. A simulator proves the Dataplicity integration; it does not prove sensor accuracy or field reliability.

Part 1: Prove the measurement locally

Before involving Dataplicity, prove that the Linux application can read a physical value repeatedly.

Record:

Decision	Example
Raw measurement	4.2 m from the sensor datum
Expected cadence	Every 30 seconds
Plausible minimum and maximum	0 m to 12 m
Missing-reading behavior	Keep last value only for the defined stale window
Calibration source	Empty/full points or an approved strapping table
Customer quantity	Percent, volume, height, voltage, or pressure, depending on level type

Do not continue with a derived quantity until you can explain how it is calculated. A cylindrical tank may have a simple conversion. A grain silo or irregular vessel may require a strapping artefact. A well depth may use an inverted scale. Preserve the raw value so support can distinguish sensor failure from conversion failure.

Part 2: Create the level-monitor Device Class

1. Open Engineering > Device classes.
2. Choose New device class.
3. Name it SiloSentry Monitor.
4. Select the architecture that matches the representative device.
5. Describe the physical product and its supported sensor/runtime combination.
6. Create the class.

The Device Class is the reusable product definition, not a customer or rollout tag. It joins hardware compatibility, software, streams, controls, settings, level conversion, customer layout, and the peer baseline for this model.

Fast path: attach a simulator

1. Open the class Software tab.
2. Choose Add container.
3. Keep Use an example selected.
4. Select Grain silo (sim) (grain-silo-sim), Tank level (sim) (tank-level-sim), or Water table (sim) (water-table-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 managed example generates bounded values and publishes them through the local agent broker. When the product path is proven, replace the generator with your hardware adapter while keeping the stable stream IDs.

The class Software tab attaches a simulator and shows whether its Software set is shipping before hardware integration begins.

Production path: keep your existing runtime

Your sensor application may remain a systemd service, Docker workload, or other supervisor-managed process. It does not have to become Dataplicity-managed Software.

Create a stable stream on UI Components, for example:

Field	Value
ID	silo_height_m
Name	Silo fill height
Data type	Number
Unit	m
History	Enabled for the customer decision window

Publish samples to the local broker:

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

{
  "sequence": 1,
  "timestamp_ms": 1710000000000,
  "body": { "value": 4.2 },
  "metadata": { "source": "level-adapter" }
}

The publisher contains no Dataplicity API key. The agent authenticates and delivers the sample. The class stream's History setting controls retention; a publisher storageProfile does not override it.

Part 3: Define the finished product behavior

On UI Components, define only what the customer and support team need:

Product concept	Example definition
Raw sensor value	silo_height_m numeric stream
Explicit warning state	silo_below_low and silo_above_high boolean streams
One-off operation	Run sensor test trigger action
Persistent preference	Reporting interval numeric setting with safe bounds
Level conversion	Silo level input using height, capacity, and calibration

The grain-silo example also publishes silo_low_m and silo_high_m threshold marks.

Use a Level input for the bounded customer quantity. Choose the shape that matches the product: silo, tank, compact tank, battery, wellhead, percentage gauge, or absolute gauge.

Configure what the sensor actually reports and what the customer should see. Do not label height as volume or percentage by changing only the unit. If volume conversion needs a strapping table, the level tile shows a strapping-required state rather than a false derived value.

An action requests work now. A setting records desired state. The device application must validate, apply, and report controls; placing a widget does not implement safe physical behavior.

Part 4: Connect and verify the representative device

1. Open Engineering > Devices.
2. Choose Add device and select SiloSentry Monitor.
3. Copy the current class-specific installer command.
4. Run it on the Linux device.
5. Return to the engineering workspace and wait for Online.
6. Confirm the publisher or simulator is running.
7. Confirm the raw stream changes at the expected cadence.
8. Compare at least one sample with a local sensor reading.

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

Test minimum, normal, and maximum staging values before designing around the middle of the range.

Part 5: Design the customer level page

Open UI Designer and arrange the page in operator decision order:

1. product name, site, serial, and connectivity
2. current level with unit and freshness
3. high/low or normal state beside the level
4. history over the period used for filling or dispatch decisions
5. the bounded sensor-test action
6. reporting preference and support context

Save and preview against the staging device. Check:

• missing before first sample
• stale publisher with device still online
• device offline
• uncalibrated conversion
• low, normal, high, and out-of-range values
• action awaiting reported confirmation
• viewer role with no controls

Part 6: Create the first customer and location

1. Open Customer journey > Customer Portal.
2. Confirm the portal is enabled and has the intended name, logo, and support route.
3. Open Customer journey > Customers.
4. Create the downstream customer and first administrator.
5. In the Customer Portal, create the network that represents the installation location, such as North Farm.
6. Invite a read-only test user as well as the administrator.

Create the downstream customer in the OEM workspace before allocating the first monitor.

A portal network is the current placement boundary required for an active claimed device. It can represent a farm, terminal, building, vehicle, cabinet, or other operating location; it does not have to describe a literal computer network.

Part 7: Allocate the monitor

1. Return to Engineering > Devices.
2. Find the verified staging monitor.
3. Choose Allocate to customer.
4. Select the intended customer.
5. Confirm the audited handover.
6. Sign in to the Customer Portal as the customer administrator.
7. Open Inventory and assign the device to North Farm.

Allocation changes ownership; it does not install the agent, repair the sensor, or make calibration valid. Complete the OEM-side checks before handover.

The customer inventory is the handover surface: the administrator can identify the monitor, see connection state, and place it in the correct operating location.

Part 8: Verify the customer product

Test with separate customer accounts:

Viewer

• sees only the intended customer, locations, and monitors
• can identify the physical product and current location
• sees freshness, current level, history, and warning state
• cannot run the sensor test or change reporting settings
• cannot see Remote Shell, logs, fleet jobs, software, or OEM-wide inventory

Operator

• can perform only the approved sensor test
• can change only bounded settings exposed by the class
• sees useful failure or pending state after requesting an operation

Admin

• can place the monitor only within permitted customer networks

Verify the monitor in the customer's location context, not only from the OEM preview.

Repeat the check with another customer account and prove that the SiloSentry monitor is absent.

Part 9: Replace the simulator safely

When real hardware is ready:

1. keep the stable class stream, action, and setting IDs
2. replace synthetic generation with the tested sensor adapter
3. preserve range validation, units, cadence, and stale behavior
4. build for the target architecture
5. upload and release the new software to staging hardware
6. compare raw and derived values against a trusted local measurement
7. verify OEM and customer views before a bounded rollout

Do not claim that the portal validates the physical installation. Calibration, mounting, ingress protection, power-loss recovery, sensor replacement, and field-service procedures remain part of the product release.

Production handover gate

• [ ] The raw sensor value agrees with a trusted local measurement.
• [ ] Calibration and capacity belong to the correct physical vessel.
• [ ] Missing, stale, uncalibrated, offline, and out-of-range states differ.
• [ ] Units and precision match what the sensor can support.
• [ ] Viewer roles cannot act or change settings.
• [ ] Every action and setting is bounded and validated on the device.
• [ ] The device reconnects after power and network loss.
• [ ] Another customer cannot see the monitor.
• [ ] OEM support can diagnose the unit without exposing engineering controls.
• [ ] 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
• SiloSentry product story