Build a customer-operated level monitor

A level sensor becomes much more interesting when a customer can open a portal, see the latest reading, change a threshold, and watch an alert appear.

This workshop takes you through that whole journey. The example is a fictional grain product called SiloSentry Monitor, but the same pattern works for a tank, bin, well, battery, or any other bounded quantity.

The refreshed SiloSentry reference uses the current application and shared portal widgets with simulated readings.

For a continuous business example and the current Applications workspace, see SiloSentry. Its calibration uses raw millimetres; the simple publisher below initially reports metres, so convert the publisher before connecting it to that kit as described in step 8.

Where operators use it

Open the yard from Networks, then open the silo workplace. The kit publishes a capacity composition page (silo-capacity) that stacks the shared semantic facets for each silo record: current fill, volume history (with band guides and alarm overlays when streams are live), and optional watch camera. Open an enabled sensor and use Controls for this silo's level and vendor controls. The yard network is still the entry point for placement and site-wide work.

The monitor’s Controls page combines generic sensor widgets with the same calibrated product view used in the application.

What this tutorial actually does

You can run the complete Dataplicity path with a simulator: stream transport, customer records, threshold operation, rule, alert, and portal. The simulator does not prove sensor accuracy, vessel calibration, or a physical filling outcome. Those remain part of your hardware product and field qualification.

By the end you will have a reusable Device Class, one representative device, a customer-facing level page, and a Silo Product Application that combines customer thresholds with the latest reading.

What you need

• a supported Linux device with the Dataplicity agent
• a level sensor or staging simulator
• access to Engineering > Device classes
• access to Engineering > Software > Containers and I/O, and the class UI Designer
• access to Customer journey > Customer Portal and Customers
• a separate customer email address for portal testing

If the sensor is not ready, use grain-silo-sim, tank-level-sim, or water-table-sim. You can prove the product journey today and swap in the real adapter later.

1. Prove the measurement locally

Before adding the cloud, make your Linux application read the sensor repeatedly. Write down:

Decision	Example
Raw measurement	4.2 m from the sensor datum
Cadence	Every 30 seconds
Plausible range	0 m to 12 m
Missing-reading behaviour	Keep the last value only for a defined stale window
Calibration source	Empty/full points or an approved strapping table
Customer quantity	Height, percentage, volume, voltage, or pressure

Keep the raw measurement. A cylindrical tank may have a simple conversion, but an irregular silo can need a strapping artefact and a well may use an inverted scale. Raw data helps support distinguish sensor trouble from conversion trouble.

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 of your representative device.
5. Describe the supported sensor and runtime.
6. Create the class.

A Device Class is the reusable product definition. It brings together hardware compatibility, software, streams, controls, settings, level conversion, and the customer layout.

Fast path: attach a simulator

Open Engineering > Software > Containers, select the Device Class, choose Add container, and select Grain silo (sim), Tank level (sim), or Water table (sim). Add the example and assign the current Software Build to a tagged staging cohort or select it as the class default.

The example publishes bounded synthetic values through the local agent broker. When the hardware adapter is ready, keep the stable stream IDs and replace only the generator.

The current top-level Software workspace is where you select a Device Class and attach released container software, including a simulator used to prove a customer journey.

Bring your own runtime

Your sensor application can remain a systemd service, Docker workload, or another supervised process. Create a stream under Engineering > Software > I/O:

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

Publish a sample 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 needs no Dataplicity API key. The local agent authenticates and delivers the sample.

3. Describe the product behaviour

Under Engineering > Software > I/O, add only the things your customer and support team need:

Product idea	Example
Raw value	silo_height_m numeric stream
Warning state	silo_below_low and silo_above_high booleans
One-off action	Run sensor test
Persistent setting	Reporting interval with safe bounds
Customer quantity	Level input using height, capacity, and calibration

Choose the level shape that matches the product: silo, tank, compact tank, battery, wellhead, percentage gauge, or absolute gauge.

Do not turn height into “volume” by changing the label. If the conversion needs a strapping table, configure one or show that calibration is incomplete.

An action asks the device to do something now. A setting records desired state. Your device application must validate, apply, and report both safely.

4. Connect 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. Wait for the device to become Online.
6. Check that the publisher or simulator is running.
7. Watch the raw stream change at the expected cadence.
8. Compare one sample with a trusted local reading.

Treat the installer command as a secret. Keep it out of source control, screenshots, and support tickets.

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

5. Design the customer level page

For the application view, use Applications → Customer app → Workspace pages and the reusable Capacity layout bound to the Silo model. The kit supplies the capacity, history, threshold/freshness and optional camera facets; you do not need a custom silo dashboard component. A camera remains absent until it is assigned.

Use the Device Class UI Designer only for additional generic device Controls such as a raw measurement metric, chart or bounded device setting. Arrange the customer experience in decision order: name/site, trusted reading with unit, operating thresholds, useful history, then permitted controls.

Try missing, stale, offline, uncalibrated, low, normal, high and out-of-range states. Check that a viewer cannot change settings or invoke controls.

