Events

An overview of the various Event Types that can be encountered throughout our services.

Device Events

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

Event Name

Event Type

Trigger

Touch

touch

When touched.

Temperature

temperature

Every Periodic Heartbeat and when touched.

Object-Present

objectPresent

PRESENT/NOT_PRESENT state change.

Humidity

humidity

Every heartbeat and when touched.

Object-Present Count

objectPresentCount

Every Periodic Heartbeat.

Touch Count

touchCount

Every Periodic Heartbeat.

Water-Present

waterPresent

PRESENT/NOT_PRESENT state change.

Battery Status

batteryStatus

See event details.

Network Status

networkStatus

Every Periodic Heartbeat.

Labels Changed

labelsChanged

When a device label is created, modified, or removed.

Connection Status

connectionStatus

Changes in connection type.

Ethernet Status

ethernetStatus

Changes in the ethernet connection.

Cellular Status

cellularStatus

Changes in the cellular connection.

Periodic Heartbeat

All sensors send a networkStatus event at a predefined interval, usually around every 15 minutes. Depending on the sensor type, this heartbeat may be accompanied by additional events. For instance, the Temperature Sensor will also send a temperature event every heartbeat.

Secondary Events

A few extra Secondary Events are generated for convenience or metadata updates. For instance, while networkStatus events are sent every Periodic Heartbeat, an objectPresent event will also be accompanied by one when triggered. The same is also true for waterPresent events.

Timestamps

All timestamps in the API are shown in UTC, while DT Studio always shows timestamps and graphs based on the location of the user. This means that there can be a difference between the timestamps shown in DT Studio and those in the API.

Additionally, events often include two identical timestamps located at different places in the body.

  • event.timestamp ISO format timestamp of when the event was received by a Cloud Connector. Included in all event payloads for convenience.

  • event.data.eventType.updateTime ISO-format timestamp of when the event was received by a Cloud Connector. Included in most event data payloads.

Event Structure

Events can be encountered in the following four places.

  1. The reported field returned by the Device State REST API Endpoint.

  2. When pushed to a client using the Event Stream REST API Endpoint.

  3. When pushed by a Data Connector to another server.

  4. When fetching historic data through the REST API.

The general anatomy is as shown in the following snippets which show the fields common between all types. The data field contains specific information related to each event type.

{
"event": {
"eventId": "UNIQUE EVENT_ID",
"targetName": "/projets/PROJECT_ID/devices/DEVICE_ID ",
"eventType": "EVENT_TYPE",
"data": {
// See each event type below for details.
},
"timestamp": "ISO-format timestamp: YYYY-MM-DDThh:mm:ssZ"
},
"labels": {
"KEY": "VALUE",
...
}
}

Touch Event

  • Event Type: touch

  • Trigger: When touched.

  • Type-Specified Fields:

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"touch": {
"updateTime": "2019-05-16T08:13:15.361624Z"
}
}

Temperature Event

  • Event Type: temperature

  • Trigger: Every Periodic Heartbeat or when touched.

  • Type-Specific Fields:

    • value: Temperature in Celsius.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"temperature": {
"value": 24.9,
"updateTime": "2019-05-16T08:15:18.318751Z"
}
}

Object-Present Event

  • Event Type: objectPresent

  • Trigger: When the sensor detects the appearance or disappearance of an object.

  • Type-Specific Fields:

    • state: Indicates whether an object is PRESENT or NOT_PRESENT.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"objectPresent": {
"state": "NOT_PRESENT",
"updateTime": "2019-05-16T08:37:10.711412Z"
}
}

Humidity Event

  • Event Type: humidity

  • Trigger: Every Periodic Heartbeat or when touched.

  • Type-Specific Fields:

    • temperature: Temperature in Celsius.

    • relativeHumidity: Relative humidity in percent.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"humidity": {
"temperature": 22.45,
"relativeHumidity": 17,
"updateTime": "2019-05-16T06:13:46.369000Z"
}
}

Object-Present Count Event

  • Event Type: objectPresentCount

  • Trigger: Every Periodic Heartbeat.

  • Type-Specific Fields:

    • total: 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.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"objectPresentCount": {
"total": 4176,
"updateTime": "2019-05-16T08:23:43.209000Z"
}
}

Touch Count Event

