README
¶
awsiotcore
AWS IoT Core over MQTT in Go
This package follows https://aws.amazon.com/blogs/iot/use-aws-iot-core-mqtt-broker-with-standard-mqtt-libraries/.
Requirements
Amazon CA certs
You'll need Amazon's CA certs listed under "CA certificates for server authentication" https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html.
As of 2023-04-22 they are:
- RSA 2048 bit key: Amazon Root CA 1
- RSA 4096 bit key: Amazon Root CA 2. Reserved for future use.
- ECC 256 bit key: Amazon Root CA 3
- ECC 384 bit key: Amazon Root CA 4. Reserved for future use.
Download these and put them in a .pem file and use it when calling NewClient.
Endpoint URL
You'll need the endpoint of the MQTT broker to connect to. You can find that in the "Device data endpoint" section of the AWS IoT settings page, or you can fetch it using the AWS CLI:
aws iot describe-endpoint --endpoint-type iot:Data-ATS --query 'endpointAddress' --output text
For sending and receiving data from the message broker, use an iot:Data-ATS endpoint. See https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-devices.html#iot-connect-device-endpoints for the various endpoint types.
MQTT topics
By default telemetry will be sent to things/{device_id}/telemetry. Set TelemetryTopicOverride
on the Device to change that.
Documentation
¶
Overview ¶
package awsiotcore eases interaction with AWS IoT Core over MQTT. It handles TLS configuration and authentication.
Example ¶
package main
import (
"log"
"time"
"github.com/mtraver/awsiotcore"
)
func main() {
d := awsiotcore.Device{
Endpoint: "my-endpoint",
DeviceID: "my-device",
// roots.pem should contain the root CA certs described in the README.
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 {
Endpoint string
DeviceID string `json:"device_id"`
TelemetryTopicOverride string `json:"telemetry_topic"`
// CACerts must contain the path to a .pem file containing Amazon'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 AWS IoT device.
func (*Device) Broker ¶
func (d *Device) Broker() MQTTBroker
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 MQTT broker using TLS. By default it sets up a github.com/eclipse/paho.mqtt.golang ClientOptions with the minimal options required to establish a connection:
- Broker
- Client ID set to the device's ID
- TLS configuration that supplies root CA certs, the device's cert, and Server Name Indication (SNI) (required by AWS IoT)
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
}
}
No options are required to establish a connection but they allow for customizability.
For more information about connecting to AWS IoT MQTT brokers see https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-devices.html.
func (*Device) TelemetryTopic ¶
TelemetryTopic returns the MQTT topic to which the device should publish telemetry events.
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