pimatic-mqtt

MQTT plugin for Pimatic

Screenshots

Status of implementation

This version supports the following

• General sensor (numeric and text data from payload)
• Switch
• PresenceSensor
• ContactSensor
• Dimmer
• Buttons
• Shutter
• Input

Sponsoring

Do you like this plugin? Then please consider a donation to support the development.

Getting Started

This section is still work in progress.

Plugin Configuration

While run MQTT broker on localhost and on a standard port, without autentification, you can load the plugin by editing your config.json to include the following in the plugins section.

{
  "plugin": "mqtt",
  "active": true,
  "brokers": [
    {
      "brokerId": "default"
    }
  ]
}

Configuration with two Brokers

{
  "plugin": "mqtt",
  "active": true,
  "brokers": [
    {
      "brokerId": "default"
      "host": "localhost"
    },
    {
      "brokerId": "eclipse",
      "host": "iot.eclipse.org"
    }
  ]
}

The configuration for a broker is an object comprising the following properties.

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
host	"127.0.0.1"	String	Broker hostname or IP
port	1883	Integer	Broker port
keepalive	180	Integer	Keepalive in seconds
clientId	pimatic*	String	*pimatic + random number or your own clientId
protocolId	"MQTT"	String	With broker that supports only MQTT 3.1 (not 3.1.1 compliant), you should pass "MQIsdp"
protocolVer	4	Integer	With broker that supports only MQTT 3.1 (not 3.1.1 compliant), you should pass 3
cleanSession	true	Boolean	Set to false to receive QoS 1 and 2 messages while offline
reconnect	5000	Integer	Reconnect period in milliseconds
timeout	30000	Integer	Connect timeout in milliseconds
queueQoSZero	true	Boolean	If connection is broken, queue outgoing QoS zero messages
username	-	String	The login name
password	-	String	The Password
certPath	-	String	Path to the certificate of the client in PEM format, required for TLS connection
keyPath	-	String	Path to the key of the client in PEM format, required for TLS connection
rejectUnauthorized	true	Boolean	Whether to reject self signed certificates
ca	-	String	Path to the trusted CA list

Device Configuration

Devices must be added manually to the device section of your pimatic config.

Generic sensor

MqttSensor is based on the Sensor device class. Handles numeric and text data from the payload.

{
  "name": "Soil Hygrometer analog reading",
  "id": "wemosd1r2-2",
  "class": "MqttSensor",
  "attributes": [
    {
      "name": "soil-hygrometer",
      "topic": "wemosd1r2/moisture/humidity",
      "type": "number",
      "acronym": "rH"
    }
  ]
},
{
  "name": "ESP01 with battery",
  "id": "esp01",
  "class": "MqttSensor",
  "attributes": [
    {
      "name": "temperature",
      "topic": "myhome/firstfloor/office/esp01/dht11/temperature",
      "type": "number",
      "unit": "°C",
      "acronym": "DHT-11-Temperature"
    },
    {
      "name": "humidity",
      "topic": "myhome/firstfloor/office/esp01/dht11/humidity",
      "type": "number",
      "unit": "%",
      "acronym": "DHT-11-Humidity"
    }
  ]
},
{
  "name": "Mosquitto",
  "id": "mosquitto",
  "class": "MqttSensor",
  "attributes": [
    {
      "name": "connected-clients",
      "topic": "$SYS/broker/clients/connected",
      "type": "number",
      "acronym": "Clients",
      "discrete": true
    },
    {
      "name": "ram-usage",
      "topic": "$SYS/broker/heap/current",
      "type": "number",
      "unit": "B",
      "acronym": "RAM usage"
    }
  ],
  "xAttributeOptions": [
    {
      "name": "connected-clients",
      "displaySparkline": false
    },
    {
      "name": "ram-usage",
      "displaySparkline": false
    }
  ]
}

Supports lookup table to translate received message to another value.

{
  "name": "Sensor with lookup",
  "id": "sensor-with-lookup",
  "class": "MqttSensor",
  "attributes": [
    {
      "name": "state",
      "topic": "some/topic",
      "type": "string",
      "unit": "",
      "acronym": "",
      "messageMap": {
        "0": "Not ready",
        "1": "Ready",
        "2": "Completed"
      }
    }
  ]
}

Accepts flat JSON message

