iot: github.com/vaelen/iot Index | Examples | Files | Directories

package iot

import "github.com/vaelen/iot"

Package iot provides a simple implementation of a Google IoT Core device.

Note: Your application must import the iot/paho package to use the default Eclipse Paho MQTT client.

Index

Examples

Package Files

iot.go mock.go thing.go

Constants

const DefaultAuthTokenExpiration = time.Hour

DefaultAuthTokenExpiration is the default value for Thing.AuthTokenExpiration

Variables

var ErrCancelled = fmt.Errorf("operation was cancelled or timed out")

ErrCancelled is returned when a context is canceled or times out.

var ErrConfigurationError = fmt.Errorf("required configuration values are mising")

ErrConfigurationError is returned from Connect() if either the ID or Credentials have not been set.

var ErrNotConnected = fmt.Errorf("not connected")

ErrNotConnected is returned if a message is published but the client is not connected

var ErrPublishFailed = fmt.Errorf("could not publish message")

ErrPublishFailed is returned if the client was unable to send the message

type ClientConstructor Uses

type ClientConstructor func(thing Thing, options *ThingOptions) MQTTClient

ClientConstructor defines a function for creating an MQTT client instance

var NewClient ClientConstructor

NewClient is the ClientConstructor used to create MQTT client instances Override this value during testing to provide an MQTT client mock implementation

type ConfigHandler Uses

type ConfigHandler func(thing Thing, config []byte)

ConfigHandler handles configuration updates received from the server.

type CredentialType Uses

type CredentialType uint8

CredentialType defines the key type of the credential key pair.

const (
    // CredentialTypeRSA specfies that the credentials use RSA keys
    CredentialTypeRSA CredentialType = 0
    // CredentialTypeEC specifies that the credentials use Eliptic Curve keys
    CredentialTypeEC CredentialType = 1
)

type Credentials Uses

type Credentials struct {
    Type        CredentialType
    Certificate tls.Certificate
    PrivateKey  interface{}
}

Credentials wraps the public and private key for a device

func LoadECCredentials Uses

func LoadECCredentials(certificatePath string, privateKeyPath string) (*Credentials, error)

LoadECCredentials creates a Credentials struct from the given EC private key and certificate

func LoadRSACredentials Uses

func LoadRSACredentials(certificatePath string, privateKeyPath string) (*Credentials, error)

LoadRSACredentials creates a Credentials struct from the given RSA private key and certificate

type ID Uses

type ID struct {
    ProjectID string
    Location  string
    Registry  string
    DeviceID  string
}

ID represents the various components that uniquely identify this device

type Logger Uses

type Logger func(args ...interface{})

Logger is used to write log output. If no Logger is provided, no logging will be performed.

type MQTTClient Uses

type MQTTClient interface {
    // IsConnected should return true when the client is connected to the server
    IsConnected() bool

    // Connect should connect to the given MQTT server
    Connect(ctx context.Context, servers ...string) error

    // Disconnect should disconnect from the given MQTT server and clean up all client resources
    Disconnect(ctx context.Context) error

    // Publish should publish the given payload to the given topic with the given quality of service level
    Publish(ctx context.Context, topic string, qos uint8, payload interface{}) error

    // Subscribe should subscribe to the given topic with the given quality of service level and message handler
    Subscribe(ctx context.Context, topic string, qos uint8, callback ConfigHandler) error

    // Unsubscribe should unsubscribe from the given topic
    Unsubscribe(ctx context.Context, topic string) error

    // SetDebugLogger should set the logger to use for logging debug messages
    SetDebugLogger(logger Logger)

    // SetInfoLogger should set the logger to use for logging information or warning messages
    SetInfoLogger(logger Logger)

    // SetErrorLogger should set the logger to use for logging error or critical messages
    SetErrorLogger(logger Logger)

    // SetClientID should set the MQTT client id.
    SetClientID(clientID string)

    // SetCredentialsProvider should set the CredentialsProvider used by the MQTT client
    SetCredentialsProvider(crendentialsProvider MQTTCredentialsProvider)

    // SetOnConnectHandler provides a callback that should be called after the client connects to the server
    SetOnConnectHandler(handler MQTTOnConnectHandler)
}

The MQTTClient interface represents an underlying MQTT client implementation in an abstract way.

type MQTTCredentialsProvider Uses

