The Device Descriptor

Every device tells Lhings about its properties and capabilities using a JSON descriptor file. In particular, the device descriptor describes the details of the actions, events and status components of the device. The device must send this file over the network during registration and then each time its capabilities change.

The following is an example of a descriptor file:

{
    "modelName": "288 GTO",
    "manufacturer": "Ferrari",
    "deviceType": "sport car",
    "serialNumber": "SN04732",
    "friendlyName": "My Ferrari 288 GTO",
    "uuid": "13dfc9c7-f8f2-4cd0-9472-89c1b179144f",
    "version": 1,
    "stateVariableList": [
        {
            "name": "Driver family name",
            "type": "string"
        },
        {
            "name": "Engine temperature",
            "type": "float"
        },
        {
            "name": "Trip started",
            "type": "timestamp"
        },
        {
            "name": "Distance travelled km",
            "type": "integer"
        },
        {
            "name": "Engine status OK?",
            "type": "boolean"
        }
    ],
    "actionList": [
        {
            "name": "speed up",
            "description": "accelerates the car up to a given maximum speed",
            "inputs": [
                {
                    "name": "maximum speed kph",
                    "type": "integer"
                }
            ]
        }
    ],
    "eventList": [
        {
            "name": "fuel_low",
            "components" : [ 
                {
                    "name" : "remaining_distance",
                    "type" : "float"
                },
                {
                    "name" : "gps_position",
                    "type" : "geolocation"
                },
                {
                    "name" : "distance_for_refuelling",
                    "type" : "integer"
                },
                {
                    "name" : "will_make_it",
                    "type" : "boolean"
                }
            ]
        }
    ]
}

It is divided in four main sections:

  • General information about the device: like its name, model, and serial number.
  • The status section is a list with the description of the values that compose the status of the device.
  • The action section describes the action the device is capable of performing.
  • The events section describes which events will be sent by the device.

General information section

This section is composed of several kinds of items:

  • Identity information, used to identify the device. These two items are optional:
    • uuid: the UUID of the device.
    • friendlyName: the name of the device. This is the same name as the one provided in the registration process.
  • Manufacturer information, used to provide details related to the manufacturing process of a device. These four items are optional:
    • manufacturer: the name of the manufacturer, e. g. "Ferrari".
    • deviceType: the product type, e. g. "sport car".
    • modelName: the model of the product, e. g. "288 GTO".
    • serialNumber: an unique identifier provided by the manufacturer of the device, e. g. "SN04732".
  • version: this field is used to convey which version of the descriptor file format is to be used. This field is optional and its default value 1.

Status section

The status section is represented in the descriptor by the JSON array named stateVariableList. Each object in this array represents one of the variables that make up the status of the device. Each device can have up to eight variables in its status. stateVariableList is mandatory, if the device has no status an empty array must be provided. Each variable is described by:

  • name: the name of the variable, e. g. "temperature". Mandatory.
  • type: the type of the variable, e. g. "float". Mandatory. Variables are typed parameters, what means they can be of any of these five types: integer, float, string, boolean, and timestamp.

Events section

The events section is represented in the descriptor by the JSON array named eventList. eventList is mandatory, if the device has no events an empty array must be provided. Each object in this array represents one of the events that can be sent by the device. Events are characterized by:

  • name: the name of the event, e. g. "fuel_low". Mandatory. Going on with the example of the sport car, this event would be used to warn the user when the car is running out of fuel.
  • components: the components of the payload of the event, if the event is going to use structured payload. Optional. Each component of the payload is defined by its name and type. See the payload documentation for more details.

Actions section

The actions section is represented in the descriptor by the JSON array named actionList. Each object in this array represents one of the actions that the device is able to perform. Actions have a name, a description, and a set of input parameters. actionListis mandatory, if the device has no actions an empty array must be provided. Each object in the array has the following properties:

  • name: the name of the action. Mandatory. For instance, going on with the example of the sport car, "speed up".
  • description: an optional description of the action. E. g., "this action accelerates the car up to a given maximum speed".
  • inputs: a list of typed parameters (up to 8) that will configure the way in which the action is performed. For example, the speed up action may have a parameter called "maximum speed kph" of type integer to define the maximum speed in kilometers per hour that the call will reach when speeding up. inputs is mandatory, if the action has no input parameters an empty array must be provided. Each input has the following properties:
    • name: the name of the parameter (e. g. "maximum speed kph").
    • type: the type of the parameter (e. g. "integer").
Back to top