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

Wireless Temperature Sensor

temperature-sensor-events.png The Wireless Temperature Sensors periodically sends a TemperatureEvent at the same 15-minute interval as the Periodic Heartbeat, and also when it is pressed.

Wireless Proximity Sensor

proximity-sensor-events.png The Wireless Proximity Sensors send an ObjectPresentEvent whenever an object is put close to the sensor and when it is removed.

Wireless Touch Sensor

The Touch Sensors send a TouchEvent whenever it is pressed.

Wireless Humidity Sensor

Wireless Humidity Sensors periodically sends a HumidityEvent at the same 15-minute interval as the Periodic Heartbeat, but also when it is touched.

Wireless Counting Proximity Sensor

Wireless Counting Proximity Sensors send an ObjectPresentCountEvent at the same 15-minute interval as the Periodic Heartbeat.

Wireless Counting Touch Sensor

Wireless Counting Touch Sensors send a TouchCountEvent at the same 15-minute interval as the Periodic Heartbeat.

Wireless Water Detector

The Wireless Water Detectors send a WaterPresentEvent when water comes into contact with the front of the sensors and when water no longer covers the sensors.

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

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

Periodic heartbeat

All sensors send 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 is more than one Cloud Connector within range. See NetworkStatusEvents 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 the ambient temperature and remaining lifetime of the sensor.

EN12830 sensor

EN12830 sensors send a NetworkStatusEvent every 5.5-minutes with a +/-1 minute variance.

Reported sensor state

Events will, by design, only report changes 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 REST API documentation.

Timestamps in the API and in Studio

All timestamps in the API are 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 of 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, which device that generates them, and by which trigger.

Event Generated By Trigger
TouchEvent All devices When device pressed
TemperatureEvent Temperature Sensors Every 15min and when a sensor is pressed
ObjectPresentEvent Proximity Sensors When an object approaches and is removed from ProximitySensor
HumidityEvent Humidity Sensors Every 15min and when a sensor is pressed
ObjectPresentCountEvent Counting Proximity Sensors Every 15min
TouchCountEvent Counting Touch Sensors Every 15min
WaterPresentEvent Water Detector Sensors Water appeared on or disappeared from a Water Detector Sensor
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

This event is sent when a device is pressed.

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

Wireless Touch Sensors are the only sensors optimized to detect rapid touch conditions. Wireless Counting Touch Sensors must be touched for at least 3 seconds before they emit a TouchEvent.

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 Wireless 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, the 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": {}
}

HumidityEvent

Updated temperature and relative humidity from a Humidity Sensor.

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

HumidityEvents are sent by Humidity 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": "bnpio6iuvvg2ninodrgg",
    "targetName": "projects/bhmh0143iktucae701vg/devices/b6roh6d7rihmn9oji86g",
    "eventType": "humidity",
    "data": {
      "humidity": {
        "temperature": 22.45,
        "relativeHumidity": 17,
        "updateTime": "2019-05-16T06:13:46.369000Z"
      }
    },
    "timestamp": "2019-05-16T06:13:46.369000Z"
  },
  "labels": {}
}

ObjectPresentCountEvent

An updated count of the number of times an object was put within, or removed from, the close proximity of a Counting Proximity Sensor. Note that the count is increased both when the object is detected, and when it is removed.

total Total number of times an object is put within or removed from the sensor over the lifetime of the sensor
updateTime The (UTC) timestamp of when the event was raised

ObjectPresentCountEvents are sent by Wireless Counting Proximity Sensors every 15 min as part of the periodic Periodic Heartbeat.

Example Data Connector event

{
  "event": {
    "eventId": "bnpkl3quvvg2ninq0fng",
    "targetName": "projects/bhmh0143iktucae701vg/devices/b6roh6d7rihmn9oji860",
    "eventType": "objectPresentCount",
    "data": {
      "objectPresentCount": {
        "total": 4176,
        "updateTime": "2019-05-16T08:23:43.209000Z"
      }
    },
    "timestamp": "2019-05-16T08:23:43.209000Z"
  },
  "labels": {}
}

TouchCountEvent

An updated count of the number of times a Counting Touch Sensor has been touched.

total Total number of times the sensor has been touched over the lifetime of the sensor
updateTime The (UTC) timestamp of when the event was raised

TouchCountEvent is sent by Counting Touch Sensors every 15 min as part of the periodic Periodic Heartbeat.

Example Data Connector event