type MQTTCredentialsProvider func() (username string, password string)

MQTTCredentialsProvider should return the current username and password for the MQTT client to use.

type MQTTOnConnectHandler Uses

type MQTTOnConnectHandler func(client MQTTClient)

MQTTOnConnectHandler will be called after the client connects. It should be used to resubscribe to topics and perform other connection related tasks.

type MockMQTTClient Uses

type MockMQTTClient struct {
    Connected           bool
    ConnectedTo         []string
    Messages            map[string][]interface{}
    Subscriptions       map[string]ConfigHandler
    DebugLogger         Logger
    InfoLogger          Logger
    ErrorLogger         Logger
    ClientID            string
    CredentialsProvider MQTTCredentialsProvider
    OnConnectHandler    MQTTOnConnectHandler
    // contains filtered or unexported fields
}

MockMQTTClient implements a mock MQTT client for use in testing To use this client, use code like the following: set iot.NewClient = iot.NewMockClient

Code:

var mockClient *MockMQTTClient
NewClient = func(t Thing, o *ThingOptions) MQTTClient {
    mockClient = NewMockClient(t, o)
    return mockClient
}

// Put your test code here

func NewMockClient Uses

func NewMockClient(t Thing, o *ThingOptions) *MockMQTTClient

NewMockClient returns an instance of MockMQTTClient The MockMQTTClient documentation explains how to use this method when writing tests.

func (*MockMQTTClient) Connect Uses

func (c *MockMQTTClient) Connect(ctx context.Context, servers ...string) error

Connect sets the Connected field to true and the ConnectedTo field to the list of servers

func (*MockMQTTClient) Disconnect Uses

func (c *MockMQTTClient) Disconnect(ctx context.Context) error

Disconnect sets the Connected field to false and clears the ConnectedTo field

func (*MockMQTTClient) IsConnected Uses

func (c *MockMQTTClient) IsConnected() bool

IsConnected returns the value of the Connected field

func (*MockMQTTClient) Publish Uses

func (c *MockMQTTClient) Publish(ctx context.Context, topic string, qos uint8, payload interface{}) error

Publish adds the given payload to the Messages map under the given topic

func (*MockMQTTClient) Receive Uses

func (c *MockMQTTClient) Receive(topic string, message []byte)

Receive imitates the client receiving a message on the given topic for testing purposes.

func (*MockMQTTClient) SetClientID Uses

func (c *MockMQTTClient) SetClientID(clientID string)

SetClientID sets ClientID

func (*MockMQTTClient) SetCredentialsProvider Uses

func (c *MockMQTTClient) SetCredentialsProvider(crendentialsProvider MQTTCredentialsProvider)

SetCredentialsProvider sets CredentialsProvider

func (*MockMQTTClient) SetDebugLogger Uses

func (c *MockMQTTClient) SetDebugLogger(logger Logger)

SetDebugLogger sets DebugLogger

func (*MockMQTTClient) SetErrorLogger Uses

func (c *MockMQTTClient) SetErrorLogger(logger Logger)

SetErrorLogger sets ErrorLogger

func (*MockMQTTClient) SetInfoLogger Uses

func (c *MockMQTTClient) SetInfoLogger(logger Logger)

SetInfoLogger sets InfoLogger

func (*MockMQTTClient) SetOnConnectHandler Uses

func (c *MockMQTTClient) SetOnConnectHandler(handler MQTTOnConnectHandler)

SetOnConnectHandler sets OnConnectHandler

func (*MockMQTTClient) Subscribe Uses

func (c *MockMQTTClient) Subscribe(ctx context.Context, topic string, qos uint8, callback ConfigHandler) error

Subscribe addes the given ConfigHandler to the Subscriptions map for the given topic

func (*MockMQTTClient) Unsubscribe Uses

func (c *MockMQTTClient) Unsubscribe(ctx context.Context, topic string) error

Unsubscribe removes the ConfigHandler from the Subscriptions map for the given topic

type Thing Uses

type Thing interface {
    // PublishState publishes the current device state
    PublishState(ctx context.Context, message []byte) error

    // PublishEvent publishes an event. An optional hierarchy of event names can be provided.
    PublishEvent(ctx context.Context, message []byte, event ...string) error

    // Connect to the given MQTT server(s)
    Connect(ctx context.Context, servers ...string) error

    // IsConnected returns true of the client is currently connected to MQTT server(s)
    IsConnected() bool

    // Disconnect from the MQTT server(s)
    Disconnect(ctx context.Context)
}

Thing represents an IoT device

Code:

ctx := context.Background()

// Your client must include the paho package
// to use the default Eclipse Paho MQTT client.
//
// include 	_ "github.com/vaelen/iot/paho"

id := &ID{
    DeviceID:  "deviceName",
    Registry:  "my-registry",
    Location:  "asia-east1",
    ProjectID: "my-project",
}

credentials, err := LoadRSACredentials("rsa_cert.pem", "rsa_private.pem")
if err != nil {
    panic("Couldn't load credentials")
}

tmpDir, err := ioutil.TempDir("", "queue-")
if err != nil {
    panic("Couldn't create temp directory")
}

options := DefaultOptions(id, credentials)
options.DebugLogger = log.Println
options.InfoLogger = log.Println
options.ErrorLogger = log.Println
options.QueueDirectory = tmpDir
options.ConfigHandler = func(thing Thing, config []byte) {
    // Do something here to process the updated config and create an updated state string
    state := []byte("ok")
    thing.PublishState(ctx, state)
}

thing := New(options)

err = thing.Connect(ctx, "ssl://mqtt.googleapis.com:443")
if err != nil {
    panic("Couldn't connect to server")
}
defer thing.Disconnect(ctx)

// This publishes to /events
thing.PublishEvent(ctx, []byte("Top level telemetry event"))
// This publishes to /events/a
thing.PublishEvent(ctx, []byte("Sub folder telemetry event"), "a")
// This publishes to /events/a/b
thing.PublishEvent(ctx, []byte("Sub folder telemetry event"), "a", "b")

func New Uses

func New(options *ThingOptions) Thing

New returns a new Thing using the given options.

type ThingOptions Uses

type ThingOptions struct {
    // ID identifies this device.
    // This value is required.
    ID  *ID
    // Credentials are used to authenticate with the server.
    // This value is required.
    Credentials *Credentials
    // DebugLogger is used to print debug level log output.
    // If no Logger is provided, no logging will occur.
    DebugLogger Logger
    // InfoLogger is used to print info level log output.
    // If no Logger is provided, no logging will occur.
    InfoLogger Logger
    // ErrorLogger is used to print error level log output.
    // If no Logger is provided, no logging will occur.
    ErrorLogger Logger
    // LogMQTT enables logging of the underlying MQTT client.
    // If enabled, the underlying MQTT client will log at the same level as the Thing itself (WARN, DEBUG, etc).
    LogMQTT bool
    // QueueDirectory should be a directory writable by the process.
    // If not provided, message queues will not be persisted between restarts.
    QueueDirectory string
    // ConfigHandler will be called when a new configuration document is received from the server.
    ConfigHandler ConfigHandler
    // ConfigQOS sets the QoS level for receiving config updates.
    // The default value will only perform best effort delivery.
    // The suggested value is 2.
    ConfigQOS uint8
    // StateQOS sets the QoS level for sending state updates.
    // The default value will only perform best effort delivery.
    // The suggested value is 1.
    // Google does not allow a value of 2 here.
    StateQOS uint8
    // EventQOS sets the QoS level for sending event updates.
    // The default value will only perform best effort delivery.
    // The suggested value is 1.
    // Google does not allow a value of 2 here.
    EventQOS uint8
    // AuthTokenExpiration determines how often a new auth token must be generated.
    // The minimum value is 10 minutes and the maximum value is 24 hours.
    // The default value is 1 hour.
    AuthTokenExpiration time.Duration
    // Clock represents the system clock.
    // This value can be overridden for testing purposes.
    // If not provided, this will default to the regular system clock.
    Clock clock.Clock
}

ThingOptions holds the options that are used to create a Thing

func DefaultOptions Uses

func DefaultOptions(id *ID, credentials *Credentials) *ThingOptions

DefaultOptions returns the default set of options.

Directories

PathSynopsis
examples
examples/read-sensors
pahoPackage paho provides an iot.MQTTClient implementation that uses the Eclipse Paho MQTT client.

Package iot imports 8 packages (graph) and is imported by 3 packages. Updated 2018-04-17. Refresh now. Tools for package owners.