Edge 1.16.0

Peripheral: Get Node

The Peripheral: Get Node allows an Edge Workflow to retrieve one or more of the current edge device’s Peripheral Devices and add them to the current workflow payload.

Get Peripheral Node

Node Usage

The Edge Agent is aware of up to 1000 peripheral devices, prioritizing peripherals that are directly connected to the device. Peripheral devices are synced from the cloud under the following cases:

  • The Edge Agent starts or restarts
  • A peripheral device is updated in the cloud and the Edge Agent is connected

Limited Fields

To save storage space on edge devices, peripherals sent to the gateway are sent with a limited set of fields. The following fields will be synced:

{
  "name": <name>,
  "id": <deviceId>,
  "deviceClass": <"peripheral" or "floating">,
  "tags": { key: [values] },
  "attributes": {
    "name": <name>,
    "dataType": <"string", "number", "gps", or "boolean">,
    "attributeTags": { key: [values] }
  }
}

Node Properties

The configuration for the Peripheral: Get Node requires a query method and the configuration for the selected method.

Query Method

To find one or more peripheral devices, a query method must be defined.

Get Peripheral Node Query

The Peripheral: Get Node has four query options:

  • Device ID: You can input a specific device’s ID to retrieve it or use a value on the payload. The ID can be hardcoded in the workflow editor or derived from a property on the current payload.
  • Device Name: You can input a specific device’s name to retrieve it or use a value on the payload. The name can be hardcoded in the workflow editor or derived from a property on the current payload.
  • Match All Tags Query: You can set specific tag key/value pairs to retrieve one or more devices. Any device(s) returned will match all tags in the query. The key/value can be hardcoded or derived from a property on the current payload.

    You may also query by key only or value only. If a key is set without a value, any device that has that key set regardless of the value will be returned. If a value is set without a key, any device that has that value set regardless of the key will be returned.

  • Match Any Tags Query: You can set specific tag key/value pairs to retrieve one or more devices. Any device(s) returned will match any tags in the query. The key/value can be hardcoded or derived from a property on the current payload.

    You may also query by key only or value only. If a key is set without a value, any device that has that key set regardless of the value will be returned. If a value is set without a key, any device that has that value set regardless of the key will be returned.

Configuration

Get Peripheral Node Query

Depending on the query method selected, you are able to input the specific Device ID, Device Name, or the tag key/value pairs to find a device or group of devices.

Results Configuration

For each query method aside from Device ID an extra set of properties will appear beside the tags input:

Get Peripheral Node Sorting

  • Return multiple devices?: If you want to return multiple devices from this query, check this box. This also alters the return type of the result. If checked and nothing is found, an empty array will be returned instead of null. If checked and one or more devices have been found they will be returned as an array.
  • Sort Field: This is the field on the group to sort the results by. By default, this field is name. The following are the valid sort fields: name, id, creationDate or lastUpdated.
  • Sort Direction: This is the field that tells the sort field which direction to sort in. By default, this field is Ascending.

NOTE: Sorting options affect the result — even when returning a single device.

Result Path

It is required you specify where on the payload path you want the device or group of devices to be stored.

Get Peripheral Node Result

Node Example

For example, if we get a single device by the tag sigfox_id where its value is AA00FF, and the result path set to working.deviceResult, the result might look like the following:

{
  "working": {
    "deviceResult": {
      "id": "56c794a06895b00100cbe84c",
      "name": "Sigfox Device",
      "deviceClass": "peripheral",
      "tags": {
        "sigfox_id": ["AA00FF"]
      },
      "attributes": [
        { "name": "temp", "dataType": "number" },
        { "name": "humidity", "dataType": "number" }
      ],
    },
  },
  ...
}

Node Errors

For the Device ID query, the result will either be the device object or null if no device is found. Here is an example of an empty result for this case:

{
  "working": {
    "deviceResult": null
  },
  "applicationName": "Water Pump",
  "flowName": "Tester",
  "flowId": "5cf6cb469136cc0038c37aa3",
  "relayType": "user",
  "relayId": "574f2ca804554101007ff876",
  "flowVersion": "develop",
  "triggerType": "virtualButton",
  "triggerId": "5cf6cb419136cc0008c37aa3-wnW2xlu7r9q2IxaBZjZ5c",
  "applicationId": "5bbb973892e051000926d195",
  "data": {},
  "time": "2019-06-04T19:58:08.340Z"
}

For the Device Name, Match All Tags Query and Match Any Tags Query queries, if the return multiple device? checkbox is unchecked the results will either be the device object or null if no device is found. Otherwise if the return multiple device? checkbox is checked then the results will either be an array of objects or an empty array. Here is an example of an empty result for this case:

{
  "working": {
    "deviceResult":[]
  },
  "applicationName": "Water Pump",
  "flowName": "Tester",
  "flowId": "5cf6cb469136cc0038c37aa3",
  "relayType": "user",
  "relayId": "574f2ca804554101007ff876",
  "flowVersion": "develop",
  "triggerType": "virtualButton",
  "triggerId": "5cf6cb419136cc0008c37aa3-wnW2xlu7r9q2IxaBZjZ5c",
  "applicationId": "5bbb973892e051000926d195",
  "data": {},
  "time": "2019-06-04T19:58:08.340Z"
}