Skip to main content
Version: 1.8

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​

Topic: /sauter/viasens/<network-id>/<node-address>/configure

Smart Sensor Config Data JSON Model​

Devices have several parameters that need to be configured based on their deployment environment. These settings are mainly for configuring devices' sensors, with some requiring basic options like Change-of-Value and period, while others, like the FIR sensor, need specialized parameters such as emissivity.

  • report-time is the maximum time between the sending of 2 consecutive values

  • dead-time is the blocking time used to prevent sending value

  • cov is Change-of-Value; when specified change in sensor value is detected, current value is sent immediately, and both report-time and dead-time counters are reset

  • temperature:

    • source is a temperature source and it can be:
      • FIR = 0 -> default (Far Infrared, sensor that detects temperature by measuring the infrared radiation emitted by an object)
      • NTC = 1(Negative Temperature Coefficient, thermistor that decreases in resistance as temperature increases)
    • emissivity determines how effectively a surface radiates infrared energy, which is important for FIR sensors; values are between 0 (low) and 100 (high/perfect)
    • ntc-offset is an adjustment to the temperature reading from an NTC thermistor sensor, helping to ensure accurate measurements

  • occupancy:

    • 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 (Passive Infrared, sensor detects changes in infrared light levels in its field of view and triggers an alert or action when motion is detected)
    • dead-time is internally set to 0 and it can't be configured
    • cov is triggered when state changes and it can't be configured as well

  • illuminance:

    • light sensor with a correction factor uses a linear equation to adjust its raw readings
    • light correction factor follows an a*x+b curve. slope is defined by the a constant and intercept by the b constant, while x is raw reading

  • microphone:

    • ceiling-type is used by the microphone algorithms to compensate the sound pressure level and it can be:
      • OTHER = 0 -> default

  • ibeacon:

    • 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

Default values are provided in example.