Sample mqtt message: {"rel_pressue": "30.5015", "wind_ave": "0.00", "rain": "0", "rainin": "0", "hum_in": "64", "temp_in_f": "66.4", "dailyrainin": "0", "wind_dir": "225", "temp_in_c": "19.1", "hum_out": "81", "dailyrain": "0", "wind_gust": "0.00", "idx": "2015-10-22 21:41:03", "temp_out_f": "49.6", "temp_out_c": "9.8"}

{
  "class": "MqttSensor",
  "id": "weatherstation",
  "name": "Weather Station",
  "attributes": [
    {
      "name": "temp_in_c",
      "topic": "weatherstation",
      "type": "number",
      "unit": "c",
      "acronym": "Inside Temperature"
    },
    {
      "name": "temp_out_c",
      "topic": "weatherstation",
      "type": "number",
      "unit": "c",
      "acronym": "Outside Temperature"
    }
  ]
}

Accepts JSON message with hierarchy

Sample mqtt message: {"kodi_details": {"title": "", "fanart": "", "label": "The.Victorias.Secret.Fashion.Show.2015.720p.HDTV.x264.mkv", "type": "unknown", "streamdetails": {"video": [{"stereomode": "", "width": 1280, "codec": "h264", "aspect": 1.7777780294418335, "duration": 2537, "height": 720}], "audio": [{"channels": 6, "codec": "ac3", "language": ""}], "subtitle": [{"language": ""}]}}, "val": ""}

{
  "name": "Kodi media info",
  "id": "kodi-media-info",
  "class": "MqttSensor",
  "attributes": [
    {
      "name": "kodi_details.label",
      "topic": "kodi/status/title",
      "type": "string",
      "acronym": "label"
    },
    {
      "name": "kodi_details.streamdetails.video.0.codec",
      "topic": "kodi/status/title",
      "type": "string",
      "acronym": "codec"
    }
  ]
}

It has the following configuration properties:

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
topic	-	String	Topic for device state
qos	0	Number	The QoS level of the topic and stateTopic (if exist)
type	"number"	String	The type of the variable(string or number)
unit	-	String	Attribute unit
acronym	-	String	Acronym to show as value label in the frontend
discrete	false	Boolean	Should be set to true if the value does not change continuously over time.
division	-	Number	Constants that will divide the value obtained
multiplier	-	Number	Constant that will multiply the value obtained
messageMap	-	Object	Even Pimatic 9, you must manually configure this. We're working on it.

Switch Device

MqttSwitch is based on the PowerSwitch device class.

{
  "name": "MQTT Switch",
  "id": "switch",
  "class": "MqttSwitch",
  "topic": "wemosd1r2/gpio/2/set",
  "stateTopic": "wemosd1r2/gpio/2/state"
  "onMessage": "1",
  "offMessage": "0"
}

It has the following configuration properties:

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
topic	-	String	Topic for device state
onMessage	"1"	String	Message to switch on
offMessage	"0"	String	Message to switch off
stateTopic	-	String	Topic that communicates state, if exists
stateValueKey	-	String	The key or path to the state value, given that the payload contains a JSON object
qos	0	Number	The QoS level of the topic and stateTopic (if exist)
retain	false	Boolean	If the published message should have the retain flag on or not.

Device exhibits the following attributes:

Property	Unit	Type	Acronym	Description
state	-	Boolean	-	Switch State, true is on, false is off

The following predicates and actions are supported:

• {device} is turned on|off
• switch {device} on|off
• toggle {device}

Presence Sensor

MqttPresenceSensor is a digital input device based on the PresenceSensor device class.

{
  "name": "MQTT PIR Sensor",
  "id": "mqtt-pir-sensor",
  "class": "MqttPresenceSensor",
  "topic": "wemosd1r2/pir/presence",
  "onMessage": "1",
  "offMessage": "0"
}

It has the following configuration properties:

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
topic	-	String	Topic for device state
stateValueKey	-	String	The key or path to the state value, given that the payload contains a JSON object
onMessage	"1"	String	Message that invokes positive status
offMessage	"0"	String	Message that invokes negative status
qos	0	Number	The QoS level of the topic and stateTopic (if exist)

The presence sensor exhibits the following attributes:

Property	Unit	Type	Acronym	Description
presence	-	Boolean	-	Presence State, true is present, false is absent

The following predicates are supported:

• {device} is present|absent

Contact Sensor

MqttContactSensor is a digital input device based on the ContactSensor device class.

