DT Developer Docs
REST APIDT StudioStatus Page
  • Getting Started
  • Overview
  • Concepts
    • Devices
    • Events
    • Topics
      • Temperature Measurement Interval
      • Motion Sensor Activity Timer
  • Data Connectors
    • Introduction to Data Connectors
    • Creating a Data Connector
    • Configuring a Data Connector
    • Receiving Events
    • Best Practices
    • Example Integrations
      • Heroku
      • Google Cloud Functions
      • AWS Lambda
      • Azure HTTP Triggers
      • IBM Cloud Actions
    • Development Guides
      • Local Development with ngrok
  • REST API
  • Introduction to REST API
  • Explore Our Endpoints
    • with cURL
    • with Python API
    • with Postman
  • Authentication
    • OAuth2
    • Basic Auth
  • Error Codes
  • Emulator API
  • Examples
    • Pagination
    • Streaming Events
    • Touch to Identify
    • Refreshing Access Token
  • Reference
  • Status Page
  • Service Accounts
    • Introduction to Service Accounts
    • Creating a Service Account
    • Managing Access Rights
    • Permissions
    • Organizational Structures
  • Other
    • Application Notes
      • Generating a Room Temperature Heatmap
      • Modeling Fridge Content Temperatures
      • Outlier Detection on Multiple Temperature Sensors
      • Simple Temperature Forecasting for Substation Transformers
      • Sensor Data Insight with Power BI and Azure
      • Third-Party Sensor Data in DT Cloud
    • Frequently Asked Question
Powered by GitBook
On this page
  • Event Types
  • Structure
  • Periodic Heartbeat
  • Triggered Events
  • Timestamps
  • Event Details
  • Touch Event
  • Temperature Event
  • Object Present Event
  • Humidity Event
  • Object Present Count Event
  • Touch Count Event
  • Water Present Event
  • CO2 Event
  • Pressure Event
  • Motion Event
  • Desk Occupancy Event
  • Contact Event
  • Probe Wire Status Event
  • Network Status Event
  • Battery Status Event
  • Labels Changed Event
  • Connection Status Event
  • Ethernet Status Event
  • Cellular Status Event

Was this helpful?

  1. Concepts

Events

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

Last updated 15 days ago

Was this helpful?

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

contact

OPEN / CLOSED state change.

probeWireStatus

Probe wire 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.

Structure

{
    "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"
}

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

timestamp

string

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

Periodic Heartbeat

Triggered Events

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

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

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

Event Details

Touch Event

  • Event Type: touch

  • Trigger: When touched.

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

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

Field

Type

Description

updateTime

string

Temperature Event

  • Event Type: temperature

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

{
    "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
    }
}

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. The first item in the array will always have the same value as the outer value and updateTime fields.

samples[].value

float

Sample temperature value in Celsius.

samples[].sampleTime

string

updateTime

string

isBackfilled

bool

Samples per Heartbeat Configuration

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": "2024-12-06T08:37:10.711412Z"
    }
}

Field

Type

Description

state

string

Indicates whether an object is "PRESENT" or "NOT_PRESENT".

updateTime

string

Humidity Event

  • Event Type: humidity

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

{
    "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
    }
}

Field

Type

Description

temperature

float

Temperature value in Celsius.

relativeHumidity

float

Relative humidity in percent.

samples

[struct]

samples[].temperature

float

The sampled temperature value in Celsius.

samples[].relativeHumidity

float

The sampled relative humidity value in percent.

samples[].sampleTime

string

updateTime

string

isBackfilled

bool

Object Present Count Event

  • Event Type: objectPresentCount

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

