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. Choose Create firmware and pin a version.
7. Target a staging device, or Make current / Pin to tags.
8. On UI Components, confirm the example streams, then place widgets in UI Designer.
9. Open that device in the OEM view and customer portal.

Dataplicity has already built and published the example image. Add example attaches it without an OCI upload.

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. Target a staging device and 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_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 /dev/video0 source. Keep it off the first portal-learning path unless the product page needs a video widget.

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

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. pin it to staging firmware
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
• Use the customer portal for your product