MQTT Client Library Encylcopedia - Paho Go
Written by Al Stockdill-Mander
Category: MQTT MQTT Client Library
Published: November 9, 2015
|Paho Go Client|
|License||EPL and EDL|
Back in October 2013 my job involved working on the other Paho MQTT client libraries, and having picked Go as a new language to learn, what better way to learn it than to write an MQTT client? :) Starting as a side project with two colleagues the code was contributed to Paho in January 2014 and continued to be developed in the open.
The Paho Go library also includes a packet library that can be used independently for reading and writing MQTT packets.
Currently at 0.9 the Paho Go library is imminently to release a 1.0 stable version, actively maintained it has been picked up by commercial and open source projects such as Gobot http://gobot.io/
Assuming you already having a working Go installation the easiest way to get the Paho Go library is to run;
go get git.eclipse.org/gitroot/paho/org.eclipse.paho.mqtt.golang.git
This will download the library to your $GOPATH/src directory, to make use of the library in your application add
to your list of imports.
To connect to an MQTT broker the two things that must be provided are the URL of the broker and a client ID to be used. To do this we create a new ClientOptions struct and add a broker url and set the client ID. The functions that operate on a ClientOptions struct return a pointer to the altered struct allowing you to chain the functions together.
Inspired by the Paho Java library the Paho Go library allows you to optionally receive a token when performing actions that can be used to determine when the action is complete. Calling
token.Wait() is a blocking call that will only return when the action is finished,
token.WaitTimeout(<time>) will wait up to
Connect with MQTT 3.1 or MQTT 3.1.1
By default the Paho Go library will attempt to connect to an MQTT broker using 3.1.1, if that fails it will automatically fallback and attempt to connect using 3.1.
SetProtocolVersion() allows you to explicitly set the version to connect with, 4 is 3.1.1, 3 is 3.1. If you do explicitly set a version the fallback mechanism is disabled.
Connect with LWT
There are two functions for setting the LWT in the Paho Go library,
SetBinaryWill(), and both take 4 parameters. The first in both is a string of the topic to which the LWT will be published. The second is the payload of the message, in
SetWill() this is a string value, in
SetBinaryWill() it is a byte. The third parameter is the qos level of the message and the fourth is a bool for the retained flag of the LWT
Connect with Username / Password
In the above sample c is an mqtt.Client as returned by mqtt.NewClient(). Publish takes 4 parameters; A string of the topic to publish to, the qos value for the message, a bool for the retain property of the message, and either a string or byte for the payload. Also I’m demonstrating how to use Publish() with and without using a token.
Publish a retained message
Subscribe() takes 3 paramters; a string of the topic to subscribe to, the qos level of the subscription, and a function to be called when a message matching this subscription is received. The callback function must have the signature
It is acceptable to pass nil as the callback function, in this case when a message is received the library will call the client default message handler (if set), which can be set by calling
SetDefaultPublishHandler() on a ClientOptions struct.
Unsubscribe() will accept more than one topic to Unsubscribe from, each should be a separate string parameter.
Disconnect() takes one parameter which is the number of milliseconds to allow for the library to finish any work in progress.
Using SSL / TLS
Connecting via SSL/TLS to a broker that supports it is as simple as changing the scheme part of the broker URL; ssl, tls or tcps are all supported as indicating the client should connect securely. This assumes you are connecting to a broker that uses a certificate known by the system, if you are using self signed certificates you will need to a tls.Config struct and pass it to ClientOptions with
SetTLSConfig(). The samples directory of the Paho Go library has an example of doing this.