goqtt

goqtt is a simple MQTT client library. It is intended for lightweight MQTT applications where security and data guarantees are not important (see limitations below).

Install

Using go 1.13 or higher, install using go modules:

go get github.com/andschneider/goqtt

Usage

subscription

Below is a simple example showing a subscription to a specified topic. Any Publish message received on the topic will be returned, allowing for further processing if desired. Note: there is no error handling in the example, which is not advised.

package main

import (
	"log"

	"github.com/andschneider/goqtt"
)

func main() {
	// Create Client
	topic := goqtt.Topic("goqtt")
	client := goqtt.NewClient("mqtt.eclipse.org", topic)

	// Attempt a connection to the specified MQTT broker
	client.Connect()
	defer client.Disconnect()

	// Attempt to subscribe to the topic
	client.Subscribe()

	// Read messages indefinitely
	for {
		log.Println("waiting for message")
		m, _ := client.ReadLoop()
		if m != nil {
			log.Printf("received message: '%s' from topic: '%s'", string(m.Message), m.Topic)
		}
	}
}

publish

Below is a simple example showing how to Publish a message to a specified topic. Note: there is no error handling in the example, which is not advised.

package main

import (
	"log"

	"github.com/andschneider/goqtt"
)

func main() {
	// Create Client
	topic := goqtt.Topic("goqtt")
	client := goqtt.NewClient("mqtt.eclipse.org", topic)

	// Attempt a connection to the specified MQTT broker
	client.Connect()
	defer client.Disconnect()

	// Attempt to publish a message
	err := client.Publish("hello world")
	if err != nil {
		log.Printf("could not send message: %v\n", err)
	}
}

There are more examples in the examples folder, with proper error handling and some logging:

connect and disconnect to a broker
publishing a message a topic
subscribing to a topic

Go

If you have Go installed you can run them with go run ./examples/<example>.

CLI

If you don't have Go installed, the examples have been compiled to binaries for Linux (x86 and Arm) and Darwin (macOS). These can found in the releases page. Download the correct .tar.gz for your platform and once uncompressed, the binaries will be in an examples folder. These are CLIs and can be ran directly from your terminal.

Docker

Each example has a Dockerfile if you don't have Go installed (and have Docker installed). To build an image, run docker build -t <image-name> . from an example directory.

For example, from the examples/connect directory run docker build -t conngoqtt .. Then to use the container, run docker run conngoqtt.

Limitations

Currently, goqtt does not implement the full MQTT 3.1.1 client specification.

The two main omissions from the spec are packets with QoS > 0 and username/password message payloads in CONNECT packets. Because of these, goqtt should be used with care in any environment that requires sensitive or important data.

QoS

For detailed information please refer to the spec, but with QoS set at 0 each packet is sent at most once. To quote the spec:

The message is delivered according to the capabilities of the underlying network. No response is sent by the receiver and no retry is performed by the sender. The message arrives at the receiver either once or not at all.

If a packet is encountered by goqtt with a higher QoS it will likely crash.

Authentication/Security

Without any support for username and password information to be sent to a broker there is no way for a client to authenticate. Please carefully consider if this is an acceptable security risk for your use case.

The MQTT spec does not require the use of TLS/SSL, however there are brokers that support TLS. goqtt does not support TLS connections. Please carefully consider if this is an acceptable security risk for your use case.

Other

A more minor omission is the lack of support for multiple topic subscriptions or wildcard subscriptions. A topic must be fully formed, e.g. goqtt/hello.

Logging

WIP

goqtt uses zerolog internally for creating structured logs with different levels (such as DEBUG, INFO, and ERROR).

However, all log statements are disabled by default. If you'd like to enable the logging, set the global log level to the desired level. This is done with the zerolog.SetGlobalLevel() function and a parameter such as zerolog.InfoLevel. See the examples and their documentation for more levels.

Inspiration

The eclipse paho golang MQTT library has been a large inspiration and resource for this project. Much thanks to them.

# Packages

# README