{
  "name": "MQTT Contact",
  "id": "mqtt-contact",
  "class": "MqttContactSensor",
  "topic": "wemosd1r2/contact/state",
  "onMessage": "1",
  "offMessage": "0"
}

It has the following configuration properties:

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
topic	-	String	Topic for device state
stateValueKey	-	String	The key or path to the state value, given that the payload contains a JSON object
onMessage	"1"	String	Message that invokes positive status
offMessage	"0"	String	Message that invokes negative status
qos	0	Number	The QoS level of the topic and stateTopic (if exist)

The presence sensor exhibits the following attributes:

Property	Unit	Type	Acronym	Description
contact	-	Boolean	-	Contact State, true is opened, false is closed

The following predicates are supported:

• {device} is opened|closed

Dimmer Device

MqttDimmer is based on the Dimmer device class.

{
  "name": "MQTT Dimmer",
  "id": "mqtt-dimmer",
  "class": "MqttDimmer",
  "topic": "wemosd1r2/pcapwm/5/brightness",
  "stateTopic": "wemosd1r2/pcapwm/5/state",
  "resolution": 4096
},
    {
  "topic": "dimmer/cmd",
  "resolution": 1024,
  "id": "dimmer",
  "name": "Dimmer",
  "class": "MqttDimmer",
  "message": "pwm,15,value,2000"
}

It has the following configuration properties:

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
topic	-	String	Topic for control dimmer brightness.
resolution	256	Integer	Resolution of this dimmer. For percent set 101.
message	"value"	String	Format for outgoing message.
stateTopic	-	String	Topic that communicates state, if exists
stateValueKey	-	String	The key or path to the state value, given that the payload contains a JSON object
qos	0	Number	The QoS level of the topic and stateTopic (if exist)
retain	false	Boolean	If the published message should have the retain flag on or not.

The Dimmer Action Provider:

• dim [the] device to value%

Buttons Device

MqttButtons is based on the ButtonsDevice device class.

{
  "name": "Buttons",
  "id": "buttons-demo",
  "class": "MqttButtons",
  "buttons": [
    {
      "id": "button1",
      "text": "Press me",
      "topic": "some/topic",
      "message": "1"
    }
  ]
}

It has the following configuration properties for each button:

Property	Default	Type	Description
brokerId	"default"	String	Id of the broker
id	-	String	Button id
text	-	String	Button text
topic	-	String	Topic for device state
message	-	String	Publish message when pressed
stateTopic	-	String	Topic that communicates state, if exists
stateValueKey	-	String	The key or path to the state value, given that the payload contains a JSON object
qos	0	Number	The QoS level of the topic and stateTopic (if exist)
confirm	false	Boolean	Ask the user to confirm the button press

The Button Action Provider

• press [the] device

Rules

You can publish mqtt messages in rules with the action:

publish mqtt message "<string with variables>" on topic "<string with variables>" [on broker ListOfBrokers] [qos: 0|1|2] [retain: true|false]

"rules": [
  {
    "id": "my-rule",
    "rule": "when every 3 seconds then publish mqtt message \"msg\" on topic \"topic\" on broker default qos: 1 retain: true",
    "active": true,
    "logging": false,
    "name": "Publish mqtt"
  }
]

You can trigger rules by mqtt messages with the predicate:

mqtt received "<message>" on topic "<topic>" [via broker ListOfBrokers] [qos: 0|1|2]

"rules": [
  {
    "id": "my-rule-2",
    "name": "Receive mqtt",
    "rule": "when mqtt received \"1\" on topic \"topic\" via broker default qos: 0 then log \"Yeah!\"",
    "active": true,
    "logging": true
  }
]

To Do

'x' marks done To Do items

• Add RGB device
• Reflecting external condition for dimmer
• Reflecting external condition for buttons
• QoS and retain flag
• Processing JSON-encoded object
• Make payload configurable for all device
• Buttons Device
• Configurable PWM range for Dimmer
• Configurable CIE1931 correction for Dimmer
• Support for more then one Broker
• Sending all variables from Pimatic to Broker/s
• Control Pimatic over MQTT :)
• Integration with ActionProvider
• TLS support
• Add shutter device
• Add text and numeric input device
• JSON filtering for state values

Credits

sweet pi for his work on best automatization software Pimatic and all guys from the pimatic community.

Andre Miller for for his module pimatic-mqtt-simple from which it comes also part of the code.

Marcus Wittig for his nice module pimatic-johnny-five which was a big inspiration.