wutu / pimatic-mqtt

MQTT plugin for Pimatic
https://pimatic.org/plugins/pimatic-mqtt/
GNU Affero General Public License v3.0
9 stars 13 forks source link
mqtt pimatic plugin

pimatic-mqtt

npm version

MQTT plugin for Pimatic

Screenshots

Screenshot 1 Screenshot 2 Screenshot 3 Screenshot 4 Screenshot 5

Status of implementation

This version supports the following

Sponsoring

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

PayPal Donate Button

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:

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:

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:

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:

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

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

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.