Component: MQTT Client (Comms: IoT/Cloud)

Author	Matrix TSL
Version	1.5
Category	Comms: IoT/Cloud

MQTT Client component

A component providing access to MQTT IoT client. The client can connect to a MQTT server such as ThingSpeak. Allowing IoT type data to be published and read back.

Version information

Library Version, Component Version, Date, Author, Info
7, 1.1, 23-07-24, BR, Added Max Packet Size property to allow the size of a single packet to be altered by the user
8, 1.1, 30-07-24, BR, Resolved ESP compile error due to missing return and added TopicTooLong error
9, 1.2, 11-08-26, Remaining Length is now encoded and decoded as a proper Variable Byte Integer, so packets are no longer limited to 127 bytes
10, 1.2, 11-08-26, Connect and ConnectTo now share a single Prv_DoConnect implementation
11, 1.2, 11-08-26, PacketTransfer reply buffer was hardcoded to 64 bytes, now uses Max Packet Size
12, 1.2, 11-08-26, UNSUBSCRIBE no longer sends a spurious QoS byte and its Remaining Length is correct
13, 1.2, 11-08-26, Read masks the packet type nibble, so PUBLISH packets with DUP, QoS or RETAIN flags set are no longer discarded
14, 1.2, 11-08-26, Full QoS 1 and QoS 2 support with Packet Identifiers and acknowledgement handshakes, Quality of Service property unhidden
15, 1.3, 11-08-26, Added Retain support - Retain property, PublishRetain and PublishByteArrayRetain, plus GetRetain and GetDup for incoming messages
16, 1.3, 11-08-26, Added Last Will and Testament - Will Topic, Message, QoS and Retain properties sent in the CONNECT packet
17, 1.4, 11-08-26, ErrorAsString return buffer reduced from 2000 to 48 bytes
18, 1.4, 11-08-26, PacketTransfer returned u16 packet sizes through a u8, so sends of 256 bytes or more reported failure. Widened to u16
19, 1.4, 11-08-26, Publish and PublishByteArray now return 1 or 0 consistently at every QoS level
20, 1.4, 11-08-26, Added IsConnected and GetGrantedQoS
21, 1.4, 11-08-26, Acknowledge Timeout and Acknowledge Retries properties replace the fixed four attempts at the network timeout
22, 1.4, 11-08-26, Corrected the CONNACK code 4 error string and the Max Packet Size and Client identifier help text
23, 1.5, 11-08-26, Added Clean Start - the Clean Session flag was previously hardwired on. Session Present is read from the CONNACK and exposed by GetSessionPresent
24, 1.5, 11-08-26, The Packet Identifier sequence is no longer reset when the broker resumes an existing session

Detailed description

No detailed description exists yet for this component

Examples

The MQTT component requires connection to a Network Comms component via the "Network Component" property, to provide the bridge for simulated TCP/IP communication.

The Network Comms component can then be linked to an embedded TCP/IP component to provide embedded TCP/IP support.

Here is a typical setup for using MQTT on a Raspberry Pi.

Local Weather

A simple example demonstrating how to use MQTT with Flowcode SCADA to get the local weather conditions.

The example shows temperatures from Halifax in the UK and from Sydney in Australia.

SCADA BBC TEMPERATURES

Publish

Raspberry Pi

Here we have an embedded Raspberry Pi project connected to an I2C Sensor, the sensor is sampled and the data is published to a MQTT server.

RPI3 MQTT IOT EBM016

ESP8266 Module

Here we have an embedded project using an ESP8266 wifi module, an analogue input is sampled and the data is published to a MQTT server.

MQTT IOT ESP8266

Subscribe

ESP8266 Module

Here we subscribe to a topic and receive it back into Flowcode embedded using an ESP8266 module.

Subscribe ESP8266 MQTT

Flowcode App Developer

Here we subscribe to a topic and receive it back into Flowcode App Developer.

