DEV — Device and channel related messages

DEV-INF — Retrieve the current value of a channel or device path

A client sends this request to the server to retrieve the current value of a channel or the current values of all channels that are in a subtree of a device node in the device tree. The server will respond with an appropriately formatted JSON object that is structured in exactly the same way as the part of the matched device tree that the client is interested in. For instance, if the client requests the current value of a device node that has four channels with names ch1, ch2, ch3 and ch4, then the response object will also have four keys with names ch1, ch2, ch3 and ch4.

A server sends notifications of this type to the client whenever a channel in the part of the device tree that the client is subscribed to was updated (see DEV-SUB, DEV-UNSUB and DEV-LISTSUB for managing subscriptions).

Request fields

Name Required? Type Description

paths

yes

list of strings

The list of device tree paths that the client is interested in

Response and notification fields

Name Required? Type Description

values

no

object

Object mapping device tree paths to the corresponding values of the channels. A channel value may be replaced with null if the value is not known yet.

error

no

object

Object mapping failed device tree paths to reasons why the corresponding channel values could not have been retrieved.

All the device tree paths that were specified in the request MUST appear either in the status list or in the error map. When this message is sent as a notification, only the status field SHOULD be present.

Example request

{
  "type": "DEV-INF",
  "paths": ["/1/battery/voltage", "/1/led", "/1/cpu/core3"]
}

Example response or notification

{
  "type": "DEV-INF",
  "values": {
    "/1/battery/voltage": 13.4,
    "/1/led": {
      "on": true
    }
  },
  "error": {
    "/1/cpu/core3": "Path does not exist"
  }
}

DEV-LIST — List of devices and channels

A client sends this request to the server to retrieve the list (well, more precisely, the tree) of devices and channels associated to one or more objects.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of object IDs that the client is interested in

Response fields

Name Required? Type Description

devices

no

object

Mapping from object IDs to the corresponding device trees. The structure of this object is described by the DeviceTreeNode complex type.

error

no

object

Mapping from failed object IDs to reasons why the corresponding device tree could not have been retrieved.

All the object IDs that were specified in the request MUST appear either in the status list or in the error map.

Example request

{
  "type": "DEV-LIST",
  "ids": ["1", "spam"]
}

Example response

{
  "type": "DEV-LIST",
  "devices": {
    "1": {
      "type": "object",
      "children": {
        "battery": {
          "type": "device",
          "children": {
            "voltage": {
              "type": "channel",
              "subType": "number",
              "operations": ["read"],
              "unit": "V"
            },
            "manufacturerId": {
              "type": "channel",
              "subType": "string",
              "operations": ["read"]
            }
          }
        },
        "led": {
          "type": "device",
          "children": {
            "on": {
              "type": "channel",
              "subType": "boolean",
              "operations": ["read", "write"]
            }
          }
        },
        "reset": {
          "type": "channel",
          "subType": "boolean",
          "operations": ["write"]
        }
      }
    }
  },
  "error": {
    "spam": "No such UAV."
  }
}

DEV-LISTSUB — List device tree subscriptions

A client sends this request to the server to retrieve the list of device tree paths that the client is subscribed to.

The list of paths returned may optionally be filtered to parts of the device tree. A subscription path will be included in the result if it matches at least one of the specified paths. When no path is supplied in the request, the default path filter is ["/"], which will match all subscription paths.

A path MUST be included as many times in the request as the number of subscription requests sent by the client to this path.

Request fields

Name Required? Type Description

pathFilter

no

list of strings

The list of device or channel paths that the client is interested in. Only subscriptions that refer to these paths or subtrees of these paths will be returned in the response. The default value is ["/"].

Response fields

Name Required? Type Description

paths

yes

list of strings

The list of device or channel paths that the client is subscribed to and that match at least one of the path filters specified in the request. A path will be returned as many times as the number of subscriptions for the path, multiplied by the number of path filters that match the path[1].

Example request

{
  "type": "DEV-LISTSUB",
  "pathFilter": ["/1", "/2"]
}

Example response

{
  "type": "DEV-LISTSUB",
  "paths": ["/1/battery/voltage", "/1/led"]
}

DEV-SUB — Subscribe to a part of a device tree

A client sends this request to the server to subscribe to changes in the values of channels in a given part of the device tree of a given object.

The channel and/or device paths specified in the request are added to a client-specific list of subscriptions in the server. When a value of a channel is modified on one of the devices, the server will find all the clients that are subscribed to the channel with at least one subscription, and send an appropriate DEV-INF notification to them. Note that only one notification will be sent even if there are multiple subscriptions of the client that matches the channel that was modified. However, it is possible to subscribe to the same path multiple times.

The server MUST NOT accept nonexistent paths in the paths array by default. However, if the lazy request field is set to true, the server MUST accept nonexistent paths and subscribe the client to these paths when the paths come into existence later in the device tree. This allows a client to subscribe to channels from a UAV even when the server has not received telemetry status from the UAV yet.

Request fields

Name Required? Type Description

paths

yes

list of strings

The list of device or channel paths that the client is interested in

lazy

no

boolean

Whether the list is allowed to contain paths that do not exist yet.

Response fields

Name Required? Type Description

success

no

list of strings

The list of paths that the client was successfully subscribed to

error

no

object

Object mapping failed paths to explanations about why the subscription failed for these paths.

Example request

{
  "type": "DEV-SUB",
  "paths": ["/1/battery/voltage", "/1/led", "/1/cpu/core3"],
  "lazy": true
}

Example response

{
  "type": "DEV-SUB",
  "success": ["/1/battery/voltage", "/1/led"],
  "error": {
    "/1/cpu/core3": "Path does not exist"
  }
}

DEV-UNSUB — Unsubscribe from a part of a device tree

A client sends this request to the server to stop receiving notifications changes in the values of channels in a given part of the device tree of a given object.

The channel and/or device paths specified in the request are removed from a client-specific list of subscriptions in the server. Only exact matches are considered, i.e. it is not possible to subscribe to a larger part of the tree and then unsubscribe from a subset of it. Since it is possible to subscribe to the same path multiple times, and the paths a client subscribed to are stored in a list, the same number of unsubscription requests are required to cancel the subscription, unless "removeAll": true is specified in the request, in which case all exact matches will be removed.

Request fields

Name Required? Type Description

paths

yes

list of strings

The list of device or channel paths that the client wants to unsubscribe from

removeAll

no

boolean

Whether to remove all subscriptions that are exact matches to the paths specified in paths. The default is false, in which case the same number of unsubscription requests are required as the number of currently active subscriptions.

includeSubtrees

no

boolean

Whether to also remove all subscriptions that are in the subtrees of the paths specified in the request. The default is false.

Response fields

Name Required? Type Description

success

no

list of strings

The list of paths that the client was successfully unsubscribed from. This list may include paths that were not in the original paths list if includeSubtrees was true.

error

no

object

Object mapping failed paths to explanations about why the subscription failed for these paths.

Example request

{
  "type": "DEV-UNSUB",
  "paths": ["/1/battery", "/1/led", "/1/cpu/core3", "/2/battery"],
  "includeSubtrees": true
}

Example response

{
  "type": "DEV-UNSUB",
  "success": ["/1/battery/voltage", "/1/led"],
  "error": {
    "/1/cpu/core3": "Path does not exist",
    "/2/battery": "Not subscribed to this path"
  }
}
1. Typically, this is not a problem if you ensure that the path filters match disjoint parts of the tree.