Device Profiles

A device profile describes a type of device within the Edge Xpert system. Each device managed by a Device Service has an association with a device profile, which defines that device type in terms of the operations that it supports. A device profile is described in YAML Ain’t Markup Language (YAML), which is a human-readable data serialization language.

The device profile contains some identification information - it has a name and a description, and a list of labels that can be used when searching device profiles. It also indicates the brand name of the device to which it applies, and the manufacturer of that device as illustrated in the following example:

name: "Test.Device.Modbus.Profile"
  manufacturer: "Cool Automation"
  model: "CoolMasterNet"
  labels:
      - "HVAC"
      - "Air conditioner"
  description: "CoolMasterNet is a unique communication bridge that seamlessly connects advanced VRF / Split Air Conditioning Systems and home automation / Building Management Systems (BMS) controllers"

This information in the device profile is followed by three sections, deviceResources, deviceCommands and coreCommands, described below.

deviceResources

The deviceResources section specifies an individual value within a device that can be read from or written to. It has a name, which allows it to be accessed, and a description for information, as shown in the following example:

deviceResources:
      -
        name: "SwitchA"
        description: "On/Off , 0-OFF 1-ON"
        attributes:
          { primaryTable: "COILS", startingAddress: "1" }
        properties:
          value:
            { type: "Bool", readWrite: "RW", minimum: "0", maximum: "1"}
          units:
            { type: "String", readWrite: "R", defaultValue: "On/Off"}

The attributes key in a deviceResources section are the device-service-specific parameters required to access the value. Each Device Service implementation has its own set of named values that are required; for example a BACnet Device Service might need an Object Identifier and a Property Identifier, whereas a Bluetooth Device Service could use a UUID to identify a value. The example above shows an attributes key definition for a Modbus Device Service.

The properties key in a deviceResources section describes the type of value that can be read/written by a Device Service. Each logical value is given two attributes: value and units. The following fields are available in a property value:

Property Value Fields
Field Mandatory (M) / Optional (O) Description Valid Values
type M The data type of the value Bool, Int8 - Int64, Uint8 - Uint64, Float32, Float64, String
readWrite O Indicates whether the value is readable or writable” R, W, RW
base O Value to be raised to the power of the raw reading before it is returned N/A
scale O Factor by which to multiply a reading before it is returned N/A
offset O Value to be added to a reading before it is returned N/A
mask O Binary mask applied to an integer reading N/A
shift O Number of bits to shift the integer reading to the right N/A
minimum O Minimum possible value of the returned reading N/A
maximum O Maximum possible value of the returned reading N/A

The processing defined by the base, scale, offset, shift and mask fields is applied in that order when reading values.

Values specified in the deviceResources section can be accessed through a Device Service’s REST API, as shown in the following example:

http://<device-service>:<port>/api/v1/device/<DeviceID>/<DeviceResourceName>
http://<device-service>:<port>/api/v1/device/name/<DeviceName>/<DeviceResourceName>

The <DeviceName> is the physical database identifier for the device, which is generated when the device is created in Edge Xpert.

The fields of the units attribute are as follows:

units Attribute Fields
Field Mandatory (M) / Optional (O) Description Valid Values
type M Indicates the type of unit String
readWrite M Indicates whether the unit can be read, written to, or both read and written to R
defaultValue M String describing the measurement units associated with a PropertyValue Depends on units; for example, deg/s, degreesFarenheit, G or %Relative Humidity

deviceCommands

The deviceCommands section defines read and write operations for multiple simultaneous values. Each deviceCommand contains a get and/or a set section, describing the HTTP get or put command respectively. This is illustrated in the following example:

deviceCommands:
      -
        name: "Switch"
        get:
        - { index: "1", operation: "set", object: "SwitchA", mappings: { "true":"ON","false":"OFF"}}
        - { index: "2", operation: "set", object: "SwitchB", mappings: { "true":"ON","false":"OFF"}}
        set:
        - { index: "1", operation: "set", object: "SwitchA", mappings: { "OFF":"false","ON":"true"}}
        - { index: "1", operation: "set", object: "SwitchB", mappings: { "OFF":"false","ON":"true"}}

Each line of a get attribute indicates a deviceResources to be read, and the lines in a set attribute indicate deviceResources to be written. The values in these lines are as follows:

deviceResources Line Values
Field Mandatory (M) / Optional (O) Description
index O Number used to define the order in which the resource is processed
operation M get or set
object O Name of the deviceResources to access. This must be specified if resource is not specified
resource O Name of another resource that can be used for aggregation. This must be specified if object is not specified
mappings O List of key-value pairs. The result is replaced with the specified value if the result of an operation matches one of the keys after transformation and conversion to a string value

deviceCommands can be accessed through a Device Service’s REST API in the same way as described for deviceResources.

coreCommands

The coreCommands section specifies the commands that are available through the core command service’s REST API for reading and writing to the device. A coreCommand must correspond by nam to a deviceResource or a deviceCommand.These are presented at the device endpoint, for example:

http://<core-command>:<port>/api/v1/device/command/<CommandID>

Commands support both get and/or put methods. For a get, the returned values are specified in the expectedValues field; for a put, the parameters to be given are specified in the parameterNames field. Both fields are arrays and specify the deviceResources to be read or written to.

In either case, the different HTTP status codes that the service generates are shown as response indicators. In the following get example, when the command for /api/v1/device/{deviceId}/SwitchA succeeds and returns HTTP Status code 200, the response also includes the SwitchA (as shown in expected values). If the command request did not succeed, the response returned is HTTP status code 503 and there is no other value in the body of the response.

coreCommands:
      -
       name: "Switch"
       get:
         path: "/api/v1/device/{deviceId}/Switch"
         responses:
         -
           code: "200"
           description: "Get the Switch"
           expectedValues: ["SwitchA","SwitchB"]
         -
           code: "503"
           description: "service unavailable"
           expectedValues: []
       put:
         path: "/api/v1/device/{deviceId}/Switch"
         parameterNames: ["SwitchA","SwitchB"]
         responses:
        -
          code: "204"
          description: "Set the Switch"
          expectedValues: []
        -
         code: "503"
         description: "service unavailable"
         expectedValues: []

Note

In the current implementation, only the command name and whether it is a get or put call are processed by the core-command service, the other information is indicative only.