{
    "objectPresentCount": {
        "total": 4176,
        "updateTime": "2024-12-06T08: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

Touch Count Event

  • Event Type: touchCount

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

{
    "touchCount": {
        "total": 469,
        "updateTime": "2024-12-06T08: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

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": "2024-12-06T08:43:16.266000Z"
    }
}

Field

Type

Description

state

string

Indicates whether water is "PRESENT" or "NOT_PRESENT".

updateTime

string

CO2 Event

  • Event Type: co2

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

{
    "co2": {
        "ppm": 499,
        "updateTime": "2024-12-06T09:02:35.979000Z"
    }
}
Field
Type
Description

ppm

int

CO2 in parts per million.

updateTime

string

Pressure Event

  • Event Type: pressure

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

{
    "pressure": {
        "pascal": 98644,
        "updateTime": "2024-12-06T09:02:35.979000Z"
    }
}
Field
Type
Description

pascal

int

Barometric pressure in Pascal.

updateTime

string

Motion Event

  • Event Type: motion

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

{
    "motion": {
        "state": "MOTION_DETECTED",
        "updateTime": "2024-12-06T11:45:57.454551Z"
    }
}
Field
Type
Description

state

string

Indicates whether MOTION_DETECTED or NO_MOTION_DETECTED.

updateTime

string

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.

{
    "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]

updateTime

string

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.

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

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.

{
    "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

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:

State
Description

TWO_WIRE

A 2-wire probe has been connected to the sensor.

THREE_WIRE

A 3-wire probe has been connected to the sensor.

FOUR_WIRE

A 4-wire probe has been connected to the sensor.

INVALID_WIRE_CONFIGURATION

INVALID_COEFFICIENT_CONFIGURATION

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.

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

{
    "probeWireStatus": {
        "state": "THREE_WIRE",
        "updateTime": "2024-12-06T14:23:50.728000Z"
    }
}
Field
Type
Description

state

string

Indicates whether the probe wire state is INVALID_WIRE_CONFIGURATION, INVALID_COEFFICIENT_CONFIGURATION, TWO_WIRE, THREE_WIRE or FOUR_WIRE.

updateTime

string

Network Status Event

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

Proximity to multiple Cloud Connectors

Offline detection

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

{
    "networkStatus": {
        "signalStrength": 45,
        "rssi": -83,
        "updateTime": "2024-12-06T08: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

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

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": "2024-12-06T08:21:21.076013Z"
    }
}

Field

Type

Description

percentage

int

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

updateTime

string

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 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:

Connection
Description

SDS

ETHERNET

Used for Cloud Connectors when they are online and communicate to the Cloud through an ethernet cable.

CELLULAR

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.

OFFLINE

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.

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

Field

Type

Description

connection

string

Whether the current connection is SDS, ETHERNET, CELLULAR, or OFFLINE.

available

[string]

A list of the string types of networks available to the device. For Cloud Connectors, this can contain the values ETHERNET, CELLULAR, or both. For Sensors, it will contain only SDS when its online. This field will be empty when the device's connection is OFFLINE.

updateTime

string

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 an ethernetStatus event.

{
    "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"
    }
}

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

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.

{
    "cellularStatus": {
        "signalStrength": 80,
        "errors": [
            {"code": 404, "message": "Not found"},
        ],
        "updateTime": "2024-12-06T08: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

Every and when touched.

Every and when touched.

Every .

Every .

Every .

Every .

Every and together with trigger-based events.

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 is found in the data field.

The .

Includes the event data and is specific for each eventType. See the below for a detailed description of each field that can be found here.

Timestamp of when a Cloud Connector received the event, represented on the format.

The reported field of a when .

When pushed to a client using the .

When fetching historical data through the .

When pushed by a to another server.

All sensors send a 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 will also send a 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 .

for .

event for .

for .

for Motion Sensors.

for Desk Occupancy Sensors.

A accompanies each triggered event.

The format with is used for our timestamps. This is an internet-specific profile of the specification, and an example can be seen below.

A third type, sampleTime, can only be found within the . These represent the timestamps of inter-heartbeat samples and are estimated by our cloud. .

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

Most of our will send a when touched. This can be useful for identification.

An exception to this is , which aggregate each touch into a sent every . To force a single , hold your finger on the sensor for 3 seconds.

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every or when touched.

Note: and will only send temperature on heartbeats, and not when touched.

Estimated sample timestamp on the format. .

Timestamp of when a Cloud Connector received the event, represented on the format.

Indicates if the temperature event is backfilled. The backfill feature is supported for and . When this field is true, 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 in our Help Center for more information about Data Backfill.

Our 2nd and 3rd generation temperature sensors can be configured to sample up to 30 samples per . 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. .

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every or when touched.

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 temperature and relativeHumidity fields. Only the supports configuring the number of samples per heartbeat.

Estimated sample timestamp on the format. .

Timestamp of when a Cloud Connector received the event, represented on the format.

Indicates if the humidity event is backfilled. This feature is supported for the . When this field is true, 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 in our Help Center for more information about Data Backfill.

Trigger: Every .

This event aggregates and sends the total lifetime count every periodic heartbeat.

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every .

This event aggregates each and sends the total lifetime count every periodic heartbeat. To force a single to be sent, hold your finger on the sensor for 3 seconds.

Timestamp of when a Cloud Connector received the event, represented on the format.

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every .

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every .

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every .

Timestamp of when a Cloud Connector received the event, represented on the format.

Additional information about the estimated state field value. .

Timestamp of when a Cloud Connector received the event, represented on the format.

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 to improve the connection or adding one or more additional Cloud Connectors to extend your coverage.

Timestamp of when a Cloud Connector received the event, represented on the format.

Either too few wires are connected to the sensor, or the wires are connected to the wrong terminals. Look at the for more information.

Timestamp of when a Cloud Connector received the event, represented on the format.

Trigger: Every .

One networkStatus event is sent for each Cloud Connector that heard the sensor. As shown in the snippet below, when fetching events through a , , or , each networkStatus event contains only a single entry in the cloudConnectors field. When , these individual networkStatus events are merged and all displayed in the reported field.

Use the event to check whether a sensor is online or offline. This event takes into account the current 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 () connection status.

Raw as measured by the Cloud Connector with the strongest signal.

between the sensor and Cloud Connector.

Timestamp of when a Cloud Connector received the event, represented on the format.

Timestamp of when a Cloud Connector received the event, represented on the format.

Used for Sensors when they are online. SDS is the protocol.

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 within the expected time period, depending on the heartbeat interval of the sensor. The current threshold is max(15 min, HeartbeatInterval * 1.5), but this is subject to change.

Timestamp of when a Cloud Connector received the event, represented on the format.

Timestamp of when a Cloud Connector received the event, represented on the format.

Timestamp of when a Cloud Connector received the event, represented on the format.

Devices
event stream REST API endpoint
event history REST API endpoint
Data Connector
RFC 3339
fractional seconds
ISO 8601
Devices
2nd Gen Temperature Sensors
3rd Gen Temperature Sensors
Range Extender
stream
Data Connector
event history
listing a device
event type
periodic heartbeat
Motion Event
Desk Occupancy Event
Network Status Event
devices
Touch Event
periodic heartbeat
Read more
heartbeat
periodic heartbeat
periodic heartbeat
Object Present Events
periodic heartbeat
Touch Event
Touch Event
periodic heartbeat
periodic heartbeat
periodic heartbeat
periodic heartbeat
Secure Data Shot
connectionStatus
Heartbeat Interval
RFC 3339
RFC 3339
RFC 3339
Temperature Probe Sensors
Temperature Sensors with Data Backfill
Backfill page
RFC 3339
Temperature & Humidity Sensor
RFC 3339
Read more
RFC 3339
Temperature & Humidity Sensor
Backfill page
RFC 3339
RFC 3339
RFC 3339
RFC 3339
RFC 3339
RFC 3339
RFC 3339
RFC 3339
Datasheet
RFC 3339
Received Signal Strength Indication
Raw Received Signal Strength Indication
RFC 3339
RFC 3339
Secure Data Shot
RFC 3339
RFC 3339
RFC 3339
Touch
Temperature
periodic heartbeat
Object Present
Humidity
periodic heartbeat
Object Present Count
periodic heartbeat
Touch Count
periodic heartbeat
Water Present
CO2
periodic heartbeat
Pressure
periodic heartbeat
Motion
Desk Occupancy
Contact
Probe Wire Status
Battery Status
Network Status
periodic heartbeat
Labels Changed
Connection Status
Ethernet Status
Cellular Status
event type
event types
Read more below
Periodic Heartbeat
listing devices through REST API
Network Status
Temperature event
Object Present Event
Water Present Event
Touch Event
Temperature Event
Touch Count Event
periodic heartbeat
Touch Event
RFC 3339
Read more
Read more
Device
Temperature sensor
Proximity Sensors
Water Detector Sensors
Touch Sensors
Counting Touch Sensors