gomulocity

README

Gomulocity REST SDK

Gomulocity is a Go library to interact with the REST API of the Cumulocity IoT platform of Software AG (c8y).

Table of Contents

• Gomulocity REST SDK
• Usage
  • Device Bootstrap
    • Configuration
    • Device Registration API
    • Device Credentials API
• Realtime Notification
• Feature coverage
• Contributing
• License

Usage

APIs are split into seperate imports you can select from:

import "github.com/tarent/gomulocity/alarm"
import "github.com/tarent/gomulocity/events"
import "github.com/tarent/gomulocity/measurement"
import "github.com/tarent/gomulocity/inventory"

The APIs need clients with credentials to work.

var c8yClient = &generic.Client{
	HTTPClient: http.DefaultClient,
	BaseURL:    "https://management.cumulocity.com",
	Username:   "user",
	Password:   "password",
}

Device Bootstrap

Configuration

The bootstrap API needs basic credentials to be able to register your client. Please contact your platform provider for the correct bootstrap credentials. Assure that the base url points to the correct platform instance.

var bootstrapClient = &generic.Client{
	HTTPClient: http.DefaultClient,
	BaseURL:    "https://management.cumulocity.com",
	Username:   "bootstrapuser",
	Password:   "password",
}

You can then register your device with a unique ID at your tenant:

	deviceId := "uniqueDeviceID"
	deviceCredentialsApi := device_bootstrap.NewDeviceCredentialsApi(bootstrapClient)

    deviceCredentials, _ := deviceCredentialsApi.Create(deviceId)

To register a device, you need to add the registration with the unique ID to your tenant via registration API or UI. More information about the registration cycle is available in the device integration part of the c8y docs. After obtaining credentials for your device, you need to create the device itself as a managed object. Use the inventory API to accomplish this.

Device Registration API

Start a new device registration with a unique device ID:

    deviceRegistration, err := gomulocity.DeviceRegistration.Create("123")

Get a device registration by device ID:

    deviceRegistration, err := gomulocity.DeviceRegistration.Get("123")

Get all device registrations page by page:

    deviceRegistrations, err := gomulocity.DeviceRegistration.GetAll(10)
    deviceRegistrations, err = gomulocity.DeviceRegistration.NextPage(deviceRegistrations)
    deviceRegistrations, err = gomulocity.DeviceRegistration.PreviousPage(deviceRegistrations)

Update device registration status:

    deviceRegistration, err := gomulocity.DeviceRegistration.Update("123", device_bootstrap.ACCEPTED)

Delete device registration by device ID:

    err := gomulocity.DeviceRegistration.Delete("123")

Device Credentials API

Create DeviceCredentials:

    deviceCredentials, err := gomulocity.DeviceCredentials.Create("123")

Realtime Notification

To use the Realtime-notification-API you need to import it with:

import "github.com/tarent/gomulocity/realtimenotification"

To build and start the API use StartRealtimeNotificationsAPI() which requires a context.Context to work with as well as credentials and an adress to connect to. credentials have to be provided in the following pattern: "tenantID/username:password"

api, err := StartRealtimeNotificationsAPI(ctx,"mycumulocitytenant/myusername:mypassword", "myadress.cumulocity.com")

After this we can Subscribe and Unsubscribe to channels by using:

api.DoSubscribe("operations/{deviceID})
api.DoUnsubscribe("measurement/{deviceID}")

To stop the API we can cancel the context, or use an OS.Interrupt Signal.

All answers from c8y are available in the api.ResponseFromPolling channel as raw json. You need to unmarshall it to the corresponding objects depending on your subscriptions.

Feature coverage

REST API:

• inventory/managedObjects
• measurement
• alarm
• event
• deviceControl/operations
• bootstrapping
• identity
• Realtime notifications via websockets
• audit
• user
• tenant

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue with the owners of this repository before making a change.

License

See LICENSE file.

Documentation

Index

• type Gomulocity
  • func NewGomulocity(baseURL, username, password string, ...) Gomulocity

Types

type Gomulocity

type Gomulocity struct {
	DeviceCredentials  device_bootstrap.DeviceCredentialsApi
	DeviceRegistration device_bootstrap.DeviceRegistrationApi
	DeviceControl      devicecontrol.DeviceControlApi
	AlarmApi           alarm.AlarmApi
	MeasurementApi     measurement.MeasurementApi
	Inventory          inventory.InventoryApi
	Identity           identity.IdentityAPI
	UserApi            user_api.UserApi
	Audit              audit.AuditApi
}

func NewGomulocity

func NewGomulocity(baseURL, username, password string, bootstrapUsername, bootstrapPassword string) Gomulocity