Skip to content

Device Service API

The Device Services provide an API for reading and writing device resources. This API uses the XRT Bus to process requests and replies. The API provides the following operations:

  • Get. This reads from resources
  • Put. This writes to resources

Requests are published to the topic defined by the RequestTopic parameter.

Replies are published by the Device Service to the topic defined by the ReplyTopic parameter.

Operation Request Format

The request is published to a request topic in the form of a map. Each request contains key/value pairs, as described in the following table:

Key Description
client The client identity

Identifies the sender of the request

String
request_id Identifies the request within the scope of a specific client

Conventionally an unsigned integer
op Identifies the operation to be performed

Valid values are as follows:
  • get
  • put
The operations support an additional key/value pair, as described in Get Operation and Put Operation
device Identifies the device targeted by the request

Must match a device provisioned by the Device Service

String

Get Operation

Get operations support the key/value pair described in the following table:

Key Description
resource Identifies the resource to read

Must match a resource defined in the device profile associated with the targeted device

String

Put Operation

Put operations support the key/value pair described in the following table:

Key Description
values A map of device resource name to value

Request Reply Format

The reply to a request consists of a map with the key/value pairs described in the following table:

Key Description
client Client identity

The client value supplied by the request
request_id The request ID supplied by the request
result A map containing the data that was returned from the request

For further information on the format of the result, see Result Map Format

Result Map Format

The data returned in the result key value is as described in the following table:

Data Description
value The value of the reading
origin The timestamp associated with the reading

Only present if timestamp generation is enabled
type The type of the value

String

For further information on supported types, see Supported Types

Example Get Request

A Get request is shown in the following example:

{
  "resource": "BinaryInput1",
  "request_id": 3,
  "device": "damocles-0002b503c1ec",
  "client": "client1",
  "op": "get"
}

Example Get Reply

The response to the example Get request above would be as shown in the following example:

{
  "client": "client1",
  "request_id": 3,
  "result": {
    "readings": {
      "BinaryInput1": {
        "origin": 1611161894180636200,
        "value": true,
        "type": "bool"
      }
    },
    "success": true
  }
}

Example Put Request

A Put request is shown in the following example:

{
  "resource": "BinaryOutputs",
  "device": "damocles-0002b503c1ec",
  "values": {
    "BinaryOutput2": false,
    "BinaryOutput1": false
  },
  "request_id": 4,
  "client": "client1",
  "op": "put"
}

Example Put Reply

The response to the example Put request above would be as shown in the following example:

{
  "client": "client1",
  "request_id": 4,
  "result": {
    "success": true
  }
}

Supported Types

The following table describes the types supported by the Device Service Pub/Sub API:

Type Description
int8 Signed 8-bit integer
uint8 Unsigned 8-bit integer
int16 Signed 16-bit integer
uint16 Unsigned 16-bit integer
int32 Signed 32-bit integer
uint32 Unsigned 32-bit integer
int64 Unsigned 64-bit integer
uint64 Unsigned 64-bit integer
float32 32-bit floating point
float64 64-bit floating point
bool Bool
string String
int8array Signed 8-bit integer array
uint8array Unsigned 8-bit integer array
int16array Signed 16-bit integer array
uint16array Unsigned 16-bit integer array
int32array Signed 32-bit integer array
uint32array Unsigned 32-bit integer array
int64array Signed 64-bit integer array
uint64array Unsigned 64-bit integer array
float32array 32-bit floating point array
float64array 64-bit floating point array
boolarray Bool array
Back to top