MQTTπ€
About
β¦ an MQTT client library for the Go programming language. Great care was taken to provide correctness in all scenario, including the error states. Message transfers in both directions have zero-copy. Errors are propagated through the API. There is no internal logging by design.
The development was kindly sponsored by Northvolt, as a gift to the open-source community.
This is free and unencumbered software released into the public domain.
Introduction
The client supports confirmed message delivery with full progress disclosure. Message transfers without an confirmation can be as simple as the following.
err := client.Publish(ctx.Done(), []byte("20.8β"), "bedroom")
if err != nil {
log.Print("thermostat update lost: ", err)
return
}
A read routine sees inbound messages one by one.
for {
message, topic, err := client.ReadSlices()
switch {
case err == nil:
r, _ := utf8.DecodeLastRune(message)
switch r {
case 'βͺ', 'β', 'β':
log.Printf("%sΒ at %q", message, topic)
}
case errors.Is(err, mqtt.ErrClosed):
return // terminated
default:
log.Print("broker unavailable: ", err)
time.Sleep(time.Second) // backoff
}
}
The examples from the package documentation provide a good start with detailed configuration options.
Command-Line Client
Run go install github.com/pascaldekloe/mqtt/cmd/mqttc
to build the binary.
NAME
mqttc β MQTT broker access
SYNOPSIS
mqttc [options] address
DESCRIPTION
The command connects to the address argument, with an option to
publish a message and/or subscribe with topic filters.
When the address does not specify a port, then the defaults are
applied, which is 1883 for plain connections and 8883 for TLS.
OPTIONS
-client identifier
Use a specific client identifier. (default "generated")
-net name
Select the network by name. Valid alternatives include tcp4,
tcp6 and unix. (default "tcp")
-pass file
The file content is used as a password.
-prefix string
Print a string before each inbound message.
-publish topic
Send a message to a topic. The payload is read from standard
input.
-quiet
Suppress all output to standard error. Error reporting is
deduced to the exit code only.
-quote
Print inbound topics and messages as quoted strings.
-server name
Use a specific server name with TLS
-subscribe filter
Listen with a topic filter. Inbound messages are printed to
standard output until interrupted by a signal(3). Multiple
-subscribe options may be applied together.
-suffix string
Print a string after each inbound message. (default "\n")
-timeout duration
Network operation expiry. (default 4s)
-tls
Secure the connection with TLS.
-topic
Print the respective topic of each inbound message.
-user name
The user name may be used by the broker for authentication
and/or authorization purposes.
-verbose
Produces more output to standard error for debug purposes.
EXIT STATUS
(0) no error
(1) MQTT operational error
(2) illegal command invocation
(5) connection refused: unacceptable protocol version
(6) connection refused: identifier rejected
(7) connection refused: server unavailable
(8) connection refused: bad username or password
(9) connection refused: not authorized
(130) close on SIGINT
(143) disconnect on SIGTERM
EXAMPLES
Send a message:
echo "hello" | mqttc -publish chat/misc localhost
Print messages:
mqttc -subscribe "news/#" -prefix "π₯ " :1883
Health check:
mqttc -tls q1.example.com:8883 || echo "exit $?"
BUGS
Report bugs at <https://github.com/pascaldekloe/mqtt/issues>.
SEE ALSO
mosquitto_pub(1)
Standard Compliance
The implementation follows version 3.1.1 of the OASIS specification in a strict manner. Support for the originating IBM specification may be added at some point in time.
There are no plans to support protocol version 5. Version 3 is lean and well suited for IOT. The additions in version 5 may be more of a fit for backend computing.
See the Broker wiki for implementation specifics.