Overview

If you don't have access to physical sensors or want to perform controlled debugging, the Sensor Emulator API gives you the ability to create and experiment with devices at will. An emulated sensor is designed to have all the features of a real sensor, making it a valuable tool.

• Explore DT Studio without the need for real sensors.

• Can be interacted with through the REST API.

• Emit any kind of event type at will by simply clicking a button.

• Generate events in your CI flow to automate integration tests.

You can find a list of all available emulator endpoints at our REST API Reference.

Prerequisites

• Service Account Creating, deleting, and interacting with emulated devices require that your User or Service Account has been granted the role of Project Developer or higher.

Creating an Emulated Device

To illustrate the process, an emulated temperature sensor with a given Device Name, Device Type, and Label called group-number is created as an example.

DT Studio

REST API

DT Studio

In DT Studio, navigate to the project in which you want to create the emulated sensor. In the left-most menu, locate the API Integrations -> Emulator page. Click Create Device.

Under the new device creation page, select a Device Type. A Device name and labels are optional but can be useful when managing several emulated devices at once.

Remember to Save New Emulated Device.

REST API

Send a POST request to:

https://emulator.d21s.com/v2/projects/<PROJECT_ID>/devices

A request body with the following parameters is required.

{
    "type": "temperature"
}

A list of all available parameters can be found in our REST API Reference.

Example Usage

Using cURL with a Service Account for authentication, the following example creates a new emulated temperature sensor with a given name and a "group-number" label.

curl -X POST "https://emulator.d21s.com/v2/projects/<PROJECT_ID>/devices" \
    -u "<SERVICE_ACCOUNT_KEY_ID>":"<SERVICE_ACCOUNT_SECRET>" \
    -d '{"type": "temperature", "labels": {"name": "my-emulated-sensor", "group-number": "99"}}'

Emitting Emulated Events

Events can be emitted at will using an emulated device, useful for debugging and testing.

DT Studio

REST API

DT Studio

In DT Studio, navigate to the project containing your emulated sensors. In the left-most menu, locate the API Integrations -> Emulator page. Click on your emulated device.

Under the details page of your emulated device, select the Event Type and related value you wish to emit. When set, click Send Event for immediate effect.

REST API

Send a POST request to:

https://emulator.d21s.com/v2/projects/<PROJECT_ID>/devices/<DEVICE_ID>:publish

A request body with the following parameter is required, where the <EVENT_TYPE> should be one supported by the emulated sensor type, as listed here.

{
    "<EVENTY_TYPE>": {
        "value": <VALUE>
    }
}

Example Usage

Using cURL with a Service Account for authentication, the following example emits a temperature event from the specified emulated temperature sensor.

curl -X POST "https://emulator.d21s.com/v2/projects/<PROJECT_ID>/devices/<DEVICE_ID>:publish" \
    -u "<SERVICE_ACCOUNT_KEY_ID>":"<SERVICE_ACCOUNT_SECRET>" \
    -d '{"temperature": {"value": 22}}'