{
  "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​

Topic: /sauter/viasens/<network-id>/<node-address>/control

Two LED ring control payloads are used, led-ring and led-ring-basic. led-ring is a bit more complex and supports more animations, while led-ring-basic has simpler packet and supports less patterns.

LED Ring Data Specification​

  • Type: led-ring
  • mode determines the LED Ring animation; -1 clears the LED Ring
  • duration determines the duration of animation in milliseconds (animation repetiton in a continuous loop isn't supported)
  • speed determines speed of the animation; value range is 0-255
  • colors are colour modifiers for the specific modes (note: values should be in hex format and inside of quotes, e.g. "0xFF0000"):
    • -1: when clearing LED ring, colours don't matter
    • 0: only first colour from array is used
    • 1-3: first two colours from array are used
    • 4-102: all colours from array are used
mode can be one of the following values:
Mode IdentifierMode IDDescription
CLEAR_ANIMATION-1Stops any ongoing LED animation
FX_MODE_STATIC0Static LED animation
FX_MODE_BLINK1Blinking LED animation
FX_MODE_BREATH2Breathing LED animation
FX_MODE_COLOUR_WIPE3Colour wipe LED animation
FX_MODE_COLOUR_WIPE_RANDOM4Random colour wipe LED animation
FX_MODE_RANDOM_COLOUR5Random colour LED animation
FX_MODE_COLOUR_SWEEP6Colour sweep LED animation
FX_MODE_DYNAMIC7Dynamic LED animation
FX_MODE_RAINBOW8Rainbow LED animation
FX_MODE_RAINBOW_CYCLE9Rainbow cycle LED animation
FX_MODE_SCAN10Scanning LED animation
FX_MODE_DUAL_SCAN11Dual scanning LED animation
FX_MODE_FADE12Fading LED animation
FX_MODE_THEATER_CHASE13Theater chase LED animation
FX_MODE_THEATER_CHASE_RAINBOW14Rainbow theater chase LED animation
FX_MODE_RUNNING_LIGHTS15Running lights LED animation
FX_MODE_SAW16Saw LED animation
FX_MODE_TWINKLE17Twinkling LED animation
FX_MODE_DISSOLVE18Dissolving LED animation
FX_MODE_DISSOLVE_RANDOM19Random dissolving LED animation
FX_MODE_SPARKLE20Sparkling LED animation
FX_MODE_FLASH_SPARKLE21Flash sparkling LED animation
FX_MODE_HYPER_SPARKLE22Hyper sparkling LED animation
FX_MODE_STROBE23Strobing LED animation
FX_MODE_STROBE_RAINBOW24Rainbow strobing LED animation
FX_MODE_MULTI_STROBE25Multi strobe LED animation
FX_MODE_BLINK_RAINBOW26Rainbow blinking LED animation
FX_MODE_ANDROID27Android LED animation
FX_MODE_CHASE_COLOUR28Colour chasing LED animation
FX_MODE_CHASE_RANDOM29Random chasing LED animation
FX_MODE_CHASE_RAINBOW30Rainbow chasing LED animation
FX_MODE_CHASE_FLASH31Flash chasing LED animation
FX_MODE_CHASE_FLASH_RANDOM32Random flash chasing LED animation
FX_MODE_CHASE_RAINBOW_WHITE33White rainbow chasing LED animation
FX_MODE_COLOURFUL34Colourful LED animation
FX_MODE_TRAFFIC_LIGHT35Traffic light LED animation
FX_MODE_COLOUR_SWEEP_RANDOM36Random colour sweep LED animation
FX_MODE_RUNNING_COLOUR37Running colour LED animation
FX_MODE_RUNNING_RED_BLUE38Running red-blue LED animation
FX_MODE_RUNNING_RANDOM39Random running LED animation
FX_MODE_LARSON_SCANNER40Larson scanner LED animation
FX_MODE_COMET41Comet LED animation
FX_MODE_FIREWORKS42Fireworks LED animation
FX_MODE_RAIN43Rain LED animation
FX_MODE_MERRY_CHRISTMAS44Merry Christmas LED animation
FX_MODE_FIRE_FLICKER45Fire flicker LED animation
FX_MODE_GRADIENT46Gradient LED animation
FX_MODE_LOADING47Loading LED animation
FX_MODE_POLICE48Police LED animation
FX_MODE_POLICE_ALL49All-police LED animation
FX_MODE_TWO_DOTS50Two dots LED animation
FX_MODE_TWO_AREAS51Two areas LED animation
FX_MODE_CIRCUS_COMBUSTUS52Circus combustus LED animation
FX_MODE_HALLOWEEN53Halloween LED animation
FX_MODE_TRICOLOUR_CHASE54Tricolour chasing LED animation
FX_MODE_TRICOLOUR_WIPE55Tricolour wipe LED animation
FX_MODE_TRICOLOUR_FADE56Tricolour fade LED animation
FX_MODE_LIGHTNING57Lightning LED animation
FX_MODE_ICU58ICU LED animation
FX_MODE_MULTI_COMET59Multi-comet LED animation
FX_MODE_DUAL_LARSON_SCANNER60Dual Larson scanner LED animation
FX_MODE_RANDOM_CHASE61Random chasing LED animation
FX_MODE_OSCILLATE62Oscillating LED animation
FX_MODE_PRIDE_201563Pride 2015 LED animation
FX_MODE_JUGGLE64Juggling LED animation
FX_MODE_PALETTE65Palette LED animation
FX_MODE_FIRE_201266Fire 2012 LED animation
FX_MODE_COLOURWAVES67Colour waves LED animation
FX_MODE_BPM68BPM LED animation
FX_MODE_FILLNOISE869Fill noise 8 LED animation
FX_MODE_NOISE16_170Noise 16_1 LED animation
FX_MODE_NOISE16_271Noise 16_2 LED animation
FX_MODE_NOISE16_372Noise 16_3 LED animation
FX_MODE_NOISE16_473Noise 16_4 LED animation
FX_MODE_COLOURTWINKLE74Colour twinkle LED animation
FX_MODE_LAKE75Lake LED animation
FX_MODE_METEOR76Meteor LED animation
FX_MODE_METEOR_SMOOTH77Smooth meteor LED animation
FX_MODE_RAILWAY78Railway LED animation
FX_MODE_RIPPLE79Ripple LED animation
FX_MODE_TWINKLEFOX80Twinkle fox LED animation
FX_MODE_TWINKLECAT81Twinkle cat LED animation
FX_MODE_HALLOWEEN_EYES82Halloween eyes LED animation
FX_MODE_STATIC_PATTERN83Static pattern LED animation
FX_MODE_TRI_STATIC_PATTERN84Tricolour static pattern LED animation
FX_MODE_SPOTS85Spots LED animation
FX_MODE_SPOTS_FADE86Fading spots LED animation
FX_MODE_GLITTER87Glitter LED animation
FX_MODE_CANDLE88Candle LED animation
FX_MODE_STARBURST89Starburst LED animation
FX_MODE_EXPLODING_FIREWORKS90Exploding fireworks LED animation
FX_MODE_BOUNCINGBALLS91Bouncing balls LED animation
FX_MODE_SINELON92Sinelon LED animation
FX_MODE_SINELON_DUAL93Dual sinelon LED animation
FX_MODE_SINELON_RAINBOW94Rainbow sinelon LED animation
FX_MODE_POPCORN95Popcorn LED animation
FX_MODE_DRIP96Drip LED animation
FX_MODE_PLASMA97Plasma LED animation
FX_MODE_PERCENT98Percentage LED animation
FX_MODE_RIPPLE_RAINBOW99Rainbow ripple LED animation
FX_MODE_HEARTBEAT100Heartbeat LED animation
FX_MODE_SUNRISE101Sunrise LED animation
FX_MODE_FLOW102Flow LED animation
{
  "mode": "int8",
  "duration": "uint32 - [milliseconds]",
  "speed": "uint8",
  "colors": [
    "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
  • pattern determines the LED Ring Basic animation
    • up to 64 patterns supported
    • pattern repeats itself indefinitely until it is cleared or another pattern replaces it
  • colors is a two-element array containing 6-bit encoded colours (note: values should be in decimal format without quotes, e.g. [12, 48]):
    • up to 64 RGB colours are possible per value, each RGB channel being coded over 2 bits
    • 6-bit encoding is used to optimize packet size
    • e.g. green colour would be represented as 12 (RGB = (0, 3, 0)), where red, green and blue are coded over 2-bits as 00, 11 and 00, so the 6-bit binary number is 001100, which is 12 in decimal
  • period represents 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).
    • examples:
      • value 0 means 0%
      • value 5 means 50% (50% of the time first colour will be active, 50% second)
      • value 10 means 100%
pattern can be one of the following values:
PatternValue
Clear1
Full2
Half / Blinking3
Half / Alternating4
Quarter 1 - Blinking5
Quarter 2 - Blinking6
Quarter 3 - Blinking7
Quarter 4 - Blinking8
Quarter 1 - Alternating9
Quarter 2 - Alternating10
Quarter 3 - Alternating11
Quarter 4 - Alternating12
Six Opposite - Blinking13
Six Opposite - Alternating14
Twelve Opposite - Blinking15
Twelve Opposite - Alternating16
Spin clockwise17
Spin counterclockwise18

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

{
  "pattern": "uint6",
  "colors": [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%"
}

Sensor Values​

Topic: /sauter/viasens/<network-id>/<node-address>

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​

Configuration Packet​

Example of configuration packet with default values sent by the third-party to the gateway in order to configure node with the address 5.

- Client posts to topic `/sauter/viasens/<network-id>/5/configure` in order to configure the node `5`
{
  "type": "sensors-config",
  "payload": {
    "temperature": {
      "emissivity": 90,
      "source": 0,
      "ntc-offset": 0.0,
      "cov": 0.2,
      "report-time": 900,
      "dead-time": 300
    },
    "occupancy": {
      "hold-time": 30,
      "sensitivity": 2,
      "mode": 0,
    },
    "humid": {
      "cov": 5,
      "report-time": 900,
      "dead-time": 300
    },
    "voc": {
      "cov": 30,
      "report-time": 900,
      "dead-time": 300
    },
    "co2": {
      "cov": 50,
      "report-time": 900,
      "dead-time": 300
    },
    "illuminance": {
      "slope": 1,
      "intercept": 0,
      "cov": 50,
      "report-time": 900,
      "dead-time": 300
    },
    "microphone": {
      "ceiling-type": 0,
      "cov": 5,
      "report-time": 900,
      "dead-time": 300
    },
    "ibeacon": {
      "tx-power": 4
    }
  }
}

LED Ring Control Packet​

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,
      "colors": [
          "0x0000FF",
          "0x00FF00",
          "0xFF0000"
      ]
  }
}

LED Ring Basic Control Packet​

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 pattern 4 with the period of 20 (5s), colours modifiers are set to red and green in decimal (each RGB channel being coded over 2 bits), and with the duty cycle set to 5 (50%).

- Client posts to topic `/sauter/viasens/<network-id>/5/control` in order to control the LED Ring of the node `5`
{
  "type": "led-ring-basic",
  "payload": {
    "pattern": 4,
    "colors": [12, 48],
    "period": 20,
    "duty-cycle": 5
  }
}

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