Example simulators

Example simulators are prefab OCI images for learning the Device Class software and stream workflow. They generate bounded synthetic values and publish them through the local Dataplicity agent broker.

They are not hardware drivers and do not prove that a real tank, fridge, water-table sensor, silo, or HVAC controller is integrated safely.

Choose a learning path

Attach a managed example

Use this path to see the end-to-end result quickly:

1. Open the Device Class Software tab.
2. Choose Add container.
3. Keep Use an example selected.
4. Select a simulator and review its supported environment values.
5. Choose Add example.
6. When a published release exists, attach can also create and ship the current Software set automatically. Otherwise create firmware after a release is available.
7. Use Make current for the class default, or Pin to tags for a staged cohort. Tag staging hardware before using the second option.
8. On UI Components, confirm the seeded streams and widgets, then place them in UI Designer.
9. Open that device in the OEM view and customer portal.

Dataplicity has already built the example image. Add example attaches it without an OCI upload and seeds its recommended streams and widgets. If the environment has no published release for that example, attach fails until one is available.

Download and upload an example

Use this path to practise the same OCI workflow required by your own image:

1. Attach the example as above, or create an empty container with Create new.
2. Open the container and choose Upload version.
3. For a prefab example that still has no version, choose Download a practice .tar in that dialog.
4. Upload the archive as Container image (.tar). Accepted suffixes are .tar, .tar.gz, and .tgz.
5. Choose Create firmware and pin the version.
6. Choose Make current, or Pin to tags for a tagged staging cohort, then verify its streams.

The downloaded archive is a built OCI image, not the example source code. Use Build a class container when adapting the publisher for real hardware.

Example catalogue

Key	What it simulates	Primary stream	Unit
tank-level-sim	Tank volume with alarm marks	tank_litres	L
water-table-sim	Water-table depth	water_table_m	m
grain-silo-sim	Grain-silo fill height	silo_height_m	m
fridge-temp-sim	Fridge temperature	fridge_temp_c	°C
hvac-sim	HVAC space temperature and mode	hvac_temp_c	°C
video-gen-sim	Synthetic video chunks and a live JPEG	camera_video and camera_events	n/a

video-gen-sim is a capture-and-buffer example, not a camera driver. It writes bounded MP4 chunks for the agent to upload and can optionally use a real CSI or V4L2 camera. Keep it off the first portal-learning path unless the product page needs a video widget. For the full camera-to-customer walkthrough, see Turn your Linux device into a product you can sell.

Tank level example

The tank simulator is the most complete threshold example. Configure marks in ascending order:

1. Low-low (LOW_LOW_L) - critical empty or pump protection
2. Low (LOW_LEVEL_L) - early low warning
3. Safe fill (SAFE_FILL_L) - normal high or stop-fill point
4. High-high (HIGH_HIGH_L) - critical overfill
5. Capacity (CAPACITY_L) - maximum simulated volume

The required relationship is:

0 <= LOW_LOW_L <= LOW_LEVEL_L <= SAFE_FILL_L <= HIGH_HIGH_L <= CAPACITY_L

The example also publishes helper streams:

Purpose	Stream
Low-low mark	tank_low_low_l
Low mark	tank_low_level_l
Safe-fill mark	tank_safe_fill_l
High-high mark	tank_high_high_l
Below low-low	tank_below_low_low
Below low	tank_below_low
Above safe fill	tank_above_safe
Above high-high	tank_above_high_high

Use those helpers to build an understandable operator page when a dedicated gauge with drawn marks is not available.

Other example settings

Example	Settings
Water table	MIN_M, MAX_M
Grain silo	CAPACITY_M, HIGH_M, LOW_M
Fridge	SETPOINT_C, HIGH_ALARM_C, LOW_ALARM_C
HVAC	SETPOINT_C, DEADBAND_C
Video	VIDEO_GEN_MAX_DISK_PERCENT, CAMERA_TESTSRC

Only tank threshold marks are configured while attaching the example. Other values use the example's defaults unless you change them on the attached container, or in your replacement image, before rollout.

Validate settings before releasing firmware. A simulator accepting a value does not prove that the same value is safe for physical equipment.

Replace the simulator

When the page and portal flow are understood:

1. keep the class stream identifiers that form the product contract
2. keep the released local-broker publisher client
3. replace the synthetic generator with a tested hardware adapter
4. preserve units, range validation, and stale-data behaviour
5. build for the target architecture
6. upload a new software version
7. use Pin to tags for a tagged staging cohort
8. verify OEM and portal views before rollout

The production image still publishes only to the local agent broker. Do not copy device credentials into the replacement image.

Related

• Build a class container
• Device class streams
• Design a device class page
• Turn your hardware into a customer SaaS product
• Turn your Linux device into a product you can sell