Disruptive Technologies Disruptive Developers

Events

All Sensors and Cloud Connectors generate Events when their state changes. This could represent anything from pressing a Touch Sensor to removing an Ethernet cable from a Cloud Connector.

Sensor events

Temperature sensor

Temperature Sensors periodically sends a TemperatureEvent at the same 15 minute interval as the Periodic Heartbeat, but also when it is pressed.

Proximity sensor

Proximity Sensors sends an ObjectPresentEvent whenever an object is put close to the sensor and when it is removed.

Touch sensor

Touch Sensors sends a TouchEvent whenever it is pressed.

Secondary events

A few events are generated in addition to the primary events described above. These are either for convenience or are meta-data updates from the Sensor.

All Sensors generate a TouchEvent when pressed. For the Proximity Sensor, this means that it will generate both ObjectPresentEvents and a TouchEvent when pressed by a finger.

All Sensors generate NetworkStatusEvents (in most cases one per Cloud Connector within range) together with any TouchEvent or ObjectPresentEvent.

Periodic heartbeat

All Sensors sends NetworkStatusEvents approximately every 15 minutes. This acts as a type of “heartbeat” from the Sensor to the Cloud. Note that more than one NetworkStatusEvent can be sent over the API if there are more than one Cloud Connector within range. See NetworkStatusEvent for more information.

Due to the extremely low-power nature of the Sensor, this 15 minute interval can vary by up to +/- 3 minutes depending on temperature and remaining life-time of the Sensor.

Reported sensor state

Events will, by design, only report changes compared to the current state. So even though an Event can be relied on to update the state, it can be useful to know the starting state.

To get an overview of the current, or starting, state, it is possible to look up the Device via the API. When looking up a Device in the API, the reported field will contain the latest reported Event of each type.

Please see the …/devices/{device} API documentation.

Timestamps in the API and in Studio

All timestamps in the API is shown in UTC.

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 Studio and those in the API.

timestamp field deprecated

Please use the updateTime of the event instead for information on when the event was triggered.

Events in the API

Events are found in three places in the API:

  1. The reported state of …/devices/{device} showing an aggregate of the latest Events for that Device
  2. Pulled by a client as an Event stream as a part of the …/devices:stream and …/devices/{device}:stream
  3. Pushed by a Data Connector to another server

List of Events

The following table gives an overview of all Events, what can generate them and when.

Event Generate By Trigger
TouchEvent All Devices When Device pressed
TemperatureEvent TemperatureSensor Every 15min and when Sensor is pressed
ObjectPresentEvent ProximitySensor When an object approaches and is removed from ProximitySensor
BatteryStatusEvent All Sensors See event details
NetworkStatusEvent All Sensors See event details
LabelsChangedEvent All Devices When a Device Label is created, modified or removed
ConnectionStatusEvent Cloud Connectors See event details
EthernetStatusEvent Cloud Connectors See event details
CellularStatusEvent Cloud Connectors See event details

TouchEvent

A Device was pressed.

updateTime The (UTC) timestamp of when the Sensor was touched

Touch Sensors are the only Sensor optimized to detect rapid Touch conditions.

Example Data Connector event

{
  "event": {
    "eventId": "bjehn6sdm92f9pd7f4s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "touch",
    "data": {
      "touch": {
        "updateTime": "2019-05-16T08:13:15.361624Z"
      }
    },
    "timestamp": "2019-05-16T08:13:15.361624Z"
  },
  "labels": {}
}

TemperatureEvent

An updated temperature from a Temperature Sensor.

temperature Temperature in Celcius
updateTime The (UTC) timestamp of when the event was raised

TemperatureEvents are sent by Temperature Sensors either

  1. every 15 min as part of the periodic Periodic Heartbeat or
  2. when the Sensor is pressed

Example Data Connector event

{
  "event": {
    "eventId": "bjeho5nlafj3bdrehgsg",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "temperature",
    "data": {
      "temperature": {
        "value": 24.9,
        "updateTime": "2019-05-16T08:15:18.318751Z"
      }
    },
    "timestamp": "2019-05-16T08:15:18.318751Z"
  },
  "labels": {}
}

ObjectPresentEvent

An object was put within, or removed from, close proximity of a Proximity Sensor.

state Indicates if an object is present or not
updateTime The (UTC) timestamp of when an object was removed or put close to the Sensor