Subscribe App Developer MQTT

Making your own Raspberry Pi based MQTT Broker

Click here for instructions on creating your own Raspberry Pi MQTT Broker.

Macro reference

Connect

	Connect
Connect to the MQTT Server using the Host, Port and Client identifier properties. Returns the connected state. 0 if not connected, 1 if successful connection, or already connected.
- BYTE	Return

ConnectTo

	ConnectTo
Connect to a variable MQTT Server, overriding the Host, Port and Client identifier properties. Returns the connected state. 0 if not connected, 1 if successful connection, or already connected.
- STRING	Host
- UINT	Port
- STRING	ClientID
Client identifier name - must be unique on server
- BYTE	Return

Disconnect

	Disconnect
Disconnects from the MQTT server and the network
- BYTE	Return

ErrorAsString

	ErrorAsString
- BYTE	Error
- STRING	Return

GetDup

	GetDup
Returns non-zero if the last received (Read) packet was flagged by the broker as a redelivery of a message it has already sent. Useful for spotting duplicates at QoS 2.
- BYTE	Return

GetGrantedQoS

	GetGrantedQoS
Returns the QoS the broker actually granted for the last Subscribe. A broker may grant a lower QoS than requested, so this can be less than the Quality of Service property. Returns 0x80 if the last Subscribe was refused.
- BYTE	Return

GetPayload

	GetPayload
Get the Payload of the last received (Read) packet. Returns the number of bytes for the Payload
- STRING	Payload
- BYTE	Size
Byte count the Payload buffer
- BYTE	Return

GetRetain

	GetRetain
Returns non-zero if the last received (Read) packet was a retained message replayed by the broker, rather than a live publication.
- BYTE	Return

GetSessionPresent

	GetSessionPresent
Returns non-zero if the broker resumed a previous session on the last successful connect. Only meaningful when Clean Start is cleared. If this returns 0 the broker did not have a session for this Client identifier, so your subscriptions were lost and you need to Subscribe again.
- BYTE	Return

GetTopic

	GetTopic
Get the Topic of the last received (Read) packet. Returns the number of bytes for the Topic
- STRING	Topic
- BYTE	Size
Byte count the Topic buffer
- BYTE	Return

Initialise

	Initialise
- VOID	Return

IsConnected

	IsConnected
Returns non-zero while the client holds an open MQTT session with the broker. Cleared by Disconnect, and also if a send fails, so it is worth checking before Publish.
- BYTE	Return

LastError

	LastError
Returns the last error
- BYTE	Return

Ping

	Ping
Ping packet is sent to the Server and checks for a reply. Returns non-zero value if successful
- BYTE	Return

Publish

	Publish
Publish a string payload to the server (broker) Returns non-zero if successful. At QoS 1 and QoS 2 this call also waits for the broker to acknowledge the message.
- STRING	Topic
- STRING	Payload
- BYTE	Return

PublishByteArray

	PublishByteArray
Publish a byte array payload to the server (broker) Returns non-zero if successful. At QoS 1 and QoS 2 this call also waits for the broker to acknowledge the message.
- STRING	Topic
- BYTE	Payload
- UINT	PayloadSize
Number of bytes in the payload array
- BYTE	Return

PublishByteArrayRetain

	PublishByteArrayRetain
As PublishByteArray, but the Retain flag is given per message instead of coming from the Retain property. A retained message is kept by the broker and handed to any client that subscribes to the Topic later. Publishing an empty retained payload clears a previously retained message. Returns non-zero if successful.
- STRING	Topic
- BYTE	Payload
- UINT	PayloadSize
Number of bytes in the payload array
- BYTE	Retain
Non-zero to ask the broker to retain this message
- BYTE	Return

PublishRetain

	PublishRetain
