# Emulator API

## Overview

If you don't have access to physical sensors and want to test our services, 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 for experimentation or debugging.

* Explore DT Studio without the need for real sensors.
* It can be interacted with through the REST API.
* Emit any 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](https://developer.disruptive-technologies.com/api/emulator).

## 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

{% tabs %}
{% tab title="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**.

![](https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MR5PbKbz-q3w3qIO6MH%2F-MTZbrEyUaI2b5uwCOVR%2F-MTZeZj5ds1k6bkI0Mc5%2Femulator-page.png?alt=media\&token=088511ed-dcfe-428f-a197-8b1cb58692fc)

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.

![](https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MR5PbKbz-q3w3qIO6MH%2F-MUYpK0yh925VTaXNGfV%2F-MUYqNepCnSAsRST3E6R%2Femu-sensor-device-info.png?alt=media\&token=25d54dac-f225-42b9-bee1-5e2dfa6d5e76)

Remember to **Save New Emulated Device**.
{% endtab %}

{% tab title="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.

```javascript
{
    "type": "temperature"
}
```

A list of all available parameters can be found in our [REST API Reference](https://developer.disruptive-technologies.com/api/emulator).

#### 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.

```bash
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"}}'
```

{% endtab %}

{% tab title="Python API" %}
Once the package is installed and authenticated as described in the [Python API Reference](https://developer.disruptive-technologies.com/api/libraries/python/index.html), a new Emulated Device can be created by calling the following resource method.

[disruptive.Emulator.create\_device()](https://developer.disruptive-technologies.com/api/libraries/python/client/resources/emulator.html#create-device)

#### Example Usage

Using our Python API with Service Account credentials for authentication, the following example creates a new Emulated Temperature Device.

```python
import disruptive as dt

device = dt.Emulator.create_device(
    project_id='<PROJECT_ID>',
    device_type=dt.Device.TEMPERATURE,
)

print(device)
```

{% endtab %}
{% endtabs %}

## Emitting Emulated Events

Events can be emitted at will using an emulated device.

{% tabs %}
{% tab title="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.

![](https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MR5PbKbz-q3w3qIO6MH%2F-MT_3467Rpwf27cy2xfC%2F-MT_5vw_yt5v7B5jhAif%2Femit-emulated-page.png?alt=media\&token=25dc1296-e4a8-44b3-aed6-f38f3d3f38ef)

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.

![](https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MR5PbKbz-q3w3qIO6MH%2F-MT_3467Rpwf27cy2xfC%2F-MT_6kjM6fneCSdLJK2_%2Femit-emulated.png?alt=media\&token=ba17879a-ee0a-4843-98e5-37008657183d)
{% endtab %}

{% tab title="REST API" %}
Send a **POST** request to:

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

The body of the POST request should be the [event](https://docs.developer.disruptive-technologies.com/concepts/events#variations) to be published. The type of the published event must match the device type of the emulated event. For example, an emulated `temperature` sensor can't send `objectPresent` events. An overview of which events types are available for a given device type can be found [here](https://docs.developer.disruptive-technologies.com/concepts/devices#wireless-sensors).

**Note:** The `updateTime` field is optional for all event types, and defaults to now.

#### Example Usage

As an example, to publish a `temperature` event, include the following body in the POST request.

```json
{
    "temperature": {
        "value": 42
    }
}
```

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

```bash
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": 42}}'
```

{% endtab %}

{% tab title="Python API" %}
Once the package is installed and authenticated as described in the [Python API Reference](https://developer.disruptive-technologies.com/api/libraries/python/index.html), an emulated event can be published by calling the following resource method.

[disruptive.Emulator.publish\_event()](https://developer.disruptive-technologies.com/api/libraries/python/client/resources/emulator.html#publish-event)

#### Example Usage

Using our Python API with Service Account credentials for authentication, the following example published a new [motion event](https://docs.developer.disruptive-technologies.com/concepts/events#motion-event) to an emulated [motion sensor](https://docs.developer.disruptive-technologies.com/concepts/devices#motion-sensor).

```python
import disruptive as dt

dt.Emulator.publish_event(
    device_id='<DEVICE_ID>',
    project_id='<PROJECT_ID>',
    data=dt.events.Motion(
        state='MOTION_DETECTED',
    ),
)
```

{% endtab %}
{% endtabs %}