Generated by the Proximity Sensors when an object is either put within 0-5mm from the Sensor or when it is removed.

Example Data Connector event

{
  "event": {
    "eventId": "bjei2dia9k365r1ntb20",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonol7rihjtvdmd7bg",
    "eventType": "objectPresent",
    "data": {
      "objectPresent": {
        "state": "NOT_PRESENT",
        "updateTime": "2019-05-16T08:37:10.711412Z"
      }
    },
    "timestamp": "2019-05-16T08:37:10.711412Z"
  },
  "labels": {}
}

NetworkStatusEvent

Contains an overview of the Sensors signal strength to all Cloud Connectors who can hear it.

cloudConnectors The ID and signal strength of all Cloud Connectors that can hear a specific Sensor
signalStrength The signal strength of the Cloud Connector closest to the Sensor
transmissionMode The transmission mode of the Sensor - see comment below
updateTime The (UTC) timestamp of when the event was raised

Only Sensors generate the NetworkStatusEvents.

Sent when any Sensor is pressed and periodically as part of a Sensors Periodic Heartbeat.

Multiple events

If more than one Cloud Connector can hear a sensor then we will do a best effort attempt to aggregate as much meta-data as possible into the same NetworkStatusEvent, while not sacrificing too much latency.

In practice, if multiple Cloud Connectors are in range from a sensor you should expect to receive multiple NetworkStatusEvent in short succession, each with meta-data about one Cloud Connector.

Best signal strength

When using the API to get the current state of a sensor, e.g. via /projects/{project}/devices or /projects/{project}/devices/{device}, then, in the case when multiple Cloud Connectors are in range, the top-level signalStrength will always be that of the best available (often, but not always, physically closest) Cloud Connector.

Example Data Connector event

{
  "event": {
    "eventId": "bjehr0ig1me000dm66s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "networkStatus",
    "data": {
      "networkStatus": {
        "signalStrength": 45,
        "updateTime": "2019-05-16T08:21:21.076013Z",
        "cloudConnectors": [
          {
            "id": "bdkjbo2v0000uk377c4g",
            "signalStrength": 45
          }
        ],
        "transmissionMode": "LOW_POWER_STANDARD_MODE"
      }
    },
    "timestamp": "2019-05-16T08:21:21.076013Z"
  },
  "labels": {}
}

BatteryStatusEvent

An updated estimate of the remaining life-time of a Sensor.

percentage A course estimate of how much is left of the Sensor’s battery
updateTime The (UTC) timestamp of when the event was raised

Only Sensors sends the BatteryStatusEvent.

The battery of Sensors drains at an extremely slow pace, with Sensors lasting up to 15 years. Because of this, this event is sent rarely.

Please note that battery lifetime is strongly effected by the environment it is in. Please see the Sensor datasheets for more information on our Support page.


LabelsChangedEvent

Any updates to the labels of a Device will raise this event.

added New labels that has been added
modified Existing labels where the value has been modified
removed Labels that have been removed
updateTime The (UTC) timestamp of when the event was raised

The LabelsChangedEvent is not shown as part of Devices reported state explicitly as the labels themselves are part of the Device listing. See the …/devices/{device} API documentation.

Special labels in Studio

When a name is set in Studio, that devices will be listed in Studio using that name instead of the Device ID. In the API, that name is stored in a label called name.

The description field in Studio is stored in a label called description.


ConnectionStatusEvent

The current connection status of the Cloud Connector.

connection The current connection status
available The available connection options
updateTime The (UTC) timestamp of when the event was raised

The connection is used to indicate if a Cloud Connector is offline or is online, and has access to the Disruptive servers, using one of the available connection options.

A Cloud Connector can have a connection to either Ethernet or Cellular. If both are available, then the Cloud Connector will prefer Ethernet.


EthernetStatusEvent

Ethernet connection details of a Cloud Connector.

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 The (UTC) timestamp of when the event was raised

The information in this event can be used to for example locate a Cloud Connector on the local network or to open any necessary ports in a corporate firewall.


CellularStatusEvent

Cellular connection details of a Cloud Connector.

signalStrength The cellular reception signal strength of the Cloud Connector
errors Any errors related to cellular conncetion
updateTime The (UTC) timestamp of when the event was raised

The signalStrength is on a scale 0-100, in 5 steps of 20.