Peripheral: Get Node

The Peripheral: Get Node allows a Gateway Edge Agent (GEA) to retrieve one or more of the current edge device’s Peripheral Devices and add them to the current workflow payload.

Node Usage

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

• The GEA starts or restarts.
• A peripheral device is updated in the cloud and the Edge Compute device is connected to the MQTT broker.

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.

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

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:

• 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. As of Gateway Edge Agent v1.22.0, this field can also accept any valid template.
• Sort Direction: This is the field that tells the sort field which direction to sort in. By default, this field is Ascending. As of Gateway Edge Agent v1.22.0, the valid options are asc (default) for ascending or desc for descending, or any valid template.

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

Result

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

Starting with Gateway Edge Agent v1.33.0, you also have the option to return each device’s attributes and tags either as an object map, or as an array of objects. Prior GEA versions always return attributes as an array and tags as an object map.

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"
}