--- title: "MQTT client" canonical: "https://docs.cuesystem.com/space/CVCDD/575209563/MQTT%20client" format: markdown --- > Macro (toc) --- # Description This driver is used for communication with the MQTT broker (server). The MQTT 3.1.1 protocol is supported. # Resources Read [https://www.hivemq.com/mqtt-essentials/](https://www.hivemq.com/mqtt-essentials/) or download MQTT standard and essentials. # Properties | | | | | | --- | --- | --- | --- | | Property name | Data type | Default value | Description | | Mqtt Broker | | Broker IP | Text | empty | IP address or domain name of the MQTT broker. | | Broker TCP Port | Long | 1883 | TCP port of the MQTT broker. | | User Name | ByteString | empty | User name for client authentication and authorization. | | User Password | ByteString | empty | User password for client authentication and authorization. | | SSL/TLS enable | Boolean | False | Set True if the MQTT broker can use SSL/TLS encryption, otherwise set False. | | Mqtt Client | | Client ID | ByteString | myCueClient | The client identifier (ClientId) identifies each MQTT client that connects to an MQTT broker. The broker uses the ClientId to identify the client and the current state of the client.Therefore, this Id should be unique per client and broker. | | KeepAlive Time | Time | :30 | The keep alive is a time interval that the client specifies and communicates to the broker when the connection established. This interval defines the longest period of time that the broker and client can endure without sending a message. The client commits to sending regular PING Request messages to the broker. The broker responds with a PING response. This method allows both sides to determine if the other one is still available. | | Last Will Testament | | Will Topic | ByteString | empty | [https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/](https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/) | | Will Message | ByteString | offline | The last will message is part of the Last Will and Testament (LWT) feature of MQTT. This message notifies other clients when a client disconnects ungracefully. | | Will QoS | Byte | 1 | Last will QoS. | | Will Retain | Boolean | False | Last will retain flag. | | Communication | | Connect timeout | Time | :5.0000 | The timeout for connection to MQTT broker. | | Reply timeout | Time | :3.0000 | The timeout for waiting for a response to an MQTT message. | | Debug | | DebugPrint | Boolean | False | If you set it to True, the driver will print debug messages. | # Functions ## ConnectBroker This function connects to the MQTT broker. If the connection succeeds, the function returns True and the automatic reconnection of the driver to the MQTT broker is started. If the connection fails the function returns False. #### Syntax ```visualbasic Function ConnectBroker( ByRef MQTTBrokerReturnCode As Long, Optional bCleanSession As Boolean := True) As Boolean ``` #### Parameters MQTTBrokerReturnCode [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) - MQTT broker return code value. If the connection was rejected by the MQTT broker, use this value to find out why the connection was rejected by the MQTT broker. The following table desribes the meanings of the MQTTBrokerReturnCode values: | Return Code | Return Code Response | | --- | --- | | 0 | Connection accepted | | 1 | Connection refused, unacceptable protocol version | | 2 | Connection refused, identifier rejected | | 3 | Connection refused, server unavailable | | 4 | Connection refused, bad user name or password | | 5 | Connection refused, not authorized | bCleanSession [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - The clean session flag tells the broker whether the client wants to establish a persistent session or not. In a persistent session (bCleanSession = False), the broker stores all subscriptions for the client and all missed messages for the client that subscribed with a [https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/](https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/) level 1 or 2. If the session is not persistent (bCleanSession = True), the broker does not store anything for the client and purges all information from any previous persistent session. #### Return value [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - True on success or False if an error occurs. ## DisconnectBroker This function disconnects from the MQTT broker, terminates the automatic reconnection, and removes all remembered subscribed topics. #### Syntax ```visualbasic Function DisconnectBroker() ``` ## IsConnected This function returns True if the driver is connected to the MQTT broker, otherwise, it returns False. #### Syntax ```visualbasic Function IsConnected() As Boolean ``` #### Return value [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - True if the driver is connected to the MQTT broker, otherwise, it returns False. ## Publish This function is used to publish the value to the MQTT broker. The function returns True if publishing the value was successful, otherwise, it returns False. The maximum message length is 65 000 bytes. QoS 0 and QoS 1 is supported, QoS 2 is not supported. See QoS description [https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/](https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/). The function returns False if: - The length of the message being sent is longer than 65 000 bytes. - The parameter QoS < 0 or QoS > 1. - If QoS = 1 and the timeout for receiving a PUBACK response has expired. The timeout value is set in the Reply timeout property. - Sending to MQTT broker failed. - Driver is not connected to the MQTT broker. #### Syntax ```visualbasic Function Publish( bsTopic As ByteString, bsValue As ByteString, Optional iQoS As Byte :=0, Optional bRetain As Boolean :=False) As Boolean ``` #### Parameters bsTopic [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) - topic of the message. bsValue [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) - content of the message. iQoS [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) - QoS. The **allowed** QoS **values are 0 or 1**. If another value is specified, the function returns False. For details about QoS see [https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/](https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/). bRetain [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - MQTT message retain flag value. If **True **the broker stores the last retained message and the corresponding QoS for that topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message immediately after they subscribe. **The broker stores only one retained message per topic**. For more details see [https://www.hivemq.com/blog/mqtt-essentials-part-8-retained-messages/](https://www.hivemq.com/blog/mqtt-essentials-part-8-retained-messages/). #### Return value [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - True on success or False if an error occurs. ## Subscribe This function registers the receipt of a message that matches the specified topic. The function returns True if the attempt succeeded. Otherwise, it returns False. The Subscribe function **can be called after ConnectBroker**, which **returned True**. If Subscribe is called, the driver remembers it and after any reconnection to the MQTT broker, Subscribe is already called automatically. The driver remembers a maximum of **100 Subscribe** and a maximum **topic length of 500 bytes**. #### Syntax ```visualbasic Function Subscribe( bsTopic As ByteString, Optional iQOS As Byte :=0) As Boolean ``` #### Parameters bsTopic [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) - The topic for which subscribe is performed. The maximum length of a topic is 500 bytes. iQOS [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) - QoS. The **allowed** QoS **values are 0 or 1**. If another value is specified, the function returns False. For details about QoS see [https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/](https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/). #### Return value [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - True on success or False if an error occurs. ## Unsubscribe This function unregisters the receipt of messages with the corresponding topic. It returns True if everything succeeded otherwise returns False. #### Syntax ```visualbasic Function Unsubscribe (bsTopic As ByteString) As Boolean ``` #### Parameters bsTopic [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) - The topic for which unsubscribe is performed. #### Return value [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - True on success or False if an error occurs. # Events ## OnPublishReceived This event is raised when a message published by the MQTT broker is received. The event is a function type, so the **handler should take a short time**. #### Syntax ```visualbasic Event OnPublishReceived As Function( bsTopic As ByteString, bsMessage As ByteString, iQoS As Byte, retained As Boolean) ``` #### Parameters bsTopic [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) - Topic of received message. bsMessage [ByteString](/wiki/spaces/CVCHELP/pages/495058958/Data+types#ByteString) - Content of the received message. iQoS [Long](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Long) - QoS of received message. retained [Boolean](/wiki/spaces/CVCHELP/pages/495058958/Data+types#Boolean) - The retain flag value of the received message.