Events
An overview of the various event types that can be encountered throughout our services.
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 | When touched. | |
temperature | ||
objectPresent | PRESENT /NOT_PRESENT state change. | |
humidity | ||
objectPresentCount | ||
touchCount | ||
waterPresent | PRESENT /NOT_PRESENT state change. | |
co2 | ||
pressure | ||
motion | MOTION_DETECTED / NO_MOTION_DETECTED state change. | |
deskOccupancy | OCCUPIED / NOT_OCCUPIED state change. | |
batteryStatus | See event details. | |
networkStatus | ||
labelsChanged | When a device label is created, modified, or removed. | |
connectionStatus | Changes in connection type. | |
ethernetStatus | Changes in the ethernet connection. | |
cellularStatus | Changes in the cellular connection. |
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 is found in the
data
field.{
"eventId": "<EVENT_ID>",
"targetName": "projects/<PROJECT_ID>/devices/<DEVICE_ID>",
"eventType": "<EVENT_TYPE>",
"data": {
"See each event type individually below."
}
},
"timestamp": "2021-07-05T13:15:01.576753Z"
}
Field | Type | Description |
eventId | string | The unique identifier of the Event. This can be used to deduplicate events in case the same event is published multiple times. |
targetName | string | 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. |
eventType | string | |
data | struct | Includes the event data and is specific for each eventType . See the event types below for a detailed description of each field that can be found here. |
timestamp | string |
There are four places where events can be encountered in our services.
- 1.
- 2.
- 3.
- 4.
All sensors send a Network Status 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 will also send a Temperature event every heartbeat.
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.
Here are a few notes regarding timestamps and how they are presented in our services.
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.
The RFC 3339 format with fractional seconds is used for our timestamps. This is an internet-specific profile of the ISO 8601 specification, and an example can be seen below.
2021-05-16T08:13:15.361624Z
.
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. 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. These represent the timestamps of inter-heartbeat samples and are estimated by our cloud. Read more.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 page.
- Event Type:
touch
- Trigger: When touched.
An exception to this is Counting Touch Sensors, which aggregate each touch into a Touch Count Event sent every periodic heartbeat. To force a single Touch Event, hold your finger on the sensor for 3 seconds.
The following snippet shows the event
data
field content of a touch
event.{
"touch": {
"updateTime": "2021-05-16T08:13:15.361624Z"
}
}
Field | Type | Description |
updateTime | string |
- Event Type:
temperature
- Note: 2nd Gen Temperature Sensors and 3rd Gen Temperature Sensors will only send temperature on heartbeats, and not when touched.
The following snippet shows the event
data
field content of a temperature
event.{
"temperature": {
"value": 24.9,
"samples": [
{
"value": 24.9,
"sampleTime": "2021-05-16T08:15:48.223962Z"
},
{
"value": 24.3,
"sampleTime": "2021-05-16T08:15:18.318751Z"
},
{
"value": 24.4,
"sampleTime": "2021-05-16T08:14:48.872918Z"
},
...
],
"updateTime": "2021-05-16T08:15:18.318751Z"
}
}
Field | Type | Description |
value | float | Temperature value in Celsius. |
samples | [struct] | 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. |
samples[].value | float | Sample temperature value in Celsius. |
samples[].sampleTime | string | |
updateTime | string |
Our 2nd and 3rd generation temperature sensors can be configured to sample up to 30 samples per 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.- 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.{
"objectPresent": {
"state": "NOT_PRESENT",
"updateTime": "2021-05-16T08:37:10.711412Z"
}
}
Field | Type | Description |
state | string | Indicates whether an object is "PRESENT" or "NOT_PRESENT" . |
updateTime | string |
- Event Type:
humidity
The following snippet shows the event
data
field content of a humidity
event.{
"humidity": {
"temperature": 22.45,
"relativeHumidity": 17,
"updateTime": "2021-05-16T06:13:46.369000Z"
}
}
Field | Type | Description |
temperature | float | Temperature value in Celsius. |
relativeHumidity | float | Relative humidity in percent. |
updateTime | string |
- Event Type:
objectPresentCount
This event aggregates Object Present Events and sends the total lifetime count every periodic heartbeat.
The following snippet shows the event
data
field content of a objectPresentCount
event.{
"objectPresentCount": {
"total": 4176,
"updateTime": "2021-05-16T08:23:43.209000Z"
}
}
Field | Type | Description |
total | int | 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 | string |
- Event Type:
touchCount
This event aggregates each Touch Event and sends the total lifetime count every periodic heartbeat. To force a single 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.{
"touchCount": {
"total": 469,
"updateTime": "2021-05-16T08:25:21.604000Z"
}
}
Field | Type | Description |
total | int | The total number of times the sensor has been touched over its lifetime. This can currently not be reset. |
updateTime | string |
- 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.{
"waterPresent": {
"state": "PRESENT",
"updateTime": "2021-05-16T08:43:16.266000Z"
}
}
Field | Type | Description |
state | string | Indicates whether water is "PRESENT" or "NOT_PRESENT" . |
updateTime | string |
- Event Type:
co2
The following snippet shows the event
data
field content of a co2
event.{
"co2": {
"ppm": 499,
"updateTime": "2022-02-16T09:02:35.979000Z"
}
}
Field | Type | Description |
---|---|---|
ppm | int | CO2 in parts per million. |
updateTime | string |
- Event Type:
pressure
The following snippet shows the event
data
field content of a pressure
event.{
"pressure": {
"pascal": 98644,
"updateTime": "2022-02-16T09:02:35.979000Z"
}
}
Field | Type | Description |
---|---|---|
pascal | int | Barometric pressure in Pascal. |
updateTime | string |
- Event Type:
motion
The following snippet shows the event
data
field content of a motion
event.{
"motion": {
"state": "MOTION_DETECTED",
"updateTime": "2022-04-22T11:45:57.454551Z"
}
}
Field | Type | Description |
---|---|---|
state | string | Indicates whether MOTION_DETECTED or NO_MOTION_DETECTED . |
updateTime | string |
- Event Type:
deskOccupancy
- Trigger: When the state changes between
OCCUPIED
andNOT_OCCUPIED
.
The following snippet shows the event
data
field content of an deskOccupancy
event.{
"deskOccupancy": {
"state": "NOT_OCCUPIED",
"remarks": [],
"updateTime": "2022-05-30T14:23:50.728000Z"
}
}
Field | Type | Description |
---|---|---|
state | string | Indicates whether the sensors reports OCCUPIED or NOT_OCCUPIED . |
remarks | [string] | |
updateTime | string |
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 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.

