MQTT Standard Interface v1.0.0

January 10^th, 2019

1. Abstract

   Seamless IoT Device Interoperability is expected to accelerate & unlock the massive opportunity in the IoT market, accelerate industry innovation and help developers and companies create solutions quickly. The Standard Interface defines a consolidated common standard that makes devices communicable, operable, and programmable, regardless of make, model, manufacturer, or industry.

2. Limitations

   Standard Interface is using MQTT as messaging protocol which allow devices communicate each other through MQTT Broker which therefore worked in the principles of publication and subscription.

   1. Topic IDs

      • Topic consists of one or more topic levels, separated by the slash character (/).
      • A topic level ID MAY contain lowercase letters from a to z, numbers from 0 to 9 as well as the hyphen character (-).
      • A topic level ID MUST NOT start or end with a hyphen (-).
      • The special character $ is used and reserved for attributes.
      • The underscore (_) is used and reserved for node arrays.

   2. Payload

      • Every MQTT message payload MUST be sent as a UTF-8 encoded string.
      • The value published as payload MUST be valid for the respective property/attribute type as per the list below:
        1. 1. String
              • String types are limited to 268,435,456 characters.
              • An empty string (“”) is a valid payload.
           2. Integer
              • Integer types are UTF-8 encoded string literal representations of 64-bit signed whole numbers.
              • Integers range from -9,223,372,036,854,775,808 (-2⁶³) to 9,223,372,036,854,775,807 (2⁶³-1).
              • The payload may only contain whole numbers and the negation character “-”. No other characters including spaces (” “) are permitted.
              • A string with just a negation sign (“-”) is not a valid payload.
              • An empty string (“”) is not a valid payload.
           3. Float
              • Float types are UTF-8 encoded string literal representations of 64-bit signed floating point numbers.
              • Floats range from 2^-1074 to (2-2^-52)*2¹⁰²³.
              • The payload may only contain whole numbers, the negation character “-”, the exponent character “e” or “E” and the decimal separator “.”, no other characters, including spaces (” “) are permitted.
              • The dot character (“.”) is the decimal separator (used if necessary) and may only have a single instance present in the payload.
              • Representations of numeric concepts such as “NaN” (Not a Number) and “Infinity” are not a valid payload.
              • A string with just a negation sign (“-”) is not a valid payload.
              • An empty string (“”) is not a valid payload.
           4. Boolean
              • Booleans must be converted to the string literals “true” or “false”.
              • Representation is case sensitive, e.g. “TRUE” or “FALSE” are not valid payloads.
              • An empty string (“”) is not a valid payload.
           5. Enum
              • Enum payloads must be one of the values specified in the format definition of the property.
              • Enum payloads are case sensitive, e.g. “Car” will not match a format definition of “car”.
              • Payloads should have leading and trailing whitespace removed.
              • An empty string (“”) is not a valid payload.
           6. Color
              • Color payload validity varies depending on the property format definition of either “rgb” or “hsv”.
              • Both payload types contain comma separated whole numbers of differing restricted ranges.
              • The encoded string may only contain whole numbers and the comma character “,”, no other characters are permitted, including spaces (” “).
              • Payloads for type “rgb” contains 3 comma separated values of numbers with a valid range between 0 and 255. e.g. 100,100,100.
              • Payloads for type “hsv” contains 3 comma separated values of numbers. The first number has a range of 0 to 360, the second and third numbers have a range of 0 to 100. e.g. 300,50,75.
              • An empty string (“”) is not a valid payload.
           7. Location
              • Location payload validity varies depending on the property format definition of whether “dms”, “ddm” or “dd”.
              • Example for Degrees, Minutes, and Seconds (DMS) format as follow:
                41°24′12.2″N, 2°10′26.5″E
                The encoded string may only contain numbers, the cardinal points character “N,E,S,W”, the degree sign (unicode character U+00B0), the prime symbol (unicode character U+2032), double prime symbol (unicode character U+2033), the comma character “,” and spaces (” “).
              • Example for Degrees and Decimal Minutes (DDM) format as follow:
                41°24.2033′N, 2°10.4417′E
                The encoded string may only contain numbers, the cardinal points character “N,E,S,W”, the degree sign (unicode character U+00B0), the prime symbol (unicode character U+2032), the comma character “,” and spaces (” “).
              • Example for Decimal Degrees (DD) format as follow:
                41.40338, 2.17403
                The encoded string may only contain numbers, the comma character “,” spaces (” “).
              • An empty string (“”) is not a valid payload.

   3. QoS and retained messages

      The nature of the Standard Interface makes it safe about duplicate messages, so the recommended QoS for reliability is QoS 1. Please refer to your account limitation on accessing type of QoS.  All messages MUST be sent as retained, UNLESS stated otherwise.

   4. Last will

      Every published device must set a last will in the topic developer-root/device-id/$state. The expected value is “lost”, or please refer to the Device Behavior.

