README
¶
gomosquittogo
gomosquittogo is a Go (cgo) wrapper for the client library of the Mosquitto MQTT broker.
Building
This project was built and tested with Go 1.1 and libmosquitto 1.2. cgo support and an installed libmosquitto is required to build it:
go get github.com/rvolz/gomosquittogo
Testing
Use the usual go command to test:
go test github.com/rvolz/gomosquittogo ...
Most tests assume that a local (127.0.0.1) Mosquitto instance is available.
Using
The library consists of two packages. The main package gomosquittogo provides a high-level client for MQTT communication. The core package contains low-level wrappers for many libmosquitto API functions. If the functionality of the high-level client is not adequate for your needs, just use the core package to create your own.
The library is in an early development stage. It provides functionality to send and receive MQTT messages. Other functions like authentication, SSL ... will follow.
API Documentation: 
Examples
Create an anonymous client for a broker and send a string:
client := NewClient("127.0.0.1", nil)
defer client.Close()
client.Connect()
client.SendString("my topic","this is my message")
Create a named client and send some bytes:
client := NewClient("127.0.0.1", nil)
defer client.Close()
client.Name("test client")
client.Port(1884) // uses a non-standard port
client.Connect()
client.Send("my topic",([]byte)("this is my message"))
Receive messages:
// create a buffered output channel, size depends on the traffic expected
messages := make(<-chan *MosquittoMessage, 100)
client := NewClient("127.0.0.1", messages)
defer client.Close()
client.Name("test client")
client.Connect()
client.Subscribe("test")
go func(incoming <-chan *MosquittoMessage, control <-chan bool) {
for {
select {
case message := <-incoming:
// process incoming message here
case y := <-control:
// cheap solution to stop this goroutine
return
}
}
}(messages, control)
...
Documentation
¶
Overview ¶
Package gomosquittogo provides, as the name might imply, a Go language wrapper (cgo) for the client library of the Mosquitto MQTT broker. See http://mosquitto.org/man/mqtt-7.html for more information about the terminology used here.
The package contains a high-level client. The more flexible, low-level wrappers of the Mosquitto client library are contained in subpackage gomosquittogo/core.
Create an anonymous client for a broker and send a string:
client := NewClient("127.0.0.1", nil)
defer client.Close()b
client.Connect()
client.SendString("my topic","this is my message")
Create a named client and send some bytes:
client := NewClient("127.0.0.1", nil)
defer client.Close()
client.Name("test client")
client.Port(1884) // uses a non-standard port
client.Connect()
client.Send("my topic",([]byte)("this is my message"))
Receive messages:
// create a buffered output channel, size depends on the traffic expected
messages := make(<-chan *MosquittoMessage, 100)
client := NewClient("127.0.0.1", messages)
defer client.Close()
client.Name("test client")
client.Connect()
client.Subscribe("test")
go func(incoming <-chan *MosquittoMessage, control <-chan bool) {
for {
select {
case message := <-incoming:
// process incoming message here
case y := <-control:
// cheap solution to stop this goroutine
return
}
}
}(messages, control)
...
Index ¶
- type Client
- func (client *Client) Close()
- func (client *Client) Connect() bool
- func (client *Client) Password(password string)
- func (client *Client) Port(port int)
- func (client *Client) SendBytes(topic string, payload []byte, qos int, retain bool) error
- func (client *Client) SendString(topic string, payload string, qos int, retain bool) error
- func (client *Client) SetWillBytes(topic string, payload []byte, qos int, retain bool) error
- func (client *Client) SetWillString(topic string, payload string, qos int, retain bool) error
- func (client *Client) SslWithPsk(id string, psk string, tlsVersion string, ciphers string) error
- func (client *Client) SubscribeTopic(topic string, qos uint) error
- func (client *Client) UnsubscribeTopic(topic string) error
- func (client *Client) User(user string)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
MQTT client definition
func NewClient ¶
func NewClient(broker string, messages chan<- *core.MosquittoMessage) *Client
Create a new anonymous Mosquitto client. The parameter "broker" is the net address of the MQTT broker you want to connect to. Pass an output channel via "messages" to receive incoming messages. Use nil if you only want to send messages.
This method will generate an anonymous client with a generated client name. The "clean session" flag for these clients will be false. See NewNamedClient for an alternative.
Besides these the client uses the default settings, which can be changed by using the appropriate Setters before connecting.
func NewNamedClient ¶
func NewNamedClient(broker string, messages chan<- *core.MosquittoMessage, name string, cleanSession bool) *Client
Create a new named Mosquitto client. The parameter "broker" is the net address of the MQTT broker you want to connect to. Pass an output channel via "messages" to receive incoming messages. Use nil if you only want to send messages.
This method will use the "name" parameter as a client name for connections with the broker. The max. length for client names is 23. "cleanSession" sets the MQTT "clean session" flag. See NewClient for an alternative.
Besides these the client uses the default settings, which can be changed by using the appropriate Setters before connecting.
func (*Client) Close ¶
func (client *Client) Close()
Close must always be called to terminate connections and free resources. Will unsubscribe and clear wills if necessary.
func (*Client) Connect ¶
Start the connection to the MQTT broker. Connect wil create the Mosquitto client, start the internal message loop and connect to the broker. If the client as an output channel it will also start the message callback to receive incoming messages. Returns false if an error occured.
func (*Client) Port ¶
Use a different network port for communication with the broker. Default is the MQTT standard port 1883.
func (*Client) SendBytes ¶
Send a byte buffer to a broker/topic:
- topic: name of the broker topic
- payload: the bytes to send
- qos: QoS level required for sending the message
- retain: if true the broker will retain (keep) the message
func (*Client) SendString ¶
Convenience function to send a string to a broker/topic:
- topic: name of the broker topic
- payload: the string to send
- qos: QoS level required for sending the message
- retain: if true the broker will retain (keep) the message
func (*Client) SetWillBytes ¶
Set a byte buffer as a will for a topic. Will messages will be sent to the topic subscribers by the broker if the connection to the client dies unexpectedly. Will messages must be set before connecting. Parameters:
- topic: name of the broker topic
- payload: the bytes to send
- qos: QoS level required for sending the message
- retain: if true the broker will retain (keep) the message
func (*Client) SetWillString ¶
Convenience method to set a string as a will for a topic. Will messages will be sent to the topic subscribers by the broker if the connection to the client dies unexpectedly. Will messages must be set before connecting. Parameters:
- topic: name of the broker topic
- payload: the string to send
- qos: QoS level required for sending the message
- retain: if true the broker will retain (keep) the message
func (*Client) SslWithPsk ¶
Use SSL/TLS with a pre-shared key. Must be called before Connect().
id - PSK ID psk - the pre-shared key, hexadecimal characters only tlsVersion - the OpenSSL TLS version. Use one of the defined constants core.TlsV1, core.TlsV11, core.TlsV12 ciphers - optional, a list of OpenSSL ciphers, separated by double colons. If empty the default OpenSSL ciphers will be used.
func (*Client) SubscribeTopic ¶
Subscribe to a broker topic. Parameters are the topic name or pattern and the QoS level desired. See http://mosquitto.org/man/mqtt-7.html for more info about subscription patterns.
func (*Client) UnsubscribeTopic ¶
Unsubscribe from a subscribed topic.
Source Files
Directories