- Event Type:
networkStatus
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.
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, Data Connector, or event history, each networkStatus
event contains only a single entry in the cloudConnectors
field. When listing a device, these individual networkStatus
events are merged and all displayed in the reported
field.The following snippet shows the event
data
field content of a networkStatus
event.{
"networkStatus": {
"signalStrength": 45,
"rssi": -83,
"updateTime": "2021-05-16T08:21:21.076013Z",
"cloudConnectors": [
{
"id": "bdkjbo2v0000uk377c4g",
"signalStrength": 45,
"rssi": -83
}
],
"transmissionMode": "LOW_POWER_STANDARD_MODE"
}
}
Field | Type | Description |
signalStrength | int | The percentage signal strength (0% to 100%) of the strongest Cloud Connector, derived directly from the RSSI value. |
rssi | int | Raw Received Signal Strength Indication as measured by the Cloud Connector with the strongest signal. |
cloudConnectors | [struct] | The Cloud Connector that forwarded the event. |
cloudConnectors[].id | string | Unique Cloud Connector identifier. |
cloudConnectors[].signalStrength | int | The percentage signal strength (0% to 100%) between the sensor and Cloud Connector. |
cloudConnectors[].rssi | int | |
transmissionMode | string | Indicated whether the sensor is in "LOW_POWER_STANDARD_MODE" or "HIGH_POWER_BOOST_MODE" . |
updateTime | string |
- Event Type:
batteryStatus
- Trigger: Approximately once per day.
The following snippet shows the event
data
field content of a batteryStatus
event.{
"batteryStatus": {
"percentage": 100,
"updateTime": "2021-05-16T08:21:21.076013Z"
}
}
Field | Type | Description |
percentage | int | A coarse percentage estimate (0% to 100%) of the remaining battery. |
updateTime | string |
- 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.{
"added": {
"label-key": "label-value"
},
"modified": {
"label-key": "new-label-value"
},
"removed": [
"remove-key1",
"remove-key2"
]
}
Field | Type | Description |
added | struct | Key- and value pairs of new labels added, both of string type. |
modified | struct | Key- and value pairs of modified labels, both of string type. The value is the new updated value. |
removed | [string] | A list of keys of removed labels. |
- Event Type:
connectionStatus
- Trigger: Changes in Cloud Connector connection.
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.The following snippet shows the event
data
field content of a connectionStatus
event.{
"connectionStatus": {
"connection": "ETHERNET",
"available": [
"CELLULAR",
"ETHERNET"
],
"updateTime": "2021-05-16T08:21:21.076013Z"
}
}
Field | Type | Description |
connection | string | Whether the current connection is ETHERNET , CELLULAR , or OFFLINE . |
available | [string] | A list of the string types of networks available to the Cloud Connector. Can contain the values "ETHERNET" , "CELLULAR" , or both. |
updateTime | string |
- 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. 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 a ethernetStatus
event.{
"ethernetStatus": {
"macAddress": "f0:b5:b7:00:0a:08",
"ipAddress": "10.0.0.1",
"errors": [
{"code": 404, "message": "Not found"},
],
"updateTime": "2021-05-16T08:21:21.076013Z"
}
}
Field | Type | Description |
macAddress | string | The MAC address of the local network interface. |
ipAddress | string | The IP address of the Cloud Connector on the local network. |
errors | [struct] | Any errors related to connecting to the local network. |
errors[].code | int | Error status code. |
errors[].message | string | A description of the error. |
updateTime | string |
- Event Type:
cellularStatus
- Trigger: Changes in Cloud Connector cellular connection.
The following snippet shows the event
data
field content of a cellularStatus
event.{
"cellularStatus": {
"signalStrength": 80,
"errors": [
{"code": 404, "message": "Not found"},
],
"updateTime": "2021-05-16T08:21:21.076013Z"
}
}
Field | Type | Description |
signalStrength | int | Cellular reception signal strength (0% to 100%) of the Cloud Connector. |
errors | [struct] | Any errors related to connecting to the local network. |
errors[].code | int | Error status code. |
errors[].message | string | A description of the error. |
updateTime | string |
Last modified 1mo ago