# Events

## Event Types

The following table lists all event types and the triggers that generate them. An overview of event types per device can be found on the [Devices](https://docs.developer.disruptive-technologies.com/concepts/devices) page.

<table data-header-hidden><thead><tr><th>Event Name</th><th width="221">Event Type</th><th>Trigger</th></tr></thead><tbody><tr><td>Event Name</td><td>Event Type</td><td>Trigger</td></tr><tr><td><a href="#touch-event">Touch</a></td><td><code>touch</code></td><td>When touched.</td></tr><tr><td><a href="#temperature-event">Temperature</a></td><td><code>temperature</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a> and when touched.</td></tr><tr><td><a href="#object-present-event">Object Present</a></td><td><code>objectPresent</code></td><td><code>PRESENT</code>/<code>NOT_PRESENT</code> state change.</td></tr><tr><td><a href="#humidity-event">Humidity</a></td><td><code>humidity</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a> and when touched.</td></tr><tr><td><a href="#object-present-count-event">Object Present Count</a></td><td><code>objectPresentCount</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a>.</td></tr><tr><td><a href="#touch-count-event">Touch Count</a></td><td><code>touchCount</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a>.</td></tr><tr><td><a href="#water-present-event">Water Present</a></td><td><code>waterPresent</code></td><td><code>PRESENT</code>/<code>NOT_PRESENT</code> state change.</td></tr><tr><td><a href="#co2-event">CO2</a></td><td><code>co2</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a>.</td></tr><tr><td><a href="#co2-event-1">Pressure</a></td><td><code>pressure</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a>.</td></tr><tr><td><a href="#motion-event">Motion</a></td><td><code>motion</code></td><td><code>MOTION_DETECTED</code> / <code>NO_MOTION_DETECTED</code> state change.</td></tr><tr><td><a href="#desk-occupancy-event">Desk Occupancy</a></td><td><code>deskOccupancy</code></td><td><code>OCCUPIED</code> / <code>NOT_OCCUPIED</code> state change.</td></tr><tr><td><a href="#contact-event">Contact</a></td><td><code>contact</code></td><td><code>OPEN</code> / <code>CLOSED</code> state change.</td></tr><tr><td><a href="#probe-wire-status-event">Probe Wire Status</a></td><td><code>probeWireStatus</code></td><td>Probe wire state change.</td></tr><tr><td><a href="#battery-status-event">Battery Status</a></td><td><code>batteryStatus</code></td><td>See event details.</td></tr><tr><td><a href="#network-status-event">Network Status</a></td><td><code>networkStatus</code></td><td>Every <a href="#periodic-heartbeat">periodic heartbeat</a> and together with trigger-based events.</td></tr><tr><td><a href="#labels-changed-event">Labels Changed</a></td><td><code>labelsChanged</code></td><td>When a device label is created, modified, or removed.</td></tr><tr><td><a href="#connection-status-event">Connection Status</a></td><td><code>connectionStatus</code></td><td>Changes in connection type.</td></tr><tr><td><a href="#ethernet-status-event">Ethernet Status</a></td><td><code>ethernetStatus</code></td><td>Changes in the ethernet connection.</td></tr><tr><td><a href="#cellular-status-event">Cellular Status</a></td><td><code>cellularStatus</code></td><td>Changes in the cellular connection.</td></tr></tbody></table>

## Structure

All event types available through our API use the same outer layer structure, shown in the snippet below, where event metadata is found. Information specific to each [event type](#types) is found in the `data` field.

```javascript
{
    "eventId": "<EVENT_ID>",
    "targetName": "projects/<PROJECT_ID>/devices/<DEVICE_ID>",
    "eventType": "<EVENT_TYPE>",
    "data": {
            "See each event type individually below."
        }
    },
    "timestamp": "2024-12-06T13:15:01.576753Z"
}
```

<table data-header-hidden><thead><tr><th>Field</th><th width="194.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>eventId</code></td><td><code>string</code></td><td>The unique identifier of the Event. This can be used to deduplicate events in case the same event is published multiple times.</td></tr><tr><td><code>targetName</code></td><td><code>string</code></td><td>The resource name of the source device. Includes both the identifier of the project the device is currently in, and the identifier of the device itself.</td></tr><tr><td><code>eventType</code></td><td><code>string</code></td><td>The <a href="#event-types">event type</a>.</td></tr><tr><td><code>data</code></td><td><code>struct</code></td><td>Includes the event data and is specific for each <code>eventType</code>. See the <a href="#event-types">event types</a> below for a detailed description of each field that can be found here.</td></tr><tr><td><code>timestamp</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

There are four places where events can be encountered in our services.

1. The `reported` field of a [Device](https://docs.developer.disruptive-technologies.com/devices#device-structure) when [listing devices through REST API](https://developer.disruptive-technologies.com/api#/Devices%20%26%20Labels/get_projects__project__devices).
2. When pushed to a client using the [event stream REST API endpoint](https://developer.disruptive-technologies.com/api#/Live%20Events%20Streaming%20API/get_projects__project__devices_stream).
3. When fetching historical data through the [event history REST API endpoint](https://developer.disruptive-technologies.com/api#/Event%20History/get_projects__project__devices__device__events).
4. When pushed by a [Data Connector](https://docs.developer.disruptive-technologies.com/data-connectors/introduction-to-data-connector) to another server.

### Periodic Heartbeat

All sensors send a [Network Status](#network-status-event) event at a predefined interval depending on sensor type. Depending on the sensor type, this heartbeat may be accompanied by additional events. For instance, the [Temperature sensor](https://docs.developer.disruptive-technologies.com/devices#temperature-sensor) will also send a [Temperature event](#temperature-event) every heartbeat.

![](https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MR5PbKbz-q3w3qIO6MH%2F-MTaiVan0uUtwjOwl8b9%2F-MTalb-ddOy0UsSIVjyp%2FEventsTimeline.svg?alt=media\&token=3eec9412-f23c-41b7-8c57-df8cb48c1085)

### Triggered Events

A few of our sensors are designed to send events immediately at some trigger. These are sent in addition to, but independent of, the [periodic heartbeat](#periodic-heartbeat).

* [Object Present Event](#object-present-event) for [Proximity Sensors](https://docs.developer.disruptive-technologies.com/devices#proximity-sensor).
* [Water Present Event](#water-present-event) event for [Water Detector Sensors](https://docs.developer.disruptive-technologies.com/devices#water-detector-sensor).
* [Touch Event](#touch-event) for [Touch Sensors](https://docs.developer.disruptive-technologies.com/devices#touch-sensor).
* [Motion Event](#motion-event) for Motion Sensors.
* [Desk Occupancy Event](#desk-occupancy-event) for Desk Occupancy Sensors.

A [Network Status Event](#network-status-event) accompanies each triggered event.

![](https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MR5PbKbz-q3w3qIO6MH%2F-MUmJzY9qsCuMANFPp_t%2F-MUmNQsXmWv-fivGJLi8%2FProxEventsTimeline.svg?alt=media\&token=514955a8-647f-4c7d-9a20-5b8ba63ca6b5)

### Timestamps

Here are a few notes regarding timestamps and how they are presented in our services.

#### Timezone Offset

All timestamps fetched using our APIs are always given in UTC and must be accounted for. DT Studio will, however, always shows timestamps depending on user locale.

#### Format

The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format with [fractional seconds](https://datatracker.ietf.org/doc/html/rfc3339#section-5.3) is used for our timestamps. This is an internet-specific profile of the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) specification, and an example can be seen below.

* `2024-12-06T08:13:15.361624Z`.

#### Variations

A result of how our events are structured is that two different timestamp fields can be found in each event when fetching them through our API. The `timestamp` and `updateTime` fields are located in the outer layer and `data` field of an event respectively, but will always contain the same value.&#x20;

You may use either `timestamp` or `updateTime` when deciding when an event was received.

A third type, `sampleTime`, can only be found within the [Temperature Event](#temperature-event). These represent the timestamps of inter-heartbeat samples and are estimated by our cloud. [Read more](https://docs.developer.disruptive-technologies.com/usage-examples/2.gen-temperature-sensor#sample-timestamp-accuracy).

## Event Details

The following event types are available in our APIs. A table of which event types are available per device type and their triggers can be found on the [Devices](https://docs.developer.disruptive-technologies.com/concepts/devices) page.

### Touch Event

* **Event Type:** `touch`
* **Trigger:** When touched.

Most of our [devices](https://docs.developer.disruptive-technologies.com/concepts/devices) will send a [Touch Event](#touch-event) when touched. This can be useful for identification.

An exception to this is [Counting Touch Sensors](https://docs.developer.disruptive-technologies.com/devices#counting-touch-sensor), which aggregate each touch into a [Touch Count Event](#touch-count-event) sent every [periodic heartbeat](#periodic-heartbeat). To force a single [Touch Event](#touch-event), hold your finger on the sensor for 3 seconds.

The following snippet shows the event `data` field content of a `touch` event.

```javascript
{
    "touch": {
        "updateTime": "2024-12-06T08:13:15.361624Z"
    }
}
```

<table data-header-hidden><thead><tr><th width="192.7876885297">Field</th><th width="150">Type</th><th width="325.6142100518815">Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Temperature Event

* **Event Type:** `temperature`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat) or when touched.&#x20;
  * **Note:** [2nd Gen Temperature Sensors](https://support.disruptive-technologies.com/hc/en-us/articles/4405644706194-Temperature-Sensor-2nd-Gen-) and [3rd Gen Temperature Sensors](https://support.disruptive-technologies.com/hc/en-us/articles/9389983018268-Temperature-Sensor-3rd-Gen-) will only send temperature on heartbeats, and not when touched.

The following snippet shows the event `data` field content of a `temperature` event.

```javascript
{
    "temperature": {
        "value": 24.9,
        "samples": [
            {
                "value": 24.9,
                "sampleTime": "2024-12-06T08:15:48.223962Z"
            },
            {
                "value": 24.3,
                "sampleTime": "2024-12-06T08:15:18.318751Z"
            },
            {
                "value": 24.4,
                "sampleTime": "2024-12-06T08:14:48.872918Z"
            },
            ...
        ],
        "updateTime": "2024-12-06T08:15:18.318751Z",
        "isBackfilled": false
    }
}
```

<table data-header-hidden><thead><tr><th width="261.51680556917614">Field</th><th width="150">Type</th><th width="296.2868285283635">Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>value</code></td><td><code>float</code></td><td>Temperature value in Celsius.</td></tr><tr><td><code>samples</code></td><td><code>[struct]</code></td><td>A list of temperature samples and timestamps sampled since the previous heartbeat, ordered newest-to-oldest. Its length is equal to the configured samples per heartbeat, which is 1 by default. The first item in the array will always have the same value as the outer <code>value</code> and <code>updateTime</code> fields. </td></tr><tr><td><code>samples[].value</code></td><td><code>float</code></td><td>Sample temperature value in Celsius.</td></tr><tr><td><code>samples[].sampleTime</code></td><td><code>string</code></td><td>Estimated sample timestamp on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format. <a href="../usage-examples/2.gen-temperature-sensor#sample-timestamp-accuracy">Read more</a>. </td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr><tr><td><code>isBackfilled</code></td><td><code>bool</code></td><td>Indicates if the temperature event is backfilled. The backfill feature is supported for <a href="https://support.disruptive-technologies.com/hc/en-us/articles/11432439857948-Temperature-Probe-Sensor">Temperature Probe Sensors</a> and <a href="https://support.disruptive-technologies.com/hc/en-us/articles/9389983018268-Temperature-Sensor">Temperature Sensors with Data Backfill</a>. When this field is <code>true</code>, the temperature value was measured while the sensor was out of reach of an online Cloud Connector, and has been backfilled automatically after getting back online. See the <a href="https://support.disruptive-technologies.com/hc/en-us/articles/12707591585564-How-does-Data-Backfill-work">Backfill page</a> in our Help Center for more information about Data Backfill.</td></tr></tbody></table>

#### Samples per Heartbeat Configuration

Our 2nd and 3rd generation temperature sensors can be configured to sample up to 30 samples per [heartbeat](#periodic-heartbeat). If enabled, these inter-heartbeat samples will be contained in a list found under the `samples` field, accompanied by a timestamp called `sampleTime`. By default, if no configuration is enabled, this list contains only the single temperature value and timestamp found in the temperature event. [Read more](https://docs.developer.disruptive-technologies.com/concepts/usage-examples/2.gen-temperature-sensor).

### Object Present Event

* **Event Type:** `objectPresent`
* **Trigger:** When an object in close proximity appears or disappears.

The following snippet shows the event `data` field content of an `objectPresent` event.

```javascript
{
    "objectPresent": {
        "state": "NOT_PRESENT",
        "updateTime": "2024-12-06T08:37:10.711412Z"
    }
}
```

<table data-header-hidden><thead><tr><th width="172">Field</th><th width="150">Type</th><th width="349.59003831417624">Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>state</code></td><td><code>string</code></td><td>Indicates whether an object is <code>"PRESENT"</code> or <code>"NOT_PRESENT"</code>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Humidity Event

* **Event Type:** `humidity`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat) or when touched.

The following snippet shows the event `data` field content of a `humidity` event.

```javascript
{
    "humidity": {
        "temperature": 22.45,
        "relativeHumidity": 17,
        "samples": [
            {
                "temperature": 22.45,
                "relativeHumidity": 17,
                "sampleTime": "2024-12-06T06:13:46.369000Z"
            },
            {
                "temperature": 22.35,
                "relativeHumidity": 18,
                "sampleTime": "2024-12-06T06:12:45.897000Z"
            }
        ],
        "updateTime": "2024-12-06T06:13:46.369000Z",
        "isBackfilled": false
    }
}
```

<table data-header-hidden><thead><tr><th>Field</th><th width="150">Type</th><th width="320">Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>temperature</code></td><td><code>float</code></td><td>Temperature value in Celsius.</td></tr><tr><td><code>relativeHumidity</code></td><td><code>float</code></td><td>Relative humidity in percent.</td></tr><tr><td><code>samples</code></td><td><code>[struct]</code></td><td>A list of temperature and humidity samples since the previous heartbeat, ordered newest-to-oldest. Its length is equal to the configured samples per heartbeat, which is 1 by default. The first item in the array will always have the same value as the outer <code>temperature</code> and <code>relativeHumidity</code> fields. Only the <a href="https://support.disruptive-technologies.com/hc/en-us/articles/17167989869724-Temperature-and-Humidity-sensor">Temperature &#x26; Humidity Sensor</a> supports configuring the number of samples per heartbeat.</td></tr><tr><td><code>samples[].temperature</code></td><td><code>float</code></td><td>The sampled temperature value in Celsius.</td></tr><tr><td><code>samples[].relativeHumidity</code></td><td><code>float</code></td><td>The sampled relative humidity value in percent.</td></tr><tr><td><code>samples[].sampleTime</code></td><td><code>string</code></td><td>Estimated sample timestamp on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format. <a href="https://disruptive.gitbook.io/docs/concepts/usage-examples/2.gen-temperature-sensor#sample-timestamp-accuracy">Read more</a>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr><tr><td><code>isBackfilled</code></td><td><code>bool</code></td><td>Indicates if the humidity event is backfilled. This feature is supported for the <a href="https://support.disruptive-technologies.com/hc/en-us/articles/17167989869724-Temperature-and-Humidity-sensor">Temperature &#x26; Humidity Sensor</a>. When this field is <code>true</code>, the humidity and temperature value was measured while the sensor was out of reach of an online Cloud Connector, and has been backfilled automatically after getting back online. See the <a href="https://support.disruptive-technologies.com/hc/en-us/articles/12707591585564-How-does-Data-Backfill-work">Backfill page</a> in our Help Center for more information about Data Backfill.</td></tr></tbody></table>

### Object Present Count Event

* **Event Type:** `objectPresentCount`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat).

This event aggregates [Object Present Events](#object-present-event) and sends the total lifetime count every periodic heartbeat.

The following snippet shows the event `data` field content of an `objectPresentCount` event.

```javascript
{
    "objectPresentCount": {
        "total": 4176,
        "updateTime": "2024-12-06T08:23:43.209000Z"
    }
}
```

<table data-header-hidden><thead><tr><th width="189.0447030006124">Field</th><th width="150">Type</th><th width="338.52800308999616">Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>total</code></td><td><code>int</code></td><td>The total number of times the sensor has detected the appearance or disappearance of an object over its lifetime. This can currently not be reset.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Touch Count Event

* **Event Type:** `touchCount`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat).

This event aggregates each [Touch Event](#touch-event) and sends the total lifetime count every periodic heartbeat. To force a single [Touch Event](#touch-event) to be sent, hold your finger on the sensor for 3 seconds.

The following snippet shows the event `data` field content of a `touchCount` event.

```javascript
{
    "touchCount": {
        "total": 469,
        "updateTime": "2024-12-06T08:25:21.604000Z"
    }
}
```

<table data-header-hidden><thead><tr><th width="199.0084518470103">Field</th><th width="150">Type</th><th width="325.49125126709043">Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>total</code></td><td><code>int</code></td><td>The total number of times the sensor has been touched over its lifetime. This can currently not be reset.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Water Present Event

* **Event Type:** `waterPresent`
* **Trigger:** When the sensor detects the appearance or disappearance of water.

The following snippet shows the event `data` field content of a `waterPresent` event.

```javascript
{
    "waterPresent": {
        "state": "PRESENT",
        "updateTime": "2024-12-06T08:43:16.266000Z"
    }
}
```

<table data-header-hidden><thead><tr><th width="191.066583638007">Field</th><th width="152.3681934773962">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>state</code></td><td><code>string</code></td><td>Indicates whether water is <code>"PRESENT"</code> or <code>"NOT_PRESENT"</code>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### CO2 Event

* **Event Type:** `co2`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat).

The following snippet shows the event `data` field content of a `co2` event.

```javascript
{
    "co2": {
        "ppm": 499,
        "updateTime": "2024-12-06T09:02:35.979000Z"
    }
}
```

<table><thead><tr><th>Field</th><th width="162.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>ppm</code></td><td><code>int</code></td><td>CO2 in parts per million.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Pressure Event

* **Event Type:** `pressure`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat).

The following snippet shows the event `data` field content of a `pressure` event.

```javascript
{
    "pressure": {
        "pascal": 98644,
        "updateTime": "2024-12-06T09:02:35.979000Z"
    }
}
```

<table><thead><tr><th>Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>pascal</code></td><td><code>int</code></td><td>Barometric pressure in Pascal.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Motion Event

* **Event Type:** `motion`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat).

The following snippet shows the event `data` field content of a `motion` event.

```json
{
    "motion": {
        "state": "MOTION_DETECTED",
        "updateTime": "2024-12-06T11:45:57.454551Z"
    }
}
```

<table><thead><tr><th width="180.67553246294472">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>string</code></td><td>Indicates whether <code>MOTION_DETECTED</code> or <code>NO_MOTION_DETECTED</code>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Desk Occupancy Event

* **Event Type:** `deskOccupancy`
* **Trigger:** When the state changes between `OCCUPIED` and `NOT_OCCUPIED`.

The following snippet shows the event `data` field content of a `deskOccupancy` event.

```json
{
    "deskOccupancy": {
        "state": "NOT_OCCUPIED",
        "remarks": [],
        "updateTime": "2024-12-06T14:23:50.728000Z"
    }
}
```

| Field        | Type       | Description                                                                                                                                  |
| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`      | `string`   | Indicates whether the sensors reports `OCCUPIED` or `NOT_OCCUPIED`.                                                                          |
| `remarks`    | `[string]` | Additional information about the estimated `state` field value. [Read more below](#remarks).                                                 |
| `updateTime` | `string`   | Timestamp of when a Cloud Connector received the event, represented on the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. |

#### Remarks

We use the `remarks` field to relay additional information to the user about the estimated `state` field in the `deskOccupancy` event. If the field is empty, nothing is out of the ordinary.

The `remarks` field can contain none, one, or a combination of the following remarks.

* `INCOMPLETE_DATA`: The model has determined that the occupancy accuracy may be degraded due to insufficient data. If your connection is poor, we recommend using a [Range Extender](https://support.disruptive-technologies.com/hc/en-us/articles/360010450159-Range-Extender) to improve the connection or adding one or more additional Cloud Connectors to extend your coverage.

Remarks are automatically highlighted in DT Studio as shown in the figure below.

<figure><img src="https://3704330445-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MR5PbKbz-q3w3qIO6MH%2Fuploads%2FDvM2LXymUJjqnbFE8kfX%2FExampleDeskOccupancyRemark.png?alt=media&#x26;token=9d783c43-7c35-4221-9ef9-b094de4847cf" alt=""><figcaption></figcaption></figure>

### Contact Event

* **Event Type:** `contact`
* **Trigger:** When the state of a `contact` sensor changes between `OPEN` and `CLOSED`.

The following snippet shows the event `data` field content of a `contact` event.

```json
{
    "contact": {
        "state": "OPEN",
        "updateTime": "2024-12-06T14:23:50.728000Z"
    }
}
```

| Field        | Type     | Description                                                                                                                                  |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`      | `string` | Indicates whether the sensors reports `OPEN` or `CLOSED`.                                                                                    |
| `updateTime` | `string` | Timestamp of when a Cloud Connector received the event, represented on the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. |

### Probe Wire Status Event

* **Event Type:** `probeWireStatus`
* **Trigger:** When wires are plugged in or unplugged from a `temperature` probe sensor.

These are the possible state values for the event:

<table><thead><tr><th width="374">State</th><th>Description</th></tr></thead><tbody><tr><td><code>TWO_WIRE</code></td><td>A 2-wire probe has been connected to the sensor.</td></tr><tr><td><code>THREE_WIRE</code></td><td>A 3-wire probe has been connected to the sensor.</td></tr><tr><td><code>FOUR_WIRE</code></td><td>A 4-wire probe has been connected to the sensor.</td></tr><tr><td><code>INVALID_WIRE_CONFIGURATION</code></td><td>Either too few wires are connected to the sensor, or the wires are connected to the wrong terminals. Look at the <a href="https://support.disruptive-technologies.com/hc/en-us/articles/11432439857948-Temperature-Probe-Sensor">Datasheet</a> for more information.</td></tr><tr><td><code>INVALID_COEFFICIENT_CONFIGURATION</code></td><td>The coefficient configuration in Studio does not match the probe that's connected to the sensor. This may happen if a PT100 probe is connected to the sensor, but the coefficients for a PT1000 probe is configured in Studio.</td></tr></tbody></table>

The following snippet shows the event `data` field content of a `probeWireStatus` event.

```json
{
    "probeWireStatus": {
        "state": "THREE_WIRE",
        "updateTime": "2024-12-06T14:23:50.728000Z"
    }
}
```

<table><thead><tr><th width="196">Field</th><th width="129.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>string</code></td><td>Indicates whether the probe wire state is <code>INVALID_WIRE_CONFIGURATION</code>, <code>INVALID_COEFFICIENT_CONFIGURATION</code>, <code>TWO_WIRE</code>, <code>THREE_WIRE</code> or <code>FOUR_WIRE</code>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Network Status Event

* **Event Type:** `networkStatus`
* **Trigger:** Every [periodic heartbeat](#periodic-heartbeat).

This event describes the current connectivity state of a sensor. It is sent in addition to other events and contains information like the signal strength to the Cloud Connector it propagated through.

#### Proximity to multiple Cloud Connectors

One `networkStatus` event is sent for each Cloud Connector that heard the sensor. As shown in the snippet below, when fetching events through a [stream](https://developer.disruptive-technologies.com/api#/Live%20Events%20Streaming%20API/get_projects__project__devices_stream), [Data Connector](https://docs.developer.disruptive-technologies.com/data-connectors/introduction-to-data-connector), or [event history](https://developer.disruptive-technologies.com/api#/Event%20History/get_projects__project__devices__device__events), each `networkStatus` event contains only a single entry in the `cloudConnectors` field. When [listing a device](https://developer.disruptive-technologies.com/api#/Devices%20%26%20Labels/get_projects__project__devices), these individual `networkStatus` events are merged and all displayed in the `reported` field.

#### Offline detection

Use the [`connectionStatus`](#connection-status-event) event to check whether a sensor is online or offline. This event takes into account the current [Heartbeat Interval](#periodic-heartbeat) of the sensor and only sends out an event with the `OFFLINE` connection status when one heartbeat has been dropped. When the sensor comes back online, a new `connectionStatus` event will be sent out with the `SDS` ([Secure Data Shot](https://www.disruptive-technologies.com/explore/platform-security-how-we-make-sure-sensor-data-is-private-and-secure)) connection status.

The following snippet shows the event `data` field content of a `networkStatus` event.

```javascript
{
    "networkStatus": {
        "signalStrength": 45,
        "rssi": -83,
        "updateTime": "2024-12-06T08:21:21.076013Z",
        "cloudConnectors": [
            {
                "id": "bdkjbo2v0000uk377c4g",
                "signalStrength": 45,
                "rssi": -83
            }
        ],
        "transmissionMode": "LOW_POWER_STANDARD_MODE"
    }
}
```

<table data-header-hidden><thead><tr><th width="375.79298024271867">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>signalStrength</code></td><td><code>int</code></td><td>The percentage signal strength (0% to 100%) of the strongest Cloud Connector, derived directly from the RSSI value.</td></tr><tr><td><code>rssi</code></td><td><code>int</code></td><td>Raw <a href="https://en.wikipedia.org/wiki/Received_signal_strength_indication">Received Signal Strength Indication</a> as measured by the Cloud Connector with the strongest signal.</td></tr><tr><td><code>cloudConnectors</code></td><td><code>[struct]</code></td><td>The Cloud Connector that forwarded the event.</td></tr><tr><td><code>cloudConnectors[].id</code></td><td><code>string</code></td><td>Unique Cloud Connector identifier.</td></tr><tr><td><code>cloudConnectors[].signalStrength</code></td><td><code>int</code></td><td>The percentage signal strength (0% to 100%) between the sensor and Cloud Connector.</td></tr><tr><td><code>cloudConnectors[].rssi</code></td><td><code>int</code></td><td><a href="https://en.wikipedia.org/wiki/Received_signal_strength_indication">Raw Received Signal Strength Indication</a> between the sensor and Cloud Connector.</td></tr><tr><td><code>transmissionMode</code></td><td><code>string</code></td><td>Indicated whether the sensor is in <code>"LOW_POWER_STANDARD_MODE"</code> or <code>"HIGH_POWER_BOOST_MODE"</code>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Battery Status Event

* **Event Type:** `batteryStatus`
* **Trigger:** Approximately once per day.

The following snippet shows the event `data` field content of a `batteryStatus` event.

```javascript
{
    "batteryStatus": {
        "percentage": 100,
        "updateTime": "2024-12-06T08:21:21.076013Z"
    }
}
```

<table data-header-hidden><thead><tr><th>Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>percentage</code></td><td><code>int</code></td><td>A coarse percentage estimate (0% to 100%) of the remaining battery.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Labels Changed Event

* **Event Type:** `labelsChanged`
* **Trigger:** When a device label is added, modified, or removed.

The following snippet shows the event `data` field content of a `labelsChanged` event.

```javascript
{
    "added": {
        "label-key": "label-value"
    },
    "modified": {
        "label-key": "new-label-value"
    },
    "removed": [
        "remove-key1",
        "remove-key2"
    ]
}
```

<table data-header-hidden><thead><tr><th>Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>added</code></td><td><code>struct</code></td><td>Key- and value pairs of new labels added, both of <code>string</code> type.</td></tr><tr><td><code>modified</code></td><td><code>struct</code></td><td>Key- and value pairs of modified labels, both of <code>string</code> type. The value is the new updated value.</td></tr><tr><td><code>removed</code></td><td><code>[string]</code></td><td>A list of keys of removed labels.</td></tr></tbody></table>

### Connection Status Event

* **Event Type:** `connectionStatus`
* **Trigger:** Changes in connection for a Sensor or Cloud Connector.

This event is sent when a Sensor or Cloud Connector changes its communication protocol. This is the recommended way to determine if a device is online or offline.

These are the possible status values for a device's connection status:

<table><thead><tr><th width="136">Connection</th><th>Description</th></tr></thead><tbody><tr><td><code>SDS</code></td><td>Used for Sensors when they are online. SDS is the <a href="https://www.disruptive-technologies.com/explore/platform-security-how-we-make-sure-sensor-data-is-private-and-secure">Secure Data Shot</a> protocol.</td></tr><tr><td><code>ETHERNET</code></td><td>Used for Cloud Connectors when they are online and communicate to the Cloud through an ethernet cable.</td></tr><tr><td><code>CELLULAR</code></td><td>Used for Cloud Connectors when they are online and communicate to the Cloud through a cellular connection. Note that a cellular connection might have a higher latency than an ethernet connection, so prefer to use an ethernet cable whenever possible.</td></tr><tr><td><code>OFFLINE</code></td><td>Used for both Sensors and Cloud Connectors when they are determined to be offline. Cloud Connectors are determined to be offline 5–15 minutes after they've lost their connection to the Cloud. Sensors are determined to be offline once the Cloud hasn't received a <a href="#periodic-heartbeat">Periodic Heartbeat</a> within the expected time period, depending on the heartbeat interval of the sensor. The current threshold is <code>max(15 min, HeartbeatInterval * 1.5)</code>, but this is subject to change.</td></tr></tbody></table>

For a Cloud Connector, if both `ETHERNET` and `CELLULAR` connections are available, `ETHERNET` is prioritized.

The following snippet shows the event `data` field content of a `connectionStatus` event for a Cloud Connector that is connected through `ETHERNET`.

```javascript
{
    "connectionStatus": {
        "connection": "ETHERNET",
        "available": [
            "CELLULAR",
            "ETHERNET"
        ],
        "updateTime": "2024-12-06T08:21:21.076013Z"
    }
}
```

<table data-header-hidden><thead><tr><th>Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>connection</code></td><td><code>string</code></td><td>Whether the current connection is <code>SDS</code>, <code>ETHERNET</code>, <code>CELLULAR</code>, or <code>OFFLINE</code>.</td></tr><tr><td><code>available</code></td><td><code>[string]</code></td><td>A list of the <code>string</code> types of networks available to the device. For Cloud Connectors, this can contain the values <code>ETHERNET</code>, <code>CELLULAR</code>, or both. For Sensors, it will contain only <code>SDS</code> when its online. This field will be empty when the device's <code>connection</code> is <code>OFFLINE</code>.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Ethernet Status Event

* **Event Type:** `ethernetStatus`
* **Trigger:** Changes in Cloud Connector ethernet connection.

This event is sent when the ethernet status for a Cloud Connector changes, such as when it gets connected to ethernet or when it receives a new IP address. Note that this means that a Cloud Connector has to be connected to ethernet at least once to get the MAC address of the Cloud Connector through an `ethernetStatus` event.&#x20;

The information in this event can be useful for locating a Cloud Connector on the local network or open the necessary ports in a corporate firewall.

The following snippet shows the event `data` field content of an `ethernetStatus` event.

```javascript
{
    "ethernetStatus": {
        "macAddress": "f0:b5:b7:00:0a:08",
        "ipAddress": "10.0.0.1",
        "errors": [
            {"code": 404, "message": "Not found"},
        ],
        "updateTime": "2024-12-06T08:21:21.076013Z"
    }
}
```

<table data-header-hidden><thead><tr><th>Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>macAddress</code></td><td><code>string</code></td><td>The MAC address of the local network interface.</td></tr><tr><td><code>ipAddress</code></td><td><code>string</code></td><td>The IP address of the Cloud Connector on the local network.</td></tr><tr><td><code>errors</code></td><td><code>[struct]</code></td><td>Any errors related to connecting to the local network.</td></tr><tr><td><code>errors[].code</code></td><td><code>int</code></td><td> Error status code.</td></tr><tr><td><code>errors[].message</code></td><td><code>string</code></td><td>A description of the error.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>

### Cellular Status Event

* **Event Type:** `cellularStatus`
* **Trigger:** Changes in Cloud Connector cellular connection strength.

The following snippet shows the event `data` field content of a `cellularStatus` event.

```javascript
{
    "cellularStatus": {
        "signalStrength": 80,
        "errors": [
            {"code": 404, "message": "Not found"},
        ],
        "updateTime": "2024-12-06T08:21:21.076013Z"
    }
}
```

<table data-header-hidden><thead><tr><th width="238.7566864654878">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td><code>signalStrength</code></td><td><code>int</code></td><td>Cellular reception signal strength (0% to 100%) of the Cloud Connector.</td></tr><tr><td><code>errors</code></td><td><code>[struct]</code></td><td>Any errors related to connecting to the local network.</td></tr><tr><td><code>errors[].code</code></td><td><code>int</code></td><td> Error status code.</td></tr><tr><td><code>errors[].message</code></td><td><code>string</code></td><td>A description of the error.</td></tr><tr><td><code>updateTime</code></td><td><code>string</code></td><td>Timestamp of when a Cloud Connector received the event, represented on the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339</a> format.</td></tr></tbody></table>