Integrations

Integrations refer to the cloud side APIs for Drogue Cloud, which allow your application to access data coming from devices and schedule commands to devices.

Incoming data

Incoming data is streamed to applications in the form of Cloud Events. The message stream may contain telemetry events, as well as some infrastructure events.

The following events may contain additional attributes, not listed here. These are implementation details are should not be relied upon.

Device events

All regular messages/events a device sends, will end up as a "device event".

Attributes

Attribute Type Required Description

Standard attributes

specversion

String

X

Always 1.0.

type

String

X

Always io.drogue.event.v1.

id

String

X

A unique event ID.

subject

String

X

The channel information.

time

String (RFC3339)

X

The time the event arrived in the system.

datacontenttype

String

X

The content type of the message.

dataschema

String

The schema of the payload, encoded in the format defined in datacontenttype.

Extensions

instance

String

X

A unique identifier of the Drogue Cloud instance on this connection.

application

String

X

The name of the application the device belonged to.

applicationuid

String

X

The unique ID of the application the device belonged to.

device

String

X

The name of the device the event originated from.

deviceuid

String

X

The unique ID of the device the event originated from.

sender

String

X

The name of the device which delivered the event to Drogue Cloud.

senderuid

String

X

The unique ID of the device which delivered the event to Drogue Cloud.
UID fields

The uid variants of the attributes are using unique values, instead of names. Assume a device gets deleted and re-created with the same name. In this case, the name would be the same, but the UID in the event would be different.
Sender vs Device

The sender is a device which connected to Drogue Cloud. The "device" is the device the event originated from. If the originating device is also the connected device, both fields will have the same value. Drogue Cloud will also enforce that a device must be listed as gateway, in order to act on its behalf.

Payload

The payload is whatever the device sent as payload. Drogue Cloud, by default, doesn’t interpret the data in any way. It will only ensure that the data is well-formed JSON in the case the datacontenttype indicates a JSON mime type. The payload may also be empty.

Connection events

When a device connects through a connection oriented protocol (like MQTT), connection events will be issued by Drogue Cloud on behalf of the device.

Only devices which directly connect to Drogue Cloud will issue such events. Devices connected via another device, acting as gateway, do not.

Attributes

Attribute Type Required Description

Standard attributes

specversion

String

X

Always 1.0.

type

String

X

Always io.drogue.connection.v1.

id

String

X

A unique event ID.

subject

String

X

Always connection.

time

String (RFC3339)

X

The time the event was issues.

datacontenttype

String

X

Always application/json.

Extensions

instance

String

X

A unique identifier of the Drogue Cloud instance on this connection.

application

String

X

The name of the application the device belonged to.

applicationuid

String

X

The unique ID of the application the device belonged to.

device

String

X

The name of the device the event originated from.

deviceuid

String

X

The unique ID of the device the event originated from.

sender

String

X

The name of the device which delivered the event to Drogue Cloud.

senderuid

String

X

The unique ID of the device which delivered the event to Drogue Cloud.

Payload

The payload is defined by the following schema:

Schema of connection event payload
type: object
properties:
  connected:
    type: boolean
    description: Whether the device is connected or not
required:
  - connected
Example of connection event payload
{"connected": true}

Device registry events

Whenever a change is made to a device in the registry, a "device change event" is sent out.

Attributes

Attribute Type Required Description

Standard attributes

specversion

String

X

Always 1.0.

type

String

X

Always io.drogue.registry.v1.

id

String

X

A unique event ID.

subject

String

X

Always devices.

time

String (RFC3339)

X

The time the event was generated.

Extensions

instance

String

X

A unique identifier of the Drogue Cloud instance on this connection.

application

String

X

The name of the application the device belonged to.

applicationuid

String

X

The unique ID of the application the device belonged to.

device

String

X

The name of the device the event originated from.

deviceuid

String

X

The unique ID of the device the event originated from.

sender

String

X

The name of the device which delivered the event to Drogue Cloud.

senderuid

String

X

The unique ID of the device which delivered the event to Drogue Cloud.

Payload

The event doesn’t carry any payload. It is just an information that the device changed.

Commands

To be written …