MQTT data spec

This document describes the MQTT data model that's used to communicate with the Smart Sensor Mesh Network.

• Specification relies on the MQTT version 3.1 or higher.

Configuration

Smart Sensor Config Data JSON Model

Node has a dozen of parameters that need to be configured depending on the environment where the node is deployed to. This is mainly used to configure the various sensors of the node. Some sensors require a basic configuration like Change-of-Value and period parameters while some other sensors require special parameters like the FIR's emissivity for example.

• source is a temperature source and it can be:
  • FIR = 0 -> default
  • NTC = 1
• hold-time is defined as the time during which the occupancy state stays in its current state if no further movement/presence is detected
• sensitivity is responsiveness of PIR sensor to movements and it can be:
  • LOW = 0 (detects slow movements, like walking)
  • MEDIUM = 1 -> default
  • HIGH = 2 (detects also fast and small movements)
• mode defines the source of occupancy output and can be:
  • PIR = 0 -> default
• report-time is the maximum time between the sending of 2 consecutive values
• dead-time is the blocking time used to prevent sending value
• ceiling-type is used by the microphone algorithms to compensate the sound pressure level and it can be:
  • OTHER = 0 -> default
• light correction factor will follow an a*x+b curve. slope is defined by the a constant and intercept by the b constant
• tx-power is defined as an enumeration:
  • -12 dBm = 0
  • -9 dBm = 1
  • -6 dBm = 2
  • -3 dBm = 3
  • 0 dBm = 4 -> default
  • +3 dBm = 5
  • +6 dBm = 6
  • +9 dBm = 7

{
  "type": "sensors-config",
  "payload": {
    "temperature": {
      "emissivity": "uint",
      "source": "uint",
      "ntc-offset": "float",
      "cov": "float",
      "report-time": "uint",
      "dead-time": "uint"
    },
    "occupancy": {
      "hold-time": "uint",
      "sensitivity": "uint",
      "mode": "uint"
    },
    "humid": {
      "cov": "float",
      "report-time": "uint",
      "dead-time": "uint"
    },
    "voc": {
      "cov": "float",
      "report-time": "uint",
      "dead-time": "uint"
    },
    "co2": {
      "cov": "float",
      "report-time": "uint",
      "dead-time": "uint"
    },
    "illuminance": {
      "slope": "float",
      "intercept": "float",
      "cov": "float",
      "report-time": "uint",
      "dead-time": "uint"
    },
    "microphone": {
      "ceiling-type": "uint",
      "cov": "float",
      "report-time": "uint",
      "dead-time": "uint"
    },
    "ibeacon": {
      "tx-power": "uint"
    }
  }
}

Sensor Reporting and Dead Time Mechanism

Report Time Expiration and Data Transmission

• The system continuously monitors individual sensors.
• Upon expiration of the report time, the sensor's current reading is sent out.
• Report time counter reset: After transmission, the report time counter resets to zero.
• If report time = 0 : Values will not be sent periodically, only on COV changes (with respect to dead time)

Dead Time Considerations

• Definition: Dead time is an interval that is less than or equal to the report time, and is used to block sending upon COV
• Equal Dead and Report Time: If dead time equals report time, the reading is sent once at expiration. Both counters are then reset.
• Dead time > report time: Report time will be set to dead time value.

Handling Change of Value (COV) Checks

• When dead time < report time, the following process occurs:
  • At dead time expiration: Perform a COV check.
  • If COV detected: Send the current sensor value immediately, and reset both counters.
  • If no COV: Perform COV checks until expiration of report time and if COV is detected before report time expires send value and reset both report and dead timer counters.
• Dead time = 0:
  • Send value anytime COV occurs or upon report time expiration (if report time != 0)
• COV = 0:
  • Block sending upon COV change, only send on expiration of report time (if report time != 0)

Control Payloads

Two LED ring control payloads are used.

LED Ring Data Specification

Led Ring Control packet

• Type: led-ring
• mode = -1 will clear the LED Ring
• colours are modifiers for the specific modes - optional

{
  "mode": "int8",
  "duration": "uint32 - [milliseconds]",
  "speed": "uint8",
  "colours": [
    "string - hex colour, e.g. 0x112233 or #112233",
    "string - hex colour, e.g. 0x112233 or #112233",
    "string - hex colour, e.g. 0x112233 or #112233"
  ]
}

LED Ring Basic Data Specification

• Type: led-ring-basic

The following elements will be coded in the payload:

• pattern: the animation type. Up to 64 patterns supported.
• colours: a two-element array containing 6-bit encoded colours
• period: duration of one pattern animation until it repeats itself. The value is expressed in multiples of 250 ms. Max is 255, 0 means statically on (the range of period duration is [0.25, 63.75] seconds).
  • examples:
    • value 0x08 means 8 * 0.25 seconds = 2 seconds
    • value 0x51 means 81 * 0.25 seconds = 20.25 seconds
    • value 0xFF means 255 * 0.25 seconds = 63.75 seconds
