Device Service REST API
Status
proposed
Context
This ADR details the REST API to be provided by Device Service implementations in EdgeX version 2.x. As such, it supercedes the equivalent sections of the earlier "Device Service Functional Requirements" document. These requirements should be implemented as far as possible within the Device Service SDKs, but they also apply to any Device Service implementation.
Decision
Common endpoints
The DS should provide the REST endpoints that are expected of all EdgeX microservices, specifically:
- config
- metrics
- ping
- version
Callback
| Endpoint | Methods |
|---|---|
| callback/device | PUT and POST |
| callback/device/id/{id} | DELETE |
| callback/profile | PUT and POST |
| callback/profile/id/{id} | DELETE |
| callback/watcher | PUT and POST |
| callback/watcher/id/{id} | DELETE |
| parameter | meaning |
|---|---|
| {id} | a database-generated object id |
These endpoints are used by the Core Metadata service to inform the device service of metadata updates. Endpoints are defined for each of the objects of interest to a device service, ie Devices, Device Profiles and Provision Watchers. On receipt of calls to these endpoints the device service should update its internal state accordingly.
Object deletion
When an object is deleted, the Metadata service makes a DELETE request to the relevant callback/{type}/id/{id} endpoint.
Object creation and updates
When an object is created or updated, the Metadata service makes a POST or PUT request respectively to the relevant callback/{type} endpoint. The payload of the request is the new or updated object.
Device
| Endpoint | Methods |
|---|---|
| device/name/{name}/{command} | GET and PUT |
| device/{id}/{command} | GET and PUT |
| parameter | meaning |
|---|---|
| {id} | a database-generated device id or |
| {name} | the name of the device |
| {command} | the command name |
The command specified must match a deviceCommand or deviceResource name in the device's profile
body (for PUT): An application/json SettingRequest, which is a set of key/value pairs where the keys are valid deviceResource names, and the values provide the command argument for that resource. Example: {"AHU-TargetTemperature": "28.5", "AHU-TargetBand": "4.0"}
| Return code | Meaning |
|---|---|
| 200 | the command was successful |
| 404 | the specified device does not exist, or the command/resource is unknown |
| 405 | attempted write to a read-only resource |
| 423 | the specified device is locked (admin state) or disabled (operating state) |
| 500 | the device driver is unable to process the request |
response body: A successful GET operation will return a JSON-encoded Event, which contains one or more Readings. Example: {"device":"Gyro","origin":1592405201763915855,"readings":[{"name":"Xrotation","value":"124","origin":1592405201763915855,"valueType":"int32"},{"name":"Yrotation","value":"-54","origin":1592405201763915855,"valueType":"int32"},{"name":"Zrotation","value":"122","origin":1592405201763915855,"valueType":"int32"}]}
This endpoint is used for obtaining readings from a device, and for writing settings to a device.
Data formats
The values obtained when readings are taken, or used to make settings, are expressed as strings.
| Type | EdgeX types | Representation |
|---|---|---|
| Boolean | bool |
"true" or "false" |
| Integer | uint8-uint64, int8-int64 |
Numeric string, eg "-132" |
| Float | float32, float64 |
base64 encoded little-endian binary or decimal with exponent, eg "1.234e-5" |
| String | string |
string |
| Binary | bytes |
octet array |
| Array | boolarray, uint8array-uint64array, int8array-int64array, float32array, float64array |
JSON Array, eg "["1", "34", "-5"]" |
Notes: - The presence of a Binary reading will cause the entire Event to be encoded using CBOR rather than JSON - The representation of a float is determined by the "floatEncoding" attribute of the device resource. "base64" is the default, "eNotation" will cause the float to be written as a decimal with exponent.
Readings and Events
A Reading represents a value obtained from a deviceResource. It contains the following fields
| Field name | Description |
|---|---|
| name | The name of the deviceResource |
| valueType | The type of the data |
| origin | A timestamp indicating when the reading was taken |
| value | The reading value |
| mediaType | (Only for Binary readings) The MIME type of the data |
| floatEncoding | (Only for floats and arrays of floats) The float representation in use |
An Event represents the result of a GET command. If the command names a deviceResource, the Event will contain a single Reading. If the command names a deviceCommand, the Event will contain as many Readings as there are deviceResources listed in the deviceCommand.
The fields of an Event are as follows:
| Field name | Description |
|---|---|
| device | The name of the Device from which the Readings are taken |
| origin | The time at which the Event was created |
| readings | An array of Readings |
Query Parameters
Calls to the device endpoints may include a Query String in the URL. This may be used to pass parameters relating to the request to the device service. Individual device services may define their own parameters to control specific behaviors. Parameters beginning with the prefix ds- are reserved to the Device SDKs and the following parameters are defined for GET requests:
| Parameter | Valid Values | Default | Meaning |
|---|---|---|---|
| ds-postevent | "yes" or "no" | "no" | If set to yes, a successful GET will result in an event being posted to core-data |
| ds-returnevent | "yes" or "no" | "yes" | If set to no, there will be no Event returned in the http response |
Device States
A Device in EdgeX has two states associated with it: the Administrative state and the Operational state. The Administrative state may be set to LOCKED (normally UNLOCKED) to block access to the device for administrative reasons. The Operational state may be set to DISABLED (normally ENABLED) to indicate that the device is not currently working. In either case access to the device via this endpoint will be denied and HTTP 423 ("Locked") will be returned.
Data Transformations
A number of simple data transformations may be defined in the deviceResource. The table below shows these transformations in the order in which they are applied to outgoing data, ie Readings. The transformations are inverted and applied in reverse order for incoming data.
| Transform | Applicable reading types | Effect |
|---|---|---|
| mask | Integers | The reading is bitwise masked with the specified value. |
| shift | Integers | The reading is bit-shifted by the specified value. Positive values indicate right-shift, negative for left. |
| base | Integers and Floats | The reading is replaced by the specified value raised to the power of the reading. |
| scale | Integers and Floats | The reading is multiplied by the specified value. |
| offset | Integers and Floats | The reading is increased by the specified value. |
The operation of the mask transform on incoming data (a setting) is that the value to be set on the resource is the existing value bitwise-anded with the complement of the mask, bitwise-ored with the value specified in the request.
ie, new-value = (current-value & !mask) | request-value
The combination of mask and shift can therefore be used to access data contained in a subdivision of an octet.
Assertions and Mappings
Assertions are another attribute in a device resource's PropertyValue which specify a string value which the result is compared against. If the comparison fails, then the result is set to a string of the form "Assertion failed for device resource: \DISABLED. A 500 status code is also returned.
Mappings may be defined in a deviceCommand. These allow Readings of string type to be remapped. Mappings are applied after assertions are checked, and are the final transformation before Readings are created. Mappings are also applied, but in reverse, to settings (PUT request data).
lastConnected timestamp
Each Device has as part of its metadata a timestamp named lastConnected, this
indicates the most recent occasion when the device was successfully interacted
with. The device service should update this timestamp every time a GET or PUT
operation succeeds, unless it has been configured not to do so (eg for
performance reasons).
Discovery
| Endpoint | Methods |
|---|---|
| discovery | POST |
A call to this endpoint triggers the device discovery process, if enabled. See Discovery Design for details.
Consequences
Changes from v1.x API
- The callback endpoint is split according to the type of object being updated
- Callbacks for new and updated objects take the object in the request body
- The device/all form is removed
GETrequests take parameters controlling what is to be done with resulting Events, and the default behavior does not send the Event to core-data
References
OpenAPI definition of v2 API : https://github.com/edgexfoundry/device-sdk-go/blob/master/api/oas3.0/v2/device-sdk.yaml Device Service Functional Requirements (Geneva) : https://wiki.edgexfoundry.org/download/attachments/329488/edgex-device-service-requirements-v11.pdf?version=1&modificationDate=1591621033000&api=v2