Note that while other sensors will send a touch event for even a short tap, the Counting Touch Sensor will aggregate said taps into the touchCount event, sent every Periodic Heartbeat. To force a single touch event, hold your finger on the sensor for at least 3 seconds.

  • Event Type: touchCount

  • Trigger: Every Periodic Heartbeat.

  • Type-Specific Fields:

    • total: The total number of times the sensor has been touched over its lifetime. This can currently not be reset.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"touchCount": {
"total": 469,
"updateTime": "2019-05-16T08:25:21.604000Z"
}
}

Water-Present Event

  • Event Type: waterPresent

  • Trigger: When the sensor detects the appearance or disappearance of water.

  • Type-Specific Fields:

    • state: Indicates whether water is PRESENT or NOT_PRESENT.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"waterPresent": {
"state": "PRESENT",
"updateTime": "2019-05-16T08:43:16.266000Z"
}
}

Network Status Event

One networkStatus event is produced for each Cloud Connector that hears the sensor. Though the cloudConnectors field is pluralized, only a single Cloud Connector will therefore be listed in each event.

  • Event Type: networkStatus

  • Trigger: Every Periodic Heartbeat.

  • Type-Specific Fields:

    • signalStrength: The percentage signal strength (0% to 100%) of the strongest Cloud Connector, derived directly from the RSSI value.

    • rssi: Raw Received Signal Strength Indication as measured by the strongest Cloud Connector.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

    • cloudConnectors: List of the Cloud Connector that forwarded the event.

      • id: Cloud Connector identifier.

      • signalStrength: The percentage signal strength (0% to 100%) between the sensor and Cloud Connector.

      • rssi: Raw Received Signal Strength Indication between the sensor and Cloud Connector.

    • transmissionMode: Indicated whether the sensor is in LOW_POWER_STANDARD_MODE or HIGH_POWER_BOOST_MODE.

{
"networkStatus": {
"signalStrength": 45,
"rssi": -83,
"updateTime": "2019-05-16T08:21:21.076013Z",
"cloudConnectors": [
{
"id": "bdkjbo2v0000uk377c4g",
"signalStrength": 45,
"rssi": -83
}
],
"transmissionMode": "LOW_POWER_STANDARD_MODE"
}
}

Battery Status Event

  • Event Type: batteryStatus

  • Trigger: Approximately once per day. Should not be used for timing.

  • Type-Specific Fields:

    • percentage: A coarse percentage estimate (0% to 100%) of the remaining battery.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"batteryStatus": {
"percentage": 100,
"updateTime": "2019-05-16T08:21:21.076013Z"
}
}

Labels Changed Event

This event is not part of the reported state of a device, but rather the device listing.

  • Event Type: labelsChanged

  • Trigger: When a label is added, modified, or removed.

  • Type-Specific Fields:

    • added: Keys and values of new labels added.

    • modified: New keys and values of labels modified.

    • removed: List of keys for labels removed.

  • Special Labels: If a device is given a name or description in DT Studio, a label with the same key will be generated automatically, where the value is as provided in the text.

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

Connection Status Event

If both ETHERNET and CELLULAR connections are available, ETHERNET is prioritized.

  • Event Type: connectionStatus

  • Trigger: Changes in Cloud Connector connection.

  • Type-Specific Fields:

    • connection: Whether the current connection is ETHERNET, CELLULAR, or OFFLINE.

    • available: Can contain ETHERNET, CELLULAR, or both.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"connectionStatus": {
"connection": "ETHERNET",
"available": [
"CELLULAR",
"ETHERNET"
],
"updateTime": "2019-05-16T08:21:21.076013Z"
}
}

Ethernet Status Event

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. However, note that we currently do not offer a static IP range.

  • Event Type: ethernetStatus

  • Trigger: Changes in Cloud Connector ethernet connection, like an updated IP address.

  • Type-Specific Fields:

    • macAddress: The MAC address of the local network interface.

    • ipAddress: The IP address of the Cloud Connector on the local network.

    • errors: Any errors related to connecting to the local network.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"ethernetStatus": {
"macAddress": "f0:b5:b7:00:0a:08",
"ipAddress": "10.0.0.1",
"errors": [],
"updateTime": "2019-05-16T08:21:21.076013Z"
}
}

Cellular Status Event

  • Event Type: cellularStatus

  • Trigger: Changes in Cloud Connector cellular connection.

  • Type-Specific Fields:

    • signalStrength: Cellular reception signal strength (0% to 100%) of the Cloud Connector.

    • errors: Any errors related to the cellular connection.

    • updateTime: ISO-format timestamp of when the event was received by a Cloud Connector.

{
"cellularStatus": {
"signalStrength": 80,
"errors": [],
"updateTime": "2019-05-16T08:21:21.076013Z"
}
}