
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
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.