EUROTECHMulti-service IoT GatewaysDownloads
Guides
Support

Device Configurations

Suggest Edits

📘

This page is a work in progress

This group of REST API allows performing operations on the services running on a connected remote device that expose configuration parameters.

For more informations about Configurations, please read Gateway Management - Configuration

Read multiple Configurations

The following API will query the list of applications and configuration values on a given device:

GET /{scopeId}/devices/{deviceId}/configurations

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.

Response

The response of this call will contain list of the configurations on the given device. As an example:

{
  "type": "deviceConfiguration",
  "configuration": [
    {
      "id": "org.eclipse.kura.wire.graph.WireGraphService",
      "definition": {
        "description": "WireGraphService metatype",
        "id": "org.eclipse.kura.wire.graph.WireGraphService",
        "name": "WireGraphService",
        "AD": [
          {
            "cardinality": 0,
            "description": "The default wire graph JSON",
            "id": "WireGraph",
            "name": "WireGraph",
            "required": true,
            "type": "String",
            "Option": []
          }
        ],
        "Icon": []
      },
      "properties": {
        "property": [
          {
            "name": "WireGraph",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "{\"components\":[{\"pid\":\"asset1\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-580,\"y\":-120},\"inputPortNames\":{},\"outputPortNames\":{}}},{\"pid\":\"asset2\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-1100,\"y\":-100},\"inputPortNames\":{},\"outputPortNames\":{}}}],\"wires\":[]}"
            ]
          },
          {
            "name": "kura.service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          },
          {
            "name": "service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          }
        ]
      }
    }
  ]
}

For every service, an object with the following properties will be returned:

id: the OSGi ID of the service
definition An object containing all the metadata for every property (name, description, cardinality, type, whether it is required or not) and for the service itself (name, id, description)
properties: an object containing an array of object representing the value for every property of the service

Update multiple Configurations

The following API allows one to modify the configuration values on the given remote device:

PUT /{scopeId}/devices/{deviceId}/configurations

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 configuration values to send to the given device. As an example:

{
  "configuration": [
    {
      "id": "org.eclipse.kura.wire.graph.WireGraphService",
      "properties": {
        "property": [
          {
            "name": "kura.service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          }
        ]
      }
    }
  ]
}

Response

The response of this call will contain list of the updated configuration details on the given device. As an example:

{
  "type": "deviceConfiguration",
  "configuration": [
    {
      "id": "org.eclipse.kura.wire.graph.WireGraphService",
      "definition": {
        "description": "WireGraphService metatype",
        "id": "org.eclipse.kura.wire.graph.WireGraphService",
        "name": "WireGraphService",
        "AD": [
          {
            "cardinality": 0,
            "description": "The default wire graph JSON",
            "id": "WireGraph",
            "name": "WireGraph",
            "required": true,
            "type": "String",
            "Option": []
          }
        ],
        "Icon": []
      },
      "properties": {
        "property": [
          {
            "name": "WireGraph",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "{\"components\":[{\"pid\":\"asset1\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-580,\"y\":-120},\"inputPortNames\":{},\"outputPortNames\":{}}},{\"pid\":\"asset2\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-1100,\"y\":-100},\"inputPortNames\":{},\"outputPortNames\":{}}}],\"wires\":[]}"
            ]
          },
          {
            "name": "kura.service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          },
          {
            "name": "service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          }
        ]
      }
    }
  ]
}

Read a single Configuration

Similar to the call to read multiple configurations, this one allows querying the configuration of a single service on a given device. More precisely, it returns the configuration of the OSGi component identified with specified PID (service's persistent identity):

GET /{scopeId}/devices/{deviceId}/configurations/{componentId}

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;
  • {componentId} is the id (PID, service's persistent identity) of the desired service; in the OSGi framework, the service's persistent identity is defined as the name attribute of the Component Descriptor XML file; at runtime, the same value is also available in the component.name and in the service.pid attributes of the Component Configuration.

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

Response

The response of this call will contain the configuration details of the chosen service on the given device. As an example:

{
  "type": "deviceConfiguration",
  "configuration": [
    {
      "id": "org.eclipse.kura.wire.graph.WireGraphService",
      "definition": {
        "description": "WireGraphService metatype",
        "id": "org.eclipse.kura.wire.graph.WireGraphService",
        "name": "WireGraphService",
        "AD": [
          {
            "cardinality": 0,
            "description": "The default wire graph JSON",
            "id": "WireGraph",
            "name": "WireGraph",
            "required": true,
            "type": "String",
            "Option": []
          }
        ],
        "Icon": []
      },
      "properties": {
        "property": [
          {
            "name": "WireGraph",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "{\"components\":[{\"pid\":\"asset1\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-580,\"y\":-120},\"inputPortNames\":{},\"outputPortNames\":{}}},{\"pid\":\"asset2\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-1100,\"y\":-100},\"inputPortNames\":{},\"outputPortNames\":{}}}],\"wires\":[]}"
            ]
          },
          {
            "name": "kura.service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          },
          {
            "name": "service.pid",
            "array": false,
            "encrypted": false,
            "type": "String",
            "value": [
              "org.eclipse.kura.wire.graph.WireGraphService"
            ]
          }
        ]
      }
    }
  ]
}

Update a single Configuration

Similar to the call to update multiple configurations, this one allows modifying the configuration of a single service on a given device. More precisely, it updates the configuration of the OSGi component identified with specified PID (service's persistent identity):

PUT /{scopeId}/devices/{deviceId}/configurations/{componentId}

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;
  • {componentId} is the id (PID, service's persistent identity) of the desired service; in the OSGi framework, the service's persistent identity is defined as the name attribute of the Component Descriptor XML file; at runtime, the same value is also available in the component.name and in the service.pid attributes of the Component Configuration.

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 configuration values to update for the given service on the given device. As an example:

{
  "id": "string",
  "properties": {
    "property": [
      {
        "name": "kura.service.pid",
        "array": false,
        "encrypted": false,
        "type": "String",
        "value": [
          "org.eclipse.kura.wire.graph.WireGraphService"
        ]
      }
    ]
  }
}

Response

The response of this call will contain list of the updated configuration details for the chosen service on the given device. As an example:

{
  "id": "org.eclipse.kura.wire.graph.WireGraphService",
  "definition": {
    "description": "WireGraphService metatype",
    "id": "org.eclipse.kura.wire.graph.WireGraphService",
    "name": "WireGraphService",
    "AD": [
      {
        "cardinality": 0,
        "description": "The default wire graph JSON",
        "id": "WireGraph",
        "name": "WireGraph",
        "required": true,
        "type": "String",
        "Option": []
      }
    ],
    "Icon": []
  },
  "properties": {
    "property": [
      {
        "name": "WireGraph",
        "array": false,
        "encrypted": false,
        "type": "String",
        "value": [
          "{\"components\":[{\"pid\":\"asset1\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-580,\"y\":-120},\"inputPortNames\":{},\"outputPortNames\":{}}},{\"pid\":\"asset2\",\"inputPortCount\":1,\"outputPortCount\":1,\"renderingProperties\":{\"position\":{\"x\":-1100,\"y\":-100},\"inputPortNames\":{},\"outputPortNames\":{}}}],\"wires\":[]}"
        ]
      },
      {
        "name": "kura.service.pid",
        "array": false,
        "encrypted": false,
        "type": "String",
        "value": [
          "org.eclipse.kura.wire.graph.WireGraphService"
        ]
      },
      {
        "name": "service.pid",
        "array": false,
        "encrypted": false,
        "type": "String",
        "value": [
          "org.eclipse.kura.wire.graph.WireGraphService"
        ]
      }
    ]
  }
}

Updated almost 5 years ago