Events

An overview of the various event types that can be encountered throughout our services.

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 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 periodic 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.
​CO2​
co2
Every periodic heartbeat.
​Pressure​
pressure
Every periodic heartbeat.
​Motion​
motion
MOTION_DETECTED / NO_MOTION_DETECTED state change.
​Desk Occupancy​
deskOccupancy
OCCUPIED / NOT_OCCUPIED 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.
​
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 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
The event type.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
There are four places where events can be encountered in our services.
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 historical data through the event history REST API endpoint.
4.When pushed by a Data Connector to another server.
Periodic Heartbeat
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.
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.
​Object Present Event for Proximity Sensors.
​Water Present Event for Water Detector Sensors.
​Touch Event for Touch Sensors.
A Network Status Event accompanies each triggered event.
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 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.
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. 
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.
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 page.
Touch Event
Event Type: touch
Trigger: When touched.
Most of our devices will send a Touch Event when touched. This can be useful for identification.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Temperature Event
Event Type: temperature
Trigger: Every periodic heartbeat or when touched. 
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
Estimated sample timestamp on the RFC 3339 format. Read more. 
updateTime
string
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Samples per Heartbeat Configuration
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.
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.
{
    "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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Humidity Event
Event Type: humidity
Trigger: Every periodic heartbeat or when touched.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Object Present Count Event
Event Type: objectPresentCount
Trigger: Every periodic heartbeat.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Touch Count Event
Event Type: touchCount
Trigger: Every periodic heartbeat.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
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.
{
    "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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
CO2 Event
Event Type: co2
Trigger: Every periodic heartbeat.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Pressure Event
Event Type: pressure
Trigger: Every periodic heartbeat.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Motion Event
Event Type: motion
Trigger: Every periodic heartbeat.
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
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 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]
Additional information about the estimated state field value. Read more below.
updateTime
string
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 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 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.
Network Status Event
Event Type: networkStatus
Trigger: Every 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, 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
​Raw Received Signal Strength Indication between the sensor and Cloud Connector.
transmissionMode
string
Indicated whether the sensor is in "LOW_POWER_STANDARD_MODE" or "HIGH_POWER_BOOST_MODE".
updateTime
string
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Battery Status Event
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
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.
{
    "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.
Connection Status Event
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
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. 
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.
Cellular Status Event
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
Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.

Field	Type	Description
`ppm`	`int`	CO2 in parts per million.
`updateTime`	`string`	Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.

Field	Type	Description
`pascal`	`int`	Barometric pressure in Pascal.
`updateTime`	`string`	Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.

Field	Type	Description
`state`	`string`	Indicates whether `MOTION_DETECTED` or `NO_MOTION_DETECTED`.
`updateTime`	`string`	Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.

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.
`updateTime`	`string`	Timestamp of when a Cloud Connector received the event, represented on the RFC 3339 format.

Last modified 1mo ago

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 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 periodic 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.
CO2	`co2`	Every periodic heartbeat.
Pressure	`pressure`	Every periodic heartbeat.
Motion	`motion`	`MOTION_DETECTED` / `NO_MOTION_DETECTED` state change.
Desk Occupancy	`deskOccupancy`	`OCCUPIED` / `NOT_OCCUPIED` 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.