3. Base Topic

   Root topic: developer-root/
   e.g. your developer root is 2035, then the root topic will be 2035/.

   Application controllers must by default perform auto-discovery on the wildcard topic “+/+/$sammy”. Controllers are free to restrict discovery to a specific root topic, configurable by the user. The broker itself will restrict publishing & subscription based on access privilege of each API type and limitation. Please refer to API documentation.

4. Extensions (reserved)

   This convention only covers discoverability of devices and its capabilities. The aim is to have standardized MQTT topics for all kind of complex scenarios. A device may therefore support extensions, defined in separate documents.

5. Topology

   1. Devices

      A device is an instance of a physical piece of hardware. For example: a power meter, an alarm sensor, a washing machine.

      Base topic: developer-root/device-id
      Each device must have a unique device ID which adhere to the Topic ID format.
      Device-id should include developer-root + character ‘S’. Example: if your developer root is 2035 and your chip id/device serial number is 83FK2L92PO, then your device-id should be as follow: 2035S83FK2L92PO

      • Device Attributes

        Topic: developer-root/device-id/$device-attribute.

        When the MQTT connection to the broker is established or re-established, the device MUST send its attributes to the broker immediately.

        Topic	Description	Retained	Required
        $sammy	Version of the Standard Interface the device conforms to.	YES	YES
        $name	Friendly name of the device.	YES	YES
        $localip	IP of the device on the local network	YES	YES
        $mac	Mac address of the device network interface. The format MUST be of the type A1:B2:C3:D4:E5:F6	YES	YES
        $model	Device model according to the manufacturer.	YES	YES
        $fw/name	Name of the firmware running on the device.	YES	YES
        $fw/version	Version of the firmware running on the device.	YES	YES
        $reset	Whether device capable to do a system factory reset by receiving topic /reset. Value in “true” or “false”.	YES	NO
        $restart	Whether device capable to do a system restart by receiving topic /restart. Value in “true” or “false”.	YES	NO
        $state	See Device behavior.	YES	YES
        $stats	Specify all optional stats that the device will announce, with format stats separated by a , if there are multiple stats.	YES	NO
        $stats/interval	Interval in seconds at which the device refreshes its $stats/+	YES	NO, if $stats is NO
        $nodes	Nodes are the capabilities the device exposes, with format id separated by a , if there are multiple nodes. To make a node an array, append [] to the ID.	YES	YES

      • Device Behavior

        The $state device attribute represents, as the name suggests, the current state of the device. There are 6 different states:

        • init: this is the first state and first message the device should send when it connected to the MQTT broker, but has not yet sent all messages and is not yet ready to operate.
        • ready: this is the state the device should send after it has sent all messages and is ready to operate. You have to send this message after all other announcements message have been sent.
        • disconnected: this is the state the device should send before it is going offline, to cleanly disconnected from the MQTT broker. You must send this message before cleanly disconnecting.
        • sleeping: this is the state for sleeping. You have to send this message before turn the device into sleep mode.
        • lost: this is the state when device has been “badly” disconnected. You must define this message in the last will and Testament (LWT).
        • alert: this is the state of the device, connected well to the MQTT broker, but something wrong is happening. E.g. a sensor seems provide incorrect data, out of range data, or not providing data at all and needs human intervention. You have to send this message when something is wrong.

      • Device Statistics

        Topic: developer-root/device-id/$stats/$device-statistic-attribute.

        The $stats/ hierarchy allows to send device attributes that change over time. The device MUST send them every $stats/interval seconds.

        Topic	Description	Retained	Required
        $stats/uptime	Time elapsed in seconds since the boot of the device.	YES	NO
        $stats/signal	Signal strength in %.	YES	NO
        $stats/cputemp	CPU Temperature in °C.	YES	NO
        $stats/cpuload	CPU Load in %. Average of last $interval including all CPUs.	YES	NO
        $stats/battery	Battery level in %.	YES	NO
        $stats/freeheap	Free heap in bytes.	YES	NO
        $stats/supply	Supply Voltage in V.	YES	NO

      For example, a power meter device, which belong to a developer root 2035, with a device ID of 2035S83FK2L92PO  may send:

      2035/2035S83FK2L92PO/$state → “init”

      2035/2035S83FK2L92PO/$sammy → “1.0.0”

      2035/2035S83FK2L92PO/$name → “Power Meter”

      2035/2035S83FK2L92PO/$localip → “192.168.1.12”

      2035/2035S83FK2L92PO/$mac → “DE:AD:BE:EF:FE:ED”

      2035/2035S83FK2L92PO/$model → “VA-1220”

      2035/2035S83FK2L92PO/$fw/name → “Power Meter Firmware”

      2035/2035S83FK2L92PO/$fw/version → “PMF-001”

      2035/2035S83FK2L92PO/$stats → “battery,supply,signal”

      2035/2035S83FK2L92PO/$stats/interval → 60

      2035/2035S83FK2L92PO/$nodes → “sensor[],config”

      2035/2035S83FK2L92PO/$state → “ready”

      The power meter device is set with $stats/interval value “60”, then it is supposed to send its current values every 60 seconds:

      2035/2035S83FK2L92PO/$stats/battery → 65

      2035/2035S83FK2L92PO/$stats/supply → 5.1

      2035/2035S83FK2L92PO/$stats/signal → 72

   2. Nodes

      A device can expose multiple nodes. Nodes are independent or logically separable parts of a device. For example, a car might expose a wheels node, an engine node and a lights node.Nodes can be arrays. For example, instead of creating two lights node to control front lights and back lights independently, we can set the lights node to be an array with two elements. Before send any node, the nodes descriptor which the topic is: developer-root/device-id/$nodes must be sent first.

      Base topic: developer-root/device-id/node-id
      Each node must have a unique node ID on a per-device basis which adhere to the Topic ID format.

      • Node Attributes

        Topic: developer-root/device-id/node-id/$node-attribute

        A node attribute MUST be one of these:

        Topic	Description	Retained	Required (Default)
        $name	Friendly name of the node.	YES	YES
        $type	Type of the node.	YES	YES
        $isconfig	Indicate whether the attribute is a device configuration/setting attribute. Value is true or false.	YES	NO (false)
        $properties	Properties the node exposes, with format id separated by a , if there are multiple nodes.	YES	YES
        $array	Range separated by a -. e.g. 0-2 for an array with the indexes 0, 1 and 2.	YES	YES, if the node is an array

        For example, our sensor node would send:

        2035/2035S83FK2L92PO/sensor/$name → “VA Meter”

        2035/2035S83FK2L92PO/sensor/$type → “VAM-8”

        2035/2035S83FK2L92PO/sensor/$properties → “current,voltage”

        2035/2035S83FK2L92PO/sensor/$array → “0-2”

      • Properties

        Before send any property, the properties descriptor which is developer-root/device-id/$properties must be sent first.

        Topic: developer-root/device-id/node-id/property-id
        This is the base topic of a property. Each property must have a unique property ID on a per-node basis which adhere to the Topic ID format.

        A property value (e.g. a sensor reading) is directly published to the property topic.

        • Property Attributes

          Topic: developer-root/device-id/node-id/property-id/$property-attribute

          A property attribute MUST be one of these:

          Topic	Description	Valid Values	Retained	Required (Default)
          $name	Friendly name of the property.	Any String	YES	NO (“”)
          $settable	Specifies whether the property is settable (true) or readonly (false).	true or false	YES	NO (false)
          $retained	Specifies whether the property is retained (true) or non-retained (false). Publishing to a non-retained property topic MUST always happen with the MQTT ‘retain’ flag off.	true or false	YES	NO (true)
          $unit	A string containing the unit of this property. You are not limited to the recommended values, although they are the only well known ones that will have to be recognized by any consumer.	Recommended: °C Degree Celsius °F Degree Fahrenheit ° Degree L Liter gal Galon V Volts W Watt A Ampere % Percent m Meter ft Feet Pa Pascal psi PSI # Count or Amount	YES	NO (“”)
          $datatype	Describes the format of data.	integer, float, boolean, string, enum, color, location	YES	NO (string)
          $format	Describes what are valid values for this property.	from:to Describes a range of values e.g. 10:15. Valid for datatypes integer, float value,value,value Enumerating all valid values. Comma separated, e.g. A,B,C or ON,OFF,PAUSE. Valid for datatypes enum. rgb to provide colors in RGB format e.g. 255,255,0 for yellow. Valid for datatype color. hsv to provide colors in HSV format e.g. 60,100,100 for yellow. Valid for datatype color. dms to provide location in degree, minutes, seconds format e.g 41°24′12.2″N 2°10′26.5″E ddm to provide location in degree and decimal minutes format e.g 41°24.2033′N, 2°10.4417′E dd to provide location in decimal degree format e.g 41.40338, 2.17403	YES	No for datatype string, integer, float, boolean. Yes for enum, color, location.

        For example, our current property would send:

        2035/2035S83FK2L92PO/sensor/current/$name → “Current Reading”

        2035/2035S83FK2L92PO/sensor/current/$settable → “false”

        2035/2035S83FK2L92PO/sensor/current/$retained → “true”

        2035/2035S83FK2L92PO/sensor/current/$unit → “A”

        2035/2035S83FK2L92PO/sensor/current/$datatype → “float”

        2035/2035S83FK2L92PO/sensor/current/$format → “0:15”

        developer-root/device-id/node-id/property-id/set: the device can subscribe to this topic if the property is settable from the controller, in case of actuators.

        Device is state-based. You don’t tell your smartlight to turn on, but you tell it to put its power state to on. This especially fits well with MQTT, because of retained message.

        For example, a kitchen-light device exposing a light node would subscribe to 2035/2035S83FK2L92PO/light/power/set and it would receive:

        2035/2035S83FK2L92PO/light/power/set ← “true”

        The device would then turn on the light, and update its power state. This provides pessimistic feedback, which is important for home automation.

        2035/2035S83FK2L92PO/light/power → “true”

   3. Arrays

      A node can be an array if you’ve added [] to its ID in the $nodes device attribute, and if its $array attribute is set to the range of the array.

      Let’s consider there are 3 phase sensor in our power meter device, beside the config.

      2035/2035S83FK2L92PO/$nodes → “sensor[],config”

      2035/2035S83FK2L92PO/sensor/$name → “VA Meter”

      2035/2035S83FK2L92PO/sensor/$type → “VAM-8”

      2035/2035S83FK2L92PO/sensor/$properties → “current,voltage”

      2035/2035S83FK2L92PO/sensor/$array → “0-2”

      2035/2035S83FK2L92PO/sensor_0/$name → “Phase 1 Reading”

      2035/2035S83FK2L92PO/sensor_1/$name → “Phase 2 Reading”

      2035/2035S83FK2L92PO/sensor_2/$name → “Phase 3 Reading”

      2035/2035S83FK2L92PO/sensor_0/current → “2.68”

      2035/2035S83FK2L92PO/sensor_0/voltage → “221.53”

      2035/2035S83FK2L92PO/sensor_1/current → “1.56”

      Note that you can name each element in your array individually (“Phase 1 Reading”, etc.).

6. Properties

   A node can have multiple properties. Properties represent basic characteristics of a node, often given as numbers or finite states. For example the wheels node might expose an angle property. The engine node might expose a speed, direction and temperature property. The lights node might expose an intensity and a color property.

   • Properties can be settable. For example, you don’t want your temperature property to be settable in case of a temperature sensor (like the car example), but to be settable in case of a thermostat.
   • Properties can be retained. A property is retained by default. A non-retained property would be useful for momentary events (door bell pressed).A combination of those flags compiles into this list:
     1. retained + non-settable: The node publishes a property state (temperature sensor)
     2. retained + settable: The node publishes a property state, and can receive commands for the property (by controller or other party) (lamp power)
     3. non-retained + non-settable: The node publishes momentary events (door bell pressed event)
     4. non-retained + settable: The node publishes momentary events, and can receive commands for the property (by controller or other party) (door bell pressed event, and can also receive press command)

7. Attributes

   Devices, nodes and properties have specific attributes characterizing them. Attributes are represented by topic identifier starting with $. The precise definition of attributes is important for the automatic discovery of devices following the Standard Interface. Examples: A device might have an IP attribute, a node will have a name attribute, and a property will have a unit attribute.