gmq

README

GMQ - Pure Go MQTT Client


Overview

GMQ is a pure Go MQTT client. This library is compatible with MQTT Version 3.1.1. This library provides both a Go package and a command line application.

Installation

$ go get -u github.com/yosssi/gmq/...

MQTT Client Go Package

Example

package main

import (
	"fmt"
	"os"
	"os/signal"

	"github.com/yosssi/gmq/mqtt"
	"github.com/yosssi/gmq/mqtt/client"
)

func main() {
	// Set up channel on which to send signal notifications.
	sigc := make(chan os.Signal, 1)
	signal.Notify(sigc, os.Interrupt, os.Kill)

	// Create an MQTT Client.
	cli := client.New(&client.Options{
		// Define the processing of the error handler.
		ErrorHandler: func(err error) {
			fmt.Println(err)
		},
	})

	// Terminate the Client.
	defer cli.Terminate()

	// Connect to the MQTT Server.
	err := cli.Connect(&client.ConnectOptions{
		Network:  "tcp",
		Address:  "iot.eclipse.org:1883",
		ClientID: []byte("example-client"),
	})
	if err != nil {
		panic(err)
	}

	// Subscribe to topics.
	err = cli.Subscribe(&client.SubscribeOptions{
		SubReqs: []*client.SubReq{
			&client.SubReq{
				TopicFilter: []byte("foo"),
				QoS:         mqtt.QoS0,
				// Define the processing of the message handler.
				Handler: func(topicName, message []byte) {
					fmt.Println(string(topicName), string(message))
				},
			},
			&client.SubReq{
				TopicFilter: []byte("bar/#"),
				QoS:         mqtt.QoS1,
				Handler: func(topicName, message []byte) {
					fmt.Println(string(topicName), string(message))
				},
			},
		},
	})
	if err != nil {
		panic(err)
	}

	// Publish a message.
	err = cli.Publish(&client.PublishOptions{
		QoS:       mqtt.QoS0,
		TopicName: []byte("bar/baz"),
		Message:   []byte("testMessage"),
	})
	if err != nil {
		panic(err)
	}

	// Unsubscribe from topics.
	err = cli.Unsubscribe(&client.UnsubscribeOptions{
		TopicFilters: [][]byte{
			[]byte("foo"),
		},
	})
	if err != nil {
		panic(err)
	}

	// Wait for receiving a signal.
	<-sigc

	// Disconnect the Network Connection.
	if err := cli.Disconnect(); err != nil {
		panic(err)
	}
}

Details about APIs

CONNECT – Client requests a connection to a Server

// Create an MQTT Client.
cli := client.New(&client.Options{
	ErrorHandler: func(err error) {
		fmt.Println(err)
	},
})

// Terminate the Client.
defer cli.Terminate()

// Connect to the MQTT Server.
err := cli.Connect(&client.ConnectOptions{
	// Network is the network on which the Client connects to.
	Network:         "tcp",
	// Address is the address which the Client connects to.
	Address:         "iot.eclipse.org:1883",
	// TLSConfig is the configuration for the TLS connection.
	// If this property is not nil, the Client tries to use TLS
	// for the connection.
	TLSConfig:       nil,
	// CONNACKTimeout is timeout in seconds for the Client
	// to wait for receiving the CONNACK Packet after sending
	// the CONNECT Packet.
	CONNACKTimeout:  10,
	// PINGRESPTimeout is timeout in seconds for the Client
	// to wait for receiving the PINGRESP Packet after sending
	// the PINGREQ Packet.
	PINGRESPTimeout: 10,
	// ClientID is the Client Identifier of the CONNECT Packet.
	ClientID:        []byte("clientID"),
	// UserName is the User Name of the CONNECT Packet.
	UserName:        []byte("userName"),
	// // Password is the Password of the CONNECT Packet.
	Password:        []byte("password"),
	// CleanSession is the Clean Session of the CONNECT Packet.
	CleanSession:    true,
	// KeepAlive is the Keep Alive of the CONNECT Packet.
	KeepAlive:       30,
	// WillTopic is the Will Topic of the CONNECT Packet.
	WillTopic:       []byte("willTopic"),
	// WillMessage is the Will Message of the CONNECT Packet.
	WillMessage:     []byte("willMessage"),
	// WillQoS is the Will QoS of the CONNECT Packet.
	WillQoS:         mqtt.QoS0,
	// WillRetain is the Will Retain of the CONNECT Packet.
	WillRetain:      true,
})
if err != nil {
	panic(err)
}

CONNECT using TLS

// Create an MQTT Client.
cli := client.New(&client.Options{
	ErrorHandler: func(err error) {
		fmt.Println(err)
	},
})

// Terminate the Client.
defer cli.Terminate()

// Read the certificate file.
b, err := ioutil.ReadFile("/path/to/crtFile")
if err != nil {
	panic(err)
}

