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)
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeviceIDFromCert ¶
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 ¶
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) 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 ¶
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.
type MQTTBroker ¶
MQTTBroker represents an MQTT server.
func (*MQTTBroker) String ¶
func (b *MQTTBroker) String() string
String returns a string representation of the MQTTBroker.
Source Files