MQTT

  • MQTT versions 3.1.0 a and 3.1.1 are supported
  • Any device must be registered in the Mervis cloud. Connection parameters are provided upon the registration (DeviceID, user name and password)
  • possibility of a dynamic variable set (devices can specify what variables they publish)
  • only built-in types are supported (bool, integers, floating point numbers, string)
  • support for secured channel. A device can use secure or non-secure connection
  • ClientID corresponds to the DeviceID
  • User name and password
  • No special requirements considering flags or keep-alive periods (some reasonable value like 60 seconds are recommended)
  • Every topic starts with the DeviceId
  • The rest of the topic depends on the required functionality

Registration of available variables

  • Informs the subscribers of available variables
  • Publish message with “At least once delivery”
  • Topic: deviceId/TagConfiguration
  • Combination of the collection ID and Tag must be unique for every device!
  • Payload: UTF-8 JSON document
    • /FormatId: (string), message ID
    • /ApiVersion(int), version of API
    • /Complete (bool), must be true now
    • /Collections (Array of collection elements)
      • /Id (int), ID of the collection
      • /CollectionName (string)
      • /SampleRate (int), collection sample rate in ms
      • /PublishInterval (int), collection publish interval in ms
      • /TagData (Array of variable descriptions)
        • /Tag (string), ID of the variable
        • /Unit (string), unit of the variable
        • /ValueType (string), ST type; only simple types are supported

Example

{
	"FormatId": "TagConfiguration",
	"ApiVersion": 1,
	"Complete": true,
	"Collections": [{
		"Id": 1,
		"CollectionName": "Building 1",
		"SampleRate": 60000,
		"PublishInterval": 60000,
		"TagData": [{
			"Tag": "Temperature1",
			"Unit": "ºC",
			"ValueType": "real"
		},
		{
			"Tag": "Humidity",
			"Unit": "%",
			"ValueType": "word"
		}]
	},
	{
		"Id": 2,
		"CollectionName": "Building 2",
		"SampleRate": 120000,
		"PublishInterval": 240000,
		"TagData": [{
			"Tag": "Water flow",
			"Unit": "m3/h",
			"ValueType": "byte"
		},
		{
			"Tag": "Current phase L1",
			"Unit": "A",
			"ValueType": "lreal"
		}]
	}]
}

Variable values

  • Publishes values of variables
  • Publish message with “At least once delivery”
  • Topic: deviceId/TagValues
  • Payload: UTF-8 JSON document
    • /FormatId: (string), message ID
    • /ApiVersion(int), version of API
    • /CollectionId (int), identification of the collection
    • /TagData (Array of value items)
      • /Time (datetime), timestamp in ISO format (YYYY-MM-DDTHH:MM:SSZ), ideal is a UTC form
      • /Values (Collection of Tag and value tuples)

Example

{
	"FormatId": "TagValues",
	"ApiVersion": 1,
	"CollectionId": 1,
	"TagData": [{
		"Time": "2018-03-27T17:19:23.720+02:00",
		"Values": {
			"Temperature1": 15.52,
			"Humidity": 21
		}
	}]
}
  • We assume that all datetime values are in UTC
  • Print screens are from EasyBuilder Pro SW

Variable values

  • Publishes values of variables
  • Publish message with “At least once delivery”
  • Topic: $deviceId/mervis/values or $deviceId/mervis/values/*
  • Payload: UTF-8 JSON document
    • /d: root element
      • “property_name”: value - property name, can contain metada(not required). Always use array […] for value of property
        • metadata format:
          • “name” name of property
          • “type” property type(we supported only our list of types)
          • “unit” information about unit of value

Example

{
    "d" : {
        "name:MyHomeTemperature, type:generic_sint64, unit:°C" : [ 0 ],
        "number C" : [ 0 ],
        "Bit" : [ false ],
        "My array" : [ 0, 10, 20 ]
    },
    "ts" : "2020-08-27T07:10:24.360316"
}

Command registration

  • Topic: $deviceId/mervis/cmd_reg or $deviceId/mervis/cmd_reg/*
  • Format:
    • /d root element
      • “propertyName” must include some informations(separate by “,”). Value is ignored.
        • “id” what is command id and define subscribe topic ($deviceId/mervis/command/change_temperature)
        • “name” just for customer info
        • “params” parameters with informations to command (must include all parameters of supscribe topic)
          • “name” parameter name in json
          • “type” type of parameter (we supported only our list of types)
          • “unit” information about unit of parameter
        • “ts” time span
{
    "d" : {
        "id:change_temperature, name:change temperature in house ,params:[{name: temperature, type:generic_float64, unit:°C}, {name: date, type:generic_datetime, unit:UTC}]" : false
    },
    "ts" : "2020-08-27T07:10:11.356013"
}

choose/create $deviceId/mervis/cmd_reg/ set general tab by screenshot add commands

Our supported types

  • “generic_bool”
  • “generic_sint8”
  • “generic_uint8”
  • “generic_sint16”
  • “generic_uint16”
  • “generic_sint32”
  • “generic_uint32”
  • “generic_sint64”
  • “generic_uint64”
  • “generic_float32”
  • “generic_float64”
  • “generic_string”
  • “generic_datetime”

Create a subcribe topic for executing command

  • for previous command example
  • create topic $deviceId/mervis/command/change_temperature
  • with two addresses:
    • temperature(32-bit float)
    • date(string)

  • © Energocentrum Plus, s.r.o. 2017 - 2024