roots := x509.NewCertPool()
if ok := roots.AppendCertsFromPEM(b); !ok {
	panic("failed to parse root certificate")
}

tlsConfig = &tls.Config{
	RootCAs: roots,
}

// Connect to the MQTT Server using TLS.
err := cli.Connect(&client.ConnectOptions{
	// Network is the network on which the Client connects to.
	Network:         "tcp",
	// Address is the address which the Client connects to.
	Address:         "iot.eclipse.org:1883",
	// TLSConfig is the configuration for the TLS connection.
	// If this property is not nil, the Client tries to use TLS
	// for the connection.
	TLSConfig:       tlsConfig,
})
if err != nil {
	panic(err)
}

SUBSCRIBE - Subscribe to topics

// Create an MQTT Client.
cli := client.New(&client.Options{
	ErrorHandler: func(err error) {
		fmt.Println(err)
	},
})

// Terminate the Client.
defer cli.Terminate()

// Subscribe to topics.
err = cli.Subscribe(&client.SubscribeOptions{
	SubReqs: []*client.SubReq{
		&client.SubReq{
			// TopicFilter is the Topic Filter of the Subscription.
			TopicFilter: []byte("foo"),
			// QoS is the requsting QoS.
			QoS:         mqtt.QoS0,
			// Handler is the handler which handles the Application Message
			// sent from the Server.
			Handler: func(topicName, message []byte) {
				fmt.Println(string(topicName), string(message))
			},
		},
		&client.SubReq{
			TopicFilter: []byte("bar/#"),
			QoS:         mqtt.QoS1,
			Handler: func(topicName, message []byte) {
				fmt.Println(string(topicName), string(message))
			},
		},
	},
})
if err != nil {
	panic(err)
}

PUBLISH – Publish message

// Create an MQTT Client.
cli := client.New(&client.Options{
	ErrorHandler: func(err error) {
		fmt.Println(err)
	},
})

// Terminate the Client.
defer cli.Terminate()

// Publish a message.
err = cli.Publish(&client.PublishOptions{
	// QoS is the QoS of the PUBLISH Packet.
	QoS:       mqtt.QoS0,
	// Retain is the Retain of the PUBLISH Packet.
	Retain:    true,
	// TopicName is the Topic Name of the PUBLISH Packet.
	TopicName: []byte("bar/baz"),
	// Message is the Application Message of the PUBLISH Packet.
	Message:   []byte("testMessage"),
})
if err != nil {
	panic(err)
}

UNSUBSCRIBE – Unsubscribe from topics

// Create an MQTT Client.
cli := client.New(&client.Options{
	ErrorHandler: func(err error) {
		fmt.Println(err)
	},
})

// Terminate the Client.
defer cli.Terminate()

// Unsubscribe from topics.
err = cli.Unsubscribe(&client.UnsubscribeOptions{
	// TopicFilters represents a slice of the Topic Filters.
	TopicFilters: [][]byte{
		[]byte("foo"),
	},
})
if err != nil {
	panic(err)
}

DISCONNECT – Disconnect the Network Connection

// Create an MQTT Client.
cli := client.New(&client.Options{
	ErrorHandler: func(err error) {
		fmt.Println(err)
	},
})

// Terminate the Client.
defer cli.Terminate()

// Disconnect the network connection.
if err := cli.Disconnect(); err != nil {
	panic(err)
}

MQTT Client Command Line Application

After the installation, you can launch an MQTT client command line application by executing the gmq-cli command.

$ gmq-cli
gmq-cli>

You can see all GMQ Client commands by executing the help GMQ Client command.

gmq-cli> help
GMQ Client 0.0.1
Usage:
conn     establish a Network Connection and send a CONNECT Packet to the Server
disconn  send a DISCONNECT Packet to the Server and disconnect the Network Connection
help     print this help message
pub      send a PUBLISH Packet to the Server
quit     quit this process
sub      send a SUBSCRIBE Packet to the Server
unsub    send a UNSUBSCRIBE Packet to the Server

You can see all flags of a GMQ Client command by executing the command with the -help flag.

gmq-cli> conn -help
Usage:
  -P="": Password
  -c=true: Clean Session
  -crt="": the path of the certificate authority file to verify the server connection
  -ct=30: Timeout in seconds for the Client to wait for receiving the CONNACK Packet after sending the CONNECT Packet
  -h="localhost": host name of the Server which the Client connects to
  -i="": Client identifier for the Client
  -k=60: Keep Alive measured in seconds
  -n="tcp": network on which the Client connects to the Server
  -p=1883: port number of the Server which the Client connects to
  -pt=30: Timeout in seconds for the Client to wait for receiving the PINGRESP Packet after sending the PINGREQ Packet
  -u="": User Name
  -wm="": Will Message
  -wq=0: Will QoS
  -wr=false: Will Retain
  -wt="": Will Topic