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.

All timestamps in the API will be in the RFC 3339 format with fractional seconds. This is an Internet specific profile of the ISO 8601 specification. An example of the timestamp format is: 2021-05-16T08:13:15.361624Z.

Events often include two identical timestamps located at different places in the body.

  • event.timestamp Timestamp of when the event was received by a Cloud Connector. This is included in all event payloads for convenience.

  • event.data.eventType.updateTime Timestamp of when the event was received by a Cloud Connector. This is included in most event data payloads.

Event Structure

Events can be encountered in the following four places.

  1. The reported field of a device when listing devices through REST API.

  2. When pushed to a client using the event stream REST API endpoint.

  3. When fetching historic data through the event history REST API endpoint.

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

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": "yyyy-MM-ddTHH:mm:ss.SSSSSSZ"
}
}

Touch Event

These events are sent for all devices types when the device is touched.

Note that while most devices will send a touch event even for short taps, the Counting Touch Sensor will aggregate the taps into a Touch Count Event which is sent every Periodic Heartbeat. To force a single touch event for Counting Touch Sensors, hold your finger on the sensor for at least 3 seconds.

  • Event Type: touch

  • Trigger: When touched.

  • Type-Specified Fields:

    • updateTime: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"touch": {
"updateTime": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"temperature": {
"value": 24.9,
"updateTime": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"objectPresent": {
"state": "NOT_PRESENT",
"updateTime": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"humidity": {
"temperature": 22.45,
"relativeHumidity": 17,
"updateTime": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

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

Touch Count Event

Sent by Counting Touch Sensors once every Periodic Heartbeat, and includes the total number of times the sensor has been touched over its lifetime. Counting Touch Sensors can also send Touch Events by holding a 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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"touchCount": {
"total": 469,
"updateTime": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"waterPresent": {
"state": "PRESENT",
"updateTime": "2021-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 when received through an event stream, Data Connector, or event history. The exception to this is the reported field of a device where all the Cloud Connector that picked up the same event will be included in the cloudConnectors list.

  • 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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

    • 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": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

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

Labels Changed Event

This event is sent when Device Labels are added, modified, or removed for a Device. This event is not part of the reported field of a device (the labels are included as their own field), but this event will be available through the event history, event stream, as well as Data Connectors.

  • Event Type: labelsChanged

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

  • Type-Specific Fields:

    • added: Keys and values of new labels added.

    • modified: The keys of the labels that were modified, along with the updated values.

    • removed: A list of keys for the removed labels.

  • Special Labels: The display name and description of a device in DT Studio are actually labels with the keys name and description. When these are changed, a labelsChanged event is generated with their new values.

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

Connection Status Event

This event is sent when a Cloud Connector changes which type of connection it has. 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: A list of the types of networks available to the Cloud Connector. Can contain ETHERNET, CELLULAR, or both.

    • updateTime: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

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

Ethernet Status Event

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 in order to get the MAC address of the Cloud Connector through an ethernetStatus 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.

  • 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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

{
"ethernetStatus": {
"macAddress": "f0:b5:b7:00:0a:08",
"ipAddress": "10.0.0.1",
"errors": [],
"updateTime": "2021-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: Timestamp of when the event was received by a Cloud Connector. Will be in the RFC 3339 format.

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