iothub

README

Azure IoT Hub over MQTT in Go

Package iothub eases interaction with Azure IoT Hub over MQTT. It handles TLS configuration and authentication. It also makes it easy to construct the fully-qualified MQTT topics that IoT Hub uses for telemetry and cloud-to-device communication.

Currently only X.509 self-signed authentication is supported. See https://learn.microsoft.com/en-us/azure/iot-edge/how-to-authenticate-downstream-device?view=iotedge-1.4#x509-self-signed-authentication.

Requirements

Azure CA certs

You'll need Azure's trusted root certs. You can find them here: https://learn.microsoft.com/en-us/azure/security/fundamentals/azure-ca-details. Most importantly, as of Feb 2023, it should contain the DigiCert Global Root G2 cert.

Save them in a single .pem file and use its path when constructing a Device.

Documentation

Overview

Package iothub eases interaction with Azure IoT Hub over MQTT. It handles TLS configuration and authentication. It also makes it easy to construct the fully-qualified MQTT topics that IoT Hub uses for telemetry and cloud-to-device communication.

Example

package main

import (
	"log"
	"time"

	"github.com/mtraver/iothub"
)

func main() {
	d := iothub.Device{
		HubName:  "my-hub",
		DeviceID: "my-device",
		// roots.pem must contain Azure's trusted root certs. See the README for more info.
		CACerts:     "roots.pem",
		CertPath:    "my-device.x509",
		PrivKeyPath: "my-device.pem",
	}

	client, err := d.NewClient()
	if err != nil {
		log.Fatalf("Failed to make MQTT client: %v", err)
	}

	if token := client.Connect(); !token.Wait() || token.Error() != nil {
		log.Fatalf("Failed to connect to MQTT broker: %v", token.Error())
	}

	if token := client.Publish(d.TelemetryTopic(), 1, false, []byte("{\"temp\": 18.0}")); !token.Wait() || token.Error() != nil {
		log.Printf("Failed to publish: %v", token.Error())
	}

	client.Disconnect(250)
	time.Sleep(500 * time.Millisecond)
}

Index

• func DeviceIDFromCert(certPath string) (string, error)
• type Device
  • func (d *Device) Broker() MQTTBroker
  • func (d *Device) CommandTopic() string
  • func (d *Device) ID() string
  • func (d *Device) NewClient(options ...func(*Device, *mqtt.ClientOptions) error) (mqtt.Client, error)
  • func (d *Device) TelemetryTopic() string
  • func (d *Device) Username() string
• type MQTTBroker
  • func (b *MQTTBroker) String() string
  • func (b *MQTTBroker) URL() string

Examples

• Package

Functions

func DeviceIDFromCert

func DeviceIDFromCert(certPath string) (string, error)

DeviceIDFromCert gets the Common Name from an X.509 cert, which for the purposes of this package is considered to be the device ID.

Types

type Device

type Device struct {
	HubName  string `json:"hub_name"`
	DeviceID string `json:"device_id"`
	// CACerts must contain the path to a .pem file containing Azure's trusted root certs. See the README for more info.
	CACerts     string `json:"ca_certs_path"`
	CertPath    string `json:"cert_path"`
	PrivKeyPath string `json:"priv_key_path"`
}

Device represents an IoT Hub device.

func (*Device) Broker

func (d *Device) Broker() MQTTBroker

func (*Device) CommandTopic

func (d *Device) CommandTopic() string

CommandTopic returns the MQTT topic to which the device can subscribe to get commands. For more information see https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support#receiving-cloud-to-device-messages.

func (*Device) ID

func (d *Device) ID() string

func (*Device) NewClient

func (d *Device) NewClient(options ...func(*Device, *mqtt.ClientOptions) error) (mqtt.Client, error)

NewClient creates a github.com/eclipse/paho.mqtt.golang Client that may be used to connect to the device's Hub's MQTT broker using TLS, which Azure IoT Hub requires. By default it sets up a github.com/eclipse/paho.mqtt.golang ClientOptions with the minimal options required to establish a connection:

• Client ID
• Username
• TLS configuration that supplies root CA certs and the device's cert
• Broker

By passing in options you may customize the ClientOptions. Options are functions with this signature:

func(*Device, *mqtt.ClientOptions) error

They modify the ClientOptions. The option functions are applied to the ClientOptions in the order given before the Client is created. For example, if you wish to set the connect timeout, you might write this:

func ConnectTimeout(t time.Duration) func(*Device, *mqtt.ClientOptions) error {
	return func(d *Device, opts *mqtt.ClientOptions) error {
		opts.SetConnectTimeout(t)
		return nil
	}
}

Using option functions allows for sensible defaults — no options are required to establish a connection — without loss of customizability.

For more information about connecting to Azure IoT Hub's MQTT brokers see https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support#tlsssl-configuration.

func (*Device) TelemetryTopic

func (d *Device) TelemetryTopic() string

TelemetryTopic returns the MQTT topic to which the device should publish telemetry events. For more information see https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support#sending-device-to-cloud-messages.

func (*Device) Username

func (d *Device) Username() string

Username returns a username formatted as required by IoT Hub.

type MQTTBroker

type MQTTBroker struct {
	Host string
	Port int
}

MQTTBroker represents an MQTT server.

func (*MQTTBroker) String

func (b *MQTTBroker) String() string

String returns a string representation of the MQTTBroker.

func (*MQTTBroker) URL

func (b *MQTTBroker) URL() string

URL returns the URL of the MQTT server.