Getting started

Introduction

The Monitoring API was created to store high volumes of events and related data.

Monitoring can be many things, for example, someone enters the room, or exits, the humidity of Billy-Billy’s soil is ok again, the carbon dioxide reading for the room is 592 ppm, etc..

A monitoring event can include an alarm and severity.

For more information about usage, please refer to the monitoring manual pages.

Add monitoring event

Adding a monitoring event is possible via the MQTT API:

topic: zbos/monitoring/event/add

Example of a basic payload:

{
  "key": "u8ckjtwkuy",
  "event": {
    "value": 112.2,
    "type": "quantity",
    "source": "energy meter",
    "unit": "kWh"
  }
}

This is a basic, minimum example that will result in automatic creation of a default monitoring service tied to the given source and type.

Using the monitoring API, you can define your own monitoring service, that has it’s own specific set of config options. A monitoring event can also include custom data, media and alarms.

Refer to the MQTT documentation for more info: Monitoring

Monitoring event source

The source describes where the data comes from and can be chosen freely.

Monitoring types

The type describes what type the value in the monitoring event is. Although you can freely use anything there, only known types are aggregated in the cloud. Only aggregated data can be used to make graphs.

Name Types Aggregations

Timestamped numbers

temperature, humidity, quantity

count, sum, min, max, average, median

Timestamped booleans

button

count, count_by_category

Face mask

mask

count, count_by_category

Alarms

Events also allow optional alarms to be included.

Severity levels

To distinguish severity in alarms, a severity level is added to the payload. These levels are based on the definitions used in the syslog protocol (RFC5424).

Code Severity Description

0

Emergency

system is unusable

1

Alert

action must be taken immediately

2

Critical

critical conditions

3

Error

error conditions

4

Warning

warning conditions

5

Notice

normal but significant condition

6

Informational

informational messages

7

Debug

debug-level messages

A normal alarm can be 4, anything lower than or equal to 4 is an alarm.

Level 0 should only be used in emergency situations.

Persistance and type

Alarms can either be persistent or non-persistent.

Non-persistent alarms are alarms that are tied to a specific event, while persistent alarms indicate a state. See the examples below.

Persistent alarms need to be added to every event of that type/source that happens as long as that alarm remains active.

In some cases you want to send an alarm that’s not tied to a single value or sensor, for example because it is calculated by multiple values from multiple sensors. An example would be "air quality", which is calculated based on temperature, CO2, humidity, etc.

Alarms have a type property, declaring what "type" of alarm it is. This is based on AADL Error Model Annex (EMV2), an industry standard ontology used for example in automotive industry. For more information refer to this CMU SEI paper: https://resources.sei.cmu.edu/asset_files/TechnicalReport/2016_005_001_464390.pdf

Example 1: temperature of a person (non-persistent)

{
  "timestamp": 1598604831.274065,
  "value": "39",
  "type": "temperature",
  "source": "cruzr_epi_hkvision_head",
  "unit":"°C",
  "data": {
    "faceid": 529,
    "filename": "facePic165.jpg"
  }
  "alarms": [
    {
      "type": "AboveRange",
      "severity": 3,
      "persist": false,
      "timestamp": 1598604831.274065
    }
  ]
}

Example 2: Billy-Billy temperature alarm for high temperature (persistent)

{
"timestamp": 1598604831.274065,
  "value": "28",
  "source": "billy-billy",
  "type": "temperature",
  "unit":"°C",
  "data": {
    "pot": "11-40-114-75-26"
  },
  "alarms": [
    {
      "type": "AboveRange",
      "severity": 4,
      "persist": true,
      "timestamp": 1598604831.274065
    }
  ]
}

Example 3: Air Quality (persistent)

{
  "timestamp": 1598604831.274065,
  "type": "air_quality",
  "source": "billy-billy",
  "unit": "",
  "data": {
    "co2": "1000",
    "temperature": "24"
  }
  "alarms": [
    {
      "type": "BadQuality",
      "severity": 3,
      "persist": true,
      "timestamp": 1598604831.274065
    }
  ]
}
{
  "timestamp": 1598604831.274065,
  "type": "air_quality",
  "source": "billy-billy",
  "unit": "",
  "data": {
    "co2": "400",
    "temperature": "20"
  }
}