Variations

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.

Periodic Heartbeat

All sensors send a Network Status 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.

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.

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

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.

Types

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

Temperature Event

• Event Type: temperature

• Trigger: Every periodic heartbeat or 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:18.318751Z",
            },
            ...
        ],
        "updateTime": "2021-05-16T08:15:18.318751Z"
    }
}

Samples per Heartbeat Configuration

Our 2nd 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"
    }
}

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

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

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

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

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

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

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

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

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

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