|
|
| Line 1: |
Line 1: |
| − | {{Top}}
| + | <big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big> |
| | | | |
| − | =Overview=
| + | <big> |
| − | Hubitat allows for opening and maintaining a connection to an MQTT broker from the hub. All code needs to be contained in a driver, there is no option to open an MQTT client connection from an app. Hubitat provides methods to connect and disconnect to the broker, subscribe and publish messages to topics. In addition it is required to create a method in the driver that accepts incoming messages (parse) and another method that will be called with any status updates for the client connection (mqttClientStatus).
| + | This document is available at: http://docs2.hubitat.com/en/developer/interfaces/mqtt-interface |
| − | | + | </big> |
| − | =Methods=
| |
| − | | |
| − | ==Hubitat Provided Methods (Since 2.1.2) ==
| |
| − | | |
| − | ===<code>connect</code>===
| |
| − | | |
| − | :;Signature
| |
| − | :: <code>void connect(String broker, String clientId, String username, String password)</code>
| |
| − | :: <code>void connect(String broker, String clientId, String username, String password, options (name/value pairs))</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: broker - The url of the broker to connect to.
| |
| − | :: clientId - The client id to use when connecting to the broker.
| |
| − | :: username - The username to use when connecting to the broker, use null if no username is necessary.
| |
| − | :: password - The password to use when connecting to the broker, use null if no password is necessary.
| |
| − | :: options - Optional parameters to configure the MQTT connection. Possible values:
| |
| − | :::''byteInterface'' - defaults to 'false'. If set to true, messages are handled as byte arrays and will be hex string encoded.
| |
| − | :::''lastWillTopic'' - The topic to publish to if connection is lost (Since 2.1.2)
| |
| − | :::''lastWillQos'' - The qos to use for publishing last will message, possible values are 0,1 or 2 (Since 2.1.2)
| |
| − | :::''lastWillMessage'' - The message to publish if connection is lost (Since 2.1.2)
| |
| − | :::''lastWillRetain'' - Option to set last will message to retained, defaults to false (Since 2.1.2)
| |
| − | :::''cleanSession'' - Option to set the clean_session flag for the connection (Since 2.2.2)
| |
| − | :::''tlsVersion'' - The TLS version to use when connecting to broker, possible values are 1.0, 1.1, 1.2 Defaults to 1.2 if not specified (Since 2.2.2)
| |
| − | :::''caCertificate'' - The CA certificate for the TLS/SSL connection in PEM format (Since 2.2.2)
| |
| − | :::''clientCertificate'' - The client certificate (X.509) for the TLS connection in PEM format. Optional but requires privateKey is specifed (Since 2.2.2)
| |
| − | :::''privateKey'' - The private key for the TLS connection in PEM format. Optional but requires clientCertificate if specified (Since 2.2.2)
| |
| − | | |
| − | :;Examples | |
| − | | |
| − | <pre>
| |
| − | // Connect to MQTT broker
| |
| − | interfaces.mqtt.connect("tcp://test.mosquitto.org:1883", "mqtttest123", null, null)
| |
| − | </pre>
| |
| − | | |
| − | <pre>
| |
| − | // Connect to MQTT broker with last will
| |
| − | interfaces.mqtt.connect("tcp://test.mosquitto.org:1883",
| |
| − | "mqtttest456",
| |
| − | null,
| |
| − | null,
| |
| − | lastWillTopic: "/my/last/will",
| |
| − | lastWillQos: 0,
| |
| − | lastWillMessage: "I died")
| |
| − | </pre>
| |
| − | | |
| − | <pre>
| |
| − | // connect to MQTT broker with TLS and certificate (AWS IOT Core)
| |
| − | // Note, all 4 parameters (tlsVersion, privateKey, caCertificate, clientCertificate) are required for TLS secure connection
| |
| − | // if any are missing the connection won't work or will fall back to non secure
| |
| − | String clientCert = """-----BEGIN CERTIFICATE-----
| |
| − | MIIDWjCCAkKgAwIBAgIVANPd/DAZc5xaB3y6tuyA4Vi2pdyfMA0GCSqGSIb3DQEB
| |
| − | ...
| |
| − | 7qr3/l5YwtmArBPXAS4s60bfFwEVrLEpS9QPAIMnAFNWRkuwDNR1EZ3TcP12Ew==
| |
| − | -----END CERTIFICATE-----"""
| |
| − | | |
| − | String caCert = """-----BEGIN CERTIFICATE-----
| |
| − | MIIEkjCCA3qgAwIBAgITBn+USionzfP6wq4rAfkI7rnExjANBgkqhkiG9w0BAQsF
| |
| − | ...
| |
| − | akcjMS9cmvqtmg5iUaQqqcT5NJ0hGA==
| |
| − | -----END CERTIFICATE-----"""
| |
| − | | |
| − | String privateKey = """-----BEGIN RSA PRIVATE KEY-----
| |
| − | MIIEpQIBAAKCAQEA3D1ZquBWJDtLOpVlDwYHW0ayaE+T9ZPV/bq39NT1KaKG+1w3
| |
| − | ...
| |
| − | AeuFNEqh9ExHLMPw/McjOKQ+4oG42ZGox7WekbIWMt0CZvlbFYE0Ha0=
| |
| − | -----END RSA PRIVATE KEY-----"""
| |
| − | | |
| − | interfaces.mqtt.connect("ssl://q65g7jujvagsuy-ats.iot.us-east-2.amazonaws.com",
| |
| − | 'testClient',
| |
| − | null,
| |
| − | null,
| |
| − | tlsVersion: "1.2",
| |
| − | privateKey: privateKey,
| |
| − | caCertificate: caCert,
| |
| − | clientCertificate: clientCert)
| |
| − | </pre> | |
| − | | |
| − | ===<code>disconnect</code>===
| |
| − | | |
| − | :;Signature
| |
| − | :: <code>void disconnect()</code>
| |
| − | | |
| − | ===<code>subscribe</code>===
| |
| − | :;Signature
| |
| − | :: <code>void subscribe(String topicFilter, int qos = 1)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: topicFilter - The topic / filter to subscribe to.
| |
| − | :: qos - (optional, defaults to 1) The qos to use when subscribing.
| |
| − | | |
| − | ===<code>isConnected</code>===
| |
| − | :;Signature
| |
| − | :: <code> boolean isConnected()</code>
| |
| − | | |
| − | :;Returns
| |
| − | :: boolean - true if client is connected, false otherwise.
| |
| − | | |
| − | ===<code>unsubscribe</code>===
| |
| − | :;Signature
| |
| − | :: <code>void unsubscribe(String topicFilter)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: topicFilter - The topic filter to unsubscribe from.
| |
| − | | |
| − | ===<code>publish</code>===
| |
| − | :;Signature
| |
| − | :: <code>void publish(String topic, String payload, int qos = 1, boolean retained = false)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: topic - The topic to publish the message to.
| |
| − | :: payload - The body of the message.
| |
| − | :: qos - (optional, defaults to 1) The qos to use when publishing the message.
| |
| − | :: retained - (optional, defaults to false) Retain message in queue if subscriber is not listening.
| |
| − | | |
| − | ===<code>parseMessage</code>===
| |
| − | :;Signature
| |
| − | :: <code>Map parseMessage(String stringToParse)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: stringToParse - The string coming from the MQTT brokers subscribed topic.
| |
| − | | |
| − | :;Returns
| |
| − | :: Map - the string passed as a parameter is split into a Map and returned.
| |
| − | | |
| − | :;Examples
| |
| − | | |
| − | // parse message
| |
| − | interfaces.mqtt.parseMessage(description)
| |
| − | | |
| − | ==Hubitat Provided Methods (Deprecated) ==
| |
| − | | |
| − | ===<code>mqttConnect</code>===
| |
| − | | |
| − | :;Signature
| |
| − | :: <code>void hubitat.helper.InterfaceUtils.alphaV1mqttConnect(DeviceWrapper device, String broker, String clientId, String username, String password)</code>
| |
| − | :: <code>void hubitat.helper.InterfaceUtils.alphaV1mqttConnect(DeviceWrapper device, String broker, String clientId, String username, String password, options (name/value pairs))</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: device - The current device that is calling the method.
| |
| − | :: broker - The url of the broker to connect to.
| |
| − | :: clientId - The client id to use when connecting to the broker.
| |
| − | :: username - The username to use when connecting to the broker, use null if no username is necessary.
| |
| − | :: password - The password to use when connecting to the broker, use null if no password is necessary.
| |
| − | :: options - Optional parameters to configure the MQTT connection. Possible values:
| |
| − | :::''byteInterface'' - defaults to 'false'. If set to true, messages are handled as byte arrays and will be hex string encoded.
| |
| − | :::''lastWillTopic'' - The topic to publish to if connection is lost (Since 2.1.2)
| |
| − | :::''lastWillQos'' - The qos to use for publishing last will message, possible values are 0,1 or 2 (Since 2.1.2)
| |
| − | :::''lastWillMessage'' - The message to publish if connection is lost (Since 2.1.2)
| |
| − | :::''lastWillRetain'' - Option to set last will message to retained, defaults to false (Since 2.1.2)
| |
| − | | |
| − | :;Examples
| |
| − | | |
| − | // Connect to MQTT broker
| |
| − | hubitat.helper.InterfaceUtils.alphaV1mqttConnect(device, "tcp://test.mosquitto.org:1883", "mqtttest123", null, null)
| |
| − | | |
| − | // Connect to MQTT broker with last will
| |
| − | hubitat.helper.InterfaceUtils.alphaV1mqttConnect(device, "tcp://test.mosquitto.org:1883", "mqtttest456", null, null, lastWillTopic: "/my/last/will", lastWillQos: 0, lastWillMessage: "I died")
| |
| − | | |
| − | | |
| − | ===<code>mqttDisconnect</code>===
| |
| − | | |
| − | :;Signature
| |
| − | :: <code>void hubitat.helper.InterfaceUtils.alphaV1mqttDisconnect(DeviceWrapper device)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: device - The current device that is calling the method.
| |
| − | | |
| − | ===<code>mqttSubscribe</code>===
| |
| − | :;Signature
| |
| − | :: <code>void hubitat.helper.InterfaceUtils.alphaV1mqttSubscribe(DeviceWrapper device, String topicFilter, int qos = 1)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: device - The current device that is calling the method.
| |
| − | :: topicFilter - The topic / filter to subscribe to.
| |
| − | :: qos - (optional, defaults to 1) The qos to use when subscribing.
| |
| − | | |
| − | ===<code>mqttUnsubscribe</code>===
| |
| − | :;Signature
| |
| − | :: <code>void hubitat.helper.InterfaceUtils.alphaV1mqttUnsubscribe(DeviceWrapper device, String topicFilter)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: device - The current device that is calling the method.
| |
| − | :: topicFilter - The topic filter to unsubscribe from.
| |
| − | | |
| − | ===<code>mqttPublish</code>===
| |
| − | :;Signature
| |
| − | :: <code>void hubitat.helper.InterfaceUtils.alphaV1mqttPublish(DeviceWrapper device, String topic, String payload, int qos = 1, boolean retained = false)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: device - The current device that is calling the method.
| |
| − | :: topic - The topic to publish the message to.
| |
| − | :: payload - The body of the message.
| |
| − | :: qos - (optional, defaults to 1) The qos to use when publishing the message.
| |
| − | :: retained - (optional, defaults to false) Retain message in queue if subscriber is not listening.
| |
| − | | |
| − | ===<code>parseMqttMessage</code>===
| |
| − | :;Signature
| |
| − | :: <code>Map hubitat.helper.InterfaceUtils.alphaV1parseMqttMessage(String stringToParse)</code>
| |
| − | | |
| − | :;Parameters
| |
| − | :: stringToParse - The string coming from the MQTT brokers subscribed topic.
| |
| − | | |
| − | :;Returns
| |
| − | :: Map - the string passed as a parameter is split into a Map and returned.
| |
| − | | |
| − | ==User defined methods==
| |
| − | | |
| − | ===<code>parse(String message)</code>===
| |
| − | This method is called with any incoming messages from the subscribed topics of the MQTT broker. This is a standard method for drivers.
| |
| − | | |
| − | ===<code>mqttClientStatus(String message)</code>===
| |
| − | This method is called with any status messages from the MQTT client connection (disconnections, errors during connect, etc)
| |
| − | The string that is passed to this method with start with "Error" if an error occurred or "Status" if this is just a status message.
| |