As Publish, but the Retain flag is given per message instead of coming from the Retain property. A retained message is kept by the broker and handed to any client that subscribes to the Topic later. Publishing an empty retained payload clears a previously retained message. Returns non-zero if successful.
- STRING	Topic
- STRING	Payload
- BYTE	Retain
Non-zero to ask the broker to retain this message
- BYTE	Return

Read

	Read
Read incoming data. Returns non-zero if a PUBLISH packet was received. Use GetTopic and GetPayload to read the contents. Incoming QoS 1 messages are acknowledged with a PUBACK automatically. Incoming QoS 2 messages are acknowledged with a PUBREC, and the matching PUBREL is answered with a PUBCOMP on a later call to Read. The message itself is handed to the caller as soon as it arrives, so a redelivered message may be seen twice.
- UINT	Return

Subscribe

	Subscribe
Subscribe to a Topic. Must be Connected first. The Quality of Service property is sent as the requested maximum QoS for the subscription. Returns non-zero if successful
- STRING	Topic
- BYTE	Return

Unsubscribe

	Unsubscribe
Unsubscribe from a Topic. Must be Connected first Returns non-zero if successful
- STRING	Topic
- BYTE	Return

Property reference

	Properties
	LinkTo
	Host
Address of MQTT Broker Can be an IP Address or URL (URL only supported by some hardware platforms)
	Port
Port used by MQTT Broker Default 1883 for unencrypted access and 8883 for encrypted access.
	Client identifier
Client identifier (Maximum length 23 characters) Must be unique to the broker. Brokers are only obliged to accept 23 characters, though many accept more.
	Clean Start
Controls whether the broker starts a brand new session or resumes the previous one. This is the Clean Session flag in MQTT 3.1.1 and is renamed Clean Start in MQTT 5.0. Leave this ticked for a fresh session every time - subscriptions and any messages the broker was holding for this client are discarded on connect. Clear it to resume a previous session, so subscriptions survive a reconnect and the broker redelivers QoS 1 and QoS 2 messages you missed. This needs a stable Client identifier, since that is how the broker finds the session, and it is ignored if the Client identifier is empty. Always check GetSessionPresent after connecting - if it returns 0 the session was not resumed and you must Subscribe again. MQTT 3.1.1 has no way to say how long the session should be kept, so that is up to the broker.
	Network Timeout
Maximum time in mS to wait for network responses
	Read Timeout
Amount of time in ms to wait for incoming messages.
	Keep Alive
The Keep Alive is the maximum time interval that is permitted to elapse between the point at which the Client finishes transmitting one Control Packet and the point it starts sending the next, measured in seconds.
	Authentication
Selects if the broker is open or if the broker requires a username and password.
	Max Packet Size
Sets the number of bytes that can be sent and received in a single packet. A packet is 2 to 5 bytes of fixed header, then 2 bytes of topic length, the topic itself, 2 more bytes of packet identifier at QoS 1 and QoS 2, and finally the payload. Publish truncates the payload rather than overrun this limit.
	Quality of Service
Quality of Service applied to Publish, and requested as the maximum QoS when you Subscribe. At most once (QoS 0) sends the message and does not wait. At least once (QoS 1) waits for the broker to acknowledge the message, and the message may be delivered more than once. Exactly once (QoS 2) runs the full four step handshake with the broker. QoS 1 and QoS 2 make Publish slower, because it waits for the broker before returning. Incoming messages are acknowledged automatically by Read.
	Retain
Sets the default Retain flag used by Publish. When a message is retained the broker keeps the last value for the Topic and hands it to any client that subscribes later. Use PublishRetain to override this on a single message.
	Last Will and Testament
Registers a Will message with the broker when connecting. If this client disconnects without sending a DISCONNECT packet, for example because it lost power or the network dropped, the broker publishes the Will Message to the Will Topic on its behalf. Commonly used to flag a device as offline.

Component Source Code

Please click here to download the component source project: FC_Comp_Source_MQTT_Client.fcfx

Please click here to view the component source code (Beta): FC_Comp_Source_MQTT_Client.fcfx