Device Assets

📘

This page is a work in progress

This group of REST API allows to perform Assets Management operations on assets connected to a given device.

Get the Assets Definitions of a single Device

The following API will retrieve the details of all the assets configured on a given device:

GET /{scopeId}/devices/{deviceId}/assets

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device.

It is also possible to add the optional timeout query parameter, an integer value which represents the timeout for the request in milliseconds:

GET /{scopeId}/devices/{deviceId}/assets?timeout={timeoutValue}

Example Call

As an example, if a client application wants to retrieve the details of a device, where QNvLTfKO1hy is the scopeId of the account used for the authentication and TSlSMdJO1sx is the deviceId of the device registered within that account:

GET QNvLTfKO1hy/devices/TSlSMdJO1sx/assets

Response

The response of this call represents the list of assets definitions linked to the given device. As an example:

{
  "type": "deviceAssets",
  "deviceAsset": [
    {
      "name": "asset1",
      "channels": [
        {
          "valueType": "integer",
          "name": "Channel-1",
          "mode": "READ"
        },
        {
          "valueType": "integer",
          "name": "Channel-2",
          "mode": "WRITE"
        },
        {
          "valueType": "integer",
          "name": "Channel-3",
          "mode": "READ_WRITE"
        }
      ]
    },
    {
      "name": "asset2",
      "channels": [
        {
          "valueType": "integer",
          "name": "Channel-1",
          "mode": "READ"
        },
        {
          "valueType": "integer",
          "name": "Channel-2",
          "mode": "WRITE"
        },
        {
          "valueType": "integer",
          "name": "Channel-3",
          "mode": "READ_WRITE"
        }
      ]
    }
  ]
}

Additionally, by using a POST request, the results can be by Asset name:

POST /{scopeId}/devices/{deviceId}/assets

Body

This call has a required body parameter that defines an object containing the list of assets to use as a filter. As an example:

{
  "deviceAsset": [
    {
      "name": "asset2"
    },
    {
      "name": "asset3"
    }
  ]
}

Multiple objects can be passed as a filter:

Response

The response of this call represents the list of assets definition of the given device according to the filter. For instance:

{
  "type": "deviceAssets",
  "deviceAsset": [
    {
      "name": "asset2",
      "channels": [
        {
          "valueType": "integer",
          "name": "Channel-1",
          "mode": "READ"
        },
        {
          "valueType": "integer",
          "name": "Channel-2",
          "mode": "WRITE"
        },
        {
          "valueType": "integer",
          "name": "Channel-3",
          "mode": "READ_WRITE"
        }
      ]
    },
    {
      "name": "asset3",
      "channels": [
        {
          "valueType": "integer",
          "name": "Channel-1",
          "mode": "READ"
        }
      ]
    }
  ]
}

Read the values for the Assets of a single Device

The following API allows one to retrieve the values for the assets connected to the given device:

POST /{scopeId}/devices/{deviceId}/assets/_read

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device.

It is also possible to add the optional timeout query parameter, an integer value which represents the timeout for the request in milliseconds.

Body

This call have a required body parameter that defines an object containing the list of assets to use as a filter. As an example:

{
  "deviceAsset": [
    {
      "name": "asset2"
    }
  ]
}

Response

The response of this call represents the list of assets with values of the given device. For instance:

{
  "type": "deviceAssets",
  "deviceAsset": [
    {
      "name": "asset2",
      "channels": [
        {
          "valueType": "integer",
          "value": 5,
          "name": "Channel-1",
          "timestamp": "2019-09-12T14:50:24.446Z"
        },
        {
          "valueType": "integer",
          "value": 8,
          "name": "Channel-3",
          "timestamp": "2019-09-12T14:50:24.446Z"
        }
      ]
    }
  ]
}

Write the values for the Assets of a single Device

The following API allows one to write the values for the assets connected to a given device:

POST /{scopeId}/devices/{deviceId}/assets/_write

The required path parameters to be used with this call are:

• {scopeId} is the scopeId of the tenant (account) to which the desired device belongs and can be retrieved from the response of the authentication call; the "_" character can be used for indicating the scopeId of the user currently authenticated with the token;
• {deviceId} is the id of the desired device.

It is also possible to add the optional timeout query parameter, an integer value which represents the timeout for the request in milliseconds.

Body

This call have a required body parameter that defines an object containing the list of assets to be updated and the values to write. As an example:

{
  "type": "deviceAssets",
  "deviceAsset": {
    "name": "asset2",
    "channels": [
      {
        "valueType": "integer",
        "value": 12,
        "name": "Channel-2"
      },
      {
        "valueType": "integer",
        "value": 80,
        "name": "Channel-3"
      }
    ]
  }
}

Response

The response of this call represents the updated asset list for the desired device with updated values. For instance:

{
  "type": "deviceAssets",
  "deviceAsset": {
    "name": "asset2",
    "channels": [
      {
        "valueType": "integer",
        "value": 12,
        "name": "Channel-2"
      },
      {
        "valueType": "integer",
        "value": 80,
        "name": "Channel-3"
      }
    ]
  }
}