{
  "event": {
    "eventId": "bnpklsfkh4f8r5td2b70",
    "targetName": "projects/bhmh0143iktucae701vg/devices/b6roh6d7rihmn9oji870",
    "eventType": "touchCount",
    "data": {
      "touchCount": {
        "total": 469,
        "updateTime": "2019-05-16T08:25:21.604000Z"
      }
    },
    "timestamp": "2019-05-16T08:25:21.604000Z"
  },
  "labels": {}
}

WaterPresentEvent

Water appeared on or disappeared from a Water Detector Sensor.

state Indicates if the water is present or not
updateTime The (UTC) timestamp of when water appeared or disappeared

Generated by Water Detector Sensors when water appears on or disappears from the sensor.

Example Data Connector event

{
  "event": {
    "eventId": "bnpku97kh4f8r5td9rb0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/b6roh6d7rihmn9oji85g",
    "eventType": "waterPresent",
    "data": {
      "waterPresent": {
        "state": "PRESENT",
        "updateTime": "2019-05-16T08:43:16.266000Z"
      }
    },
    "timestamp": "2019-05-16T08:43:16.266000Z"
  },
  "labels": {}
}

NetworkStatusEvent

It contains an overview of the sensor signal strengths to all Cloud Connectors who can hear it.

cloudConnectors The ID, signal strength, and rssi of all Cloud Connectors that can hear a specific Sensor
signalStrength The signal strength of the Cloud Connector closest to the Sensor as a percentage (0% to 100%), and is derived directly from the rssi value. This is useful if you need an indication of how good the connection is to the Cloud Connector (eg. to show a number of signal bars).
rssi The raw Received Signal Strength Indication as measured by 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 sensor's Periodic Heartbeat.

Multiple events

One NetworkStatusEvent will be produced for each Cloud Connector that hears a sensor.

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 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,
"rssi": -83, "updateTime": "2019-05-16T08:21:21.076013Z", "cloudConnectors": [ { "id": "bdkjbo2v0000uk377c4g", "signalStrength": 45,
"rssi": -83 } ], "transmissionMode": "LOW_POWER_STANDARD_MODE" } }, "timestamp": "2019-05-16T08:21:21.076013Z" }, "labels": {} }

BatteryStatusEvent

An updated estimate of the remaining lifetime of a sensor.

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

Only sensors send 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 life is strongly affected by the environment it is in. For more information, please see the sensor datasheets on our Sensor Product Pages.

Example Data Connector event

{
  "event": {
    "eventId": "bjehr0ig1me000dm66s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "batteryStatus",
    "data": {
      "batteryStatus": {
        "percentage": 100,
        "updateTime": "2019-05-16T08:21:21.076013Z"
      }
    },
    "timestamp": "2019-05-16T08:21:21.076013Z"
  },
  "labels": {}
}

LabelsChangedEvent

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

added New labels that have 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 device 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.

Example Data Connector event

{
  "event": {
    "eventId": "bjehr0ig1me000dm66s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "labelsChanged",
    "data": {
      "added": {},
      "modified": {
        "name": "Sensor name"
      },
      "removed": []
    },
    "timestamp": "2019-05-16T08:21:21.076013Z"
  },
  "labels": {}
}

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.

Example Data Connector event

{
  "event": {
    "eventId": "bjehr0ig1me000dm66s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "connectionStatus",
    "data": {
      "connectionStatus": {
        "connection": "ETHERNET",
        "available": [
          "CELLULAR",
          "ETHERNET"
        ],
        "updateTime": "2019-05-16T08:21:21.076013Z"
      }
    },
    "timestamp": "2019-05-16T08:21:21.076013Z"
  },
  "labels": {}
}

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.

Example Data Connector event

{
  "event": {
    "eventId": "bjehr0ig1me000dm66s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "ethernetStatus",
    "data": {
      "connectionStatus": {
        "macAddress": "f0:b5:b7:00:0a:08",
        "ipAddress": "10.0.0.1",
        "errors": [],
        "updateTime": "2019-05-16T08:21:21.076013Z"
      }
    },
    "timestamp": "2019-05-16T08:21:21.076013Z"
  },
  "labels": {}
}

CellularStatusEvent

Cellular connection details of a Cloud Connector.

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

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

Example Data Connector event

{
  "event": {
    "eventId": "bjehr0ig1me000dm66s0",
    "targetName": "projects/bhmh0143iktucae701vg/devices/bchonod7rihjtvdmd2vg",
    "eventType": "cellularStatus",
    "data": {
      "cellularStatus": {
        "signalStrength": 80,
        "errors": [],
        "updateTime": "2019-05-16T08:21:21.076013Z"
      }
    },
    "timestamp": "2019-05-16T08:21:21.076013Z"
  },
  "labels": {}
}