• duty cycle of the two-colour animation, if any. Percentages, in 10% increments (11 values).

A pattern repeats itself indefinitely until it is cleared.

List of patterns which will be supported:

Pattern	Value
Clear	1
Full	2
Half / Blinking	3
Half / Alternating	4
Quarter 1 - Blinking	5
Quarter 2 - Blinking	6
Quarter 3 - Blinking	7
Quarter 4 - Blinking	8
Quarter 1 - Alternating	9
Quarter 2 - Alternating	10
Quarter 3 - Alternating	11
Quarter 4 - Alternating	12
Six Opposite - Blinking	13
Six Opposite - Alternating	14
Twelve Opposite - Blinking	15
Twelve Opposite - Alternating	16
Spin clockwise	17
Spin counterclockwise	18

Blinking refers to the colour type both colours displayed at the same time .

A pattern is being enabled on the LED ring until another pattern replaces it actively. There is no timeout. A maximum of 64 patterns can be defined.

Colours: a maximum of two colour values will be supported by animation. Up to 64 RGB colours are possible per value, each RGB channel being coded over 2 bits.

{
  "pattern": "uint6",
  "colours": ["uint6 - 6-bit colour", "uint6 - 6-bit colour"],
  "period": "uint8 - value expressed in multiples of 250 ms",
  "duty-cycle": "uint4 - percentages in increments of 10%"
}

Smart Sensor Mesh Data JSON Model

• address is used to direct the data to a specific node in the mesh network,
• data holds the actual data - encapsulates the context of the Smart Sensor Data and prevents possible key collisions

{
    "address": "uint",
    "data": {
        "Smart Sensor Data Model - check below"
    }
}

Sensor Values

Smart Sensor Data JSON Model

• type specifies the data type, e.g. Humid data, FIR data, etc.
• payload holds type-specific payloads - encapsulates the context of the Type Specific Payloads and prevents possible key collisions

{
    "type": "string",
    "payload": {
        "Type-Specific Payloads - check the spec below"
    }
}

Type-Specific Payloads Specification

Type	Description
temperature	Temperature Sensor data
voc	VOC Sensor data
co2	CO2 Sensor data
humid	Humidity Sensor data
illuminance	Illuminance Sensor data
microphone	Microphone data
motion	Motion Sensor data
health	Health Sensor data
led-ring	LED Ring data
led-ring-basic	LED Ring Basic data

Sensor Payloads

Temperature Data Specification (Type: temperature)

{
  "temperature": "float - [°C]"
}

VOC Data Specification (Type: voc)

{
  "voc": "int32 - [VOC Index]"
}

CO2 Data Specification (Type: co2)

{
  "co2": "uint16 - [ppm]"
}

Humidity Data Specification (Type: humid)

{
  "humidity": "uint8 - [%rH]"
}

Illuminance Data Specification (Type: illuminance)

{
  "illuminance": "uint16 - [lux]"
}

Microphone Data Specification (Type: microphone)

{
  "noise-level": "uint8 - [dB]"
}

Motion Data (Type: motion)

{
  "occupancy": "1 or 4 - [Vacant / No movement, Occupied / Movement]"
}

Health Data Specification (Type: health)

Note 1: Health payload is a byte or more precisely a bitmask with each bit indicating validity of individual sensor's output. Bit value 0 means the sensor is missing or faulty and bit value 1 indicates the sensor is present and working. The states of the following sensors are present in the payload:

• bit7 - temperature NTC
• bit6 - temperature FIR
• bit5 - humidity
• bit4 - VOC
• bit3 - illuminance
• bit2 - noise level
• bit1 - occupancy
• bit0 - CO2

{
  "health": "uint8"
}

Example MQTT Packets

Humidity Packet

Example of the full packet sent by the gateway to the MQTT broker, packet represents sensor reading of 49%rH, and is generated by the node with the address 5.

- Gateway posts to topic `/sauter/viasens/<network-id>/5` packet received by the node `5`
{
    "type": "humid",
    "payload": {
        "humidity": 49
    }
}

LED Ring Control

Example of the full packet sent by the third-party to the gateway in order to control the LED Ring on the node with the address 5. The packet will set the LED Ring into mode 1 with the speed modifier of 100, colours modifiers are set to blue, green and red in hex, and the animation will be on for 10 seconds (10000 ms).

- Client posts to topic `/sauter/viasens/<network-id>/5/control` in order to control the LED Ring of the node `5`
{
    "type": "led-ring",
    "payload": {
        "mode": 1,
        "duration": 10000,
        "speed": 100,
        "colours": [
            "0x0000FF",
            "0x00FF00",
            "0xFF0000"
        ]
    }

}