6. Create the first customer and location

Open Customer journey > Customer Portal and check the portal name, branding, and support route. Then open Customers, create the downstream customer, and invite an administrator plus a read-only test user.

Create the downstream customer before allocating the first monitor.

In the Customer Portal, create a network such as Ashton Mill. Here a network is the placement boundary for products; it can represent a farm, building, vehicle, or cabinet.

7. Allocate the monitor

Return to Engineering > Devices, choose the verified monitor, and allocate it to the customer. Sign in as the customer administrator, open Devices, and place the Ready monitor in Ashton Mill. Network placement makes it Enabled and eligible for the yard-level silo workplace.

The reference monitors have both been placed at Ashton Mill. Check identity, placement and connection state before handing them over.

Verify the monitor from the customer's place, not only from an OEM preview.

Allocation changes ownership. It does not install the agent, repair a sensor, or validate calibration, so complete those checks first.

8. Add the silo application

Open Engineering → Applications and create the application from the shipped Silo monitoring example. Map the sensor role to your Device Class and its raw height stream. Review the current tabs: Overview, Customer app, Automations, Data, and Test & publish.

Match the measurement contract first. The Silo kit’s height and strapping fields use millimetres. The silo_height_m publisher and Grain silo simulator above report metres. Convert metres to millimetres in your publisher before mapping it to this kit, or use a separately verified millimetre publisher. For the current SiloSentry reference, the channel is level and its unit is mm. Changing the stream label alone does not convert values.

Under Data, review the Silo model, its Device Class binding and the Strapping row model. Under Customer app → Workspace pages, inspect the reusable Capacity layout and its Silo binding. Under Automations, review low/high band alerts, stale telemetry, permitted actions and their recovery conditions.

The page is a reusable layout bound to business data. The designer preview uses illustrative values.

Use Test & publish to validate and publish an immutable version, attach it to the intended portal and confirm the customer instance is on that version. Draft changes do not automatically upgrade a customer’s running version.

For Ashton Mill, bind SS-AM-01 to North Silo, select input 1, set capacity 120 m³ and low threshold 25 m³. Add calibration rows for this silo: 0 mm → 0 m³, 2,500 mm → 30 m³, 5,000 mm → 60 m³, and 10,000 mm → 120 m³. A sample near 5,683.3 mm gives approximately 68.2 m³ by interpolation. These are illustrative calibration points, not a validated vessel shape.

The shared capacity and history widgets read the configured stream and this silo’s calibration. Do not display raw millimetres as volume when calibration is missing. Bind an optional camera explicitly; sharing a network does not pair it with the silo.

The sensor input and vessel-specific calibration determine the product quantity.

The kit publishes Work and Exceptions pages alongside its capacity view. Authoring details for facets and overlays are in Semantic composition.

9. Let the customer change the threshold

Open the Silo record and edit the low-volume threshold on that record. The first-class editor is the bounded configuration surface; the current product does not expose a separate “Set low threshold” operation form.

Reload the record and check that the stored threshold changed while the stream-derived height and volume stay read-only.

Changing the threshold does not change the sensor measurement or its calibration.

Test three roles before handover. A viewer should see readings and history but no controls. An operator should see only approved actions and bounded settings. An administrator should place the monitor only within the customer's networks. Then sign in as a second customer and confirm the monitor is absent.

10. Verify the customer product

Repeat the key journey as each role. Viewer roles cannot act or change settings; operators can use only approved controls; administrators can manage placement. Confirm the current value, history, threshold, and alert all belong to the intended customer. Exercise an old sensor observation while the monitor stays connected, then an old heartbeat, then a fresh observation and heartbeat. Check that the stale alert resolves while unrelated low-level conditions remain.

Choose Account → Appearance → Light or Dark and repeat the inspection. The chart, forms, status colours and branding should remain readable in either theme. See the current SiloSentry scenario for captures.

11. Replace the simulator

When real hardware is ready:

1. keep the stable stream, action, and setting IDs
2. replace synthetic values with the tested sensor adapter
3. preserve range checks, units, cadence, and stale behaviour
4. build for the target architecture
5. release to staging hardware
6. compare raw and derived values with trusted local measurements
7. verify both OEM and customer views before rollout

The portal cannot validate mounting, calibration, ingress protection, power recovery, or sensor replacement. Include those in your product release and field-service process.

Production handover gate

• Compare raw sensor values with a trusted local measurement.
• Match calibration and capacity to the correct vessel.
• Distinguish missing, stale, uncalibrated, offline, and out-of-range states.
• Use honest units and precision.
• Bound and validate every device action and setting.
• Test power and network recovery.
• Check viewer, operator, and administrator roles.
• Prove another customer cannot see the monitor.
• Document replacement and recalibration.

Related

• Build your first connected product
• Device Classes
• Device class streams
• Design the customer product UI
• Semantic composition
• Semantic widget catalogue
• Example simulators
• Customer Portal
• SiloSentry product story