README.md

iothub

Azure IoT Hub SDK for Golang, provides both device-to-cloud (iotdevice) and cloud-to-device (iotservice) packages for end-to-end communication.

API is subject to change until v1.0.0. Bumping minor version may indicate breaking changes.

See TODO section to see what's missing in the library.

Installation

To install the library as a dependency:

go get -u gitlab.com/michaeljohn/iothub

To install CLI applications:

GO111MODULE=on go get -u gitlab.com/michaeljohn/iothub/cmd/{iothub-service,iothub-device}

Usage Example

Receive and print messages from IoT devices in a backend application:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"gitlab.com/michaeljohn/iothub/iotservice"
)

func main() {
	c, err := iotservice.NewFromConnectionString(
		os.Getenv("IOTHUB_SERVICE_CONNECTION_STRING"),
	)
	if err != nil {
		log.Fatal(err)
	}

	// subscribe to device-to-cloud events
	log.Fatal(c.SubscribeEvents(context.Background(), func(msg *iotservice.Event) error {
		fmt.Printf("%q sends %q", msg.ConnectionDeviceID, msg.Payload)
		return nil
	}))
}

Send a message from an IoT device:

package main

import (
	"context"
	"log"
	"os"

	"gitlab.com/michaeljohn/iothub/iotdevice"
	iotmqtt "gitlab.com/michaeljohn/iothub/iotdevice/transport/mqtt"
)

func main() {
	c, err := iotdevice.NewFromConnectionString(
		iotmqtt.New(), os.Getenv("IOTHUB_DEVICE_CONNECTION_STRING"),
	)
	if err != nil {
		log.Fatal(err)
	}

	// connect to the iothub
	if err = c.Connect(context.Background()); err != nil {
		log.Fatal(err)
	}

	// send a device-to-cloud message
	if err = c.SendEvent(context.Background(), []byte(`hello`)); err != nil {
		log.Fatal(err)
	}
}

cmd/iothub-service and cmd/iothub-device are reference implementations of almost all available features.

Provision Device

See _examples/provision.

CLI

The project provides two command line utilities: iothub-device and iothub-sevice. First is for using it on IoT devices and the second manages and interacts with them.

You can perform operations like publishing, subscribing to events and feedback, registering and invoking direct methods and so on straight from the command line.

iothub-service is a iothub-explorer replacement that can be distributed as a single binary opposed to a typical nodejs app.

See -help for more details.

Testing

TEST_IOTHUB_SERVICE_CONNECTION_STRING is required for end-to-end testing, which is a shared access policy connection string with all permissions.

TEST_EVENTHUB_CONNECTION_STRING is required for eventhub package testing.

TODO

iotservice

1. Complete IoT Edge support
2. Stabilize API
3. Fix TODOs

iotdevice

1. Device modules support.
2. HTTP transport (files uploading).
3. AMQP transport (batch sending, WS).

Contributing

All contributions are welcome.