n

Rigado Edge Connect API Reference

Rigado Edge Connect is an optimized BLE connectivity app that runs on a Rigado Gateway. Edge Connect scans for BLE data and makes it available to BLE Pipelines. A Pipeline is made up of a list of Filters that process event data, filtering, manipulating, and eventually publishing to the cloud or other data destination.

Bluetooth Connections can also be orchestrated using ConnectionSequences, which are comprised of a set of ConnectionActions. Sequences are triggered by a connect filter in a Pipeline.

Information about how to use this configuration can be found in the main Edge Connect Documentation

A number of keys and values in these configuration objects support templating. For more info about how to use templates, see Edge Connect Templates.

Configuration Elements

AcknowledgeConfig

If an acknowledgement fails validation, the write action stops and returns an error.

ackMessageCount: integer (int64) 1

Setting to wait for acknowledgement every N messages

characteristic: string

UUID of characteristic

indication: boolean true

Acknowledgement will be an indication instead of a notification?

keepNotificationsEnabled: boolean false

Keep notifications on characteristic enabled after receiving an acknowledgement?

match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
outputMode: string replace

Acknowledgement data output mode "replace", "array" or "append"

service: string

UUID of the service

timeout: string

Acknowledgement timeout

Example
{
  "ackMessageCount": "integer (int64)",
  "characteristic": "2a26",
  "indication": "boolean",
  "keepNotificationsEnabled": "boolean",
  "match": {
    "rssi": ">-40",
    "serviceData.fd95": ""
  },
  "matchAny": "boolean",
  "matchers": [
    "is-nearby",
    "is-my-device-type"
  ],
  "outputMode": "string",
  "service": "375aee4c-6dea-5105-9074-14d5ba44f766",
  "timeout": "string"
}

Cloud

connectors: object

Defines the cloud Connectors to connect to.

A map of unique identifier to a definition of a CloudConnector.

Connectors defined here will be connected to, and can be targeted with publish filters. Depending on CloudConnector implementation and configuration, they may also subscribe and generate cloud events.

Example
{
  "connectors": "object"
}

CloudConnector

Describes the configuration for a cloud connector. CloudConnectors can publish events to the cloud by being targeted with a publish or publishTopic filter in a pipeline.

Some CloudConnector types also support subscribing for cloud commands/events and subscribing on topics.

config: object

Configuration information for the particular type of CloudConnector used. Described in the documentation for each CloudConnector type.

type: string

The unique type of the CloudConnector, must match the type of one of the available CloudConnectors

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "type": "mqtt",
          "config": {
            "host": "iothub.myserver.net",
            "port": "8883",
            "scheme": "tcps"
          }
        }
      }
    }
  }
}

CloudConnectorDevices

Device configuration for connectors that support identification of individual devices.

Note: not all cloud connectors support all of these options. Support for each option is documented in the specific cloud connector.

attachAll: boolean false

If set to true, devices simply included in the referenced device group will be attached/subscribed. If set to false (default), devices will not be attached/subscribed until they are determined to be present.

connectMessage: CloudMessage
detachMissing: boolean false

If set to true, devices will be detached/unsubscribed if they are removed from the device group, or if they go missing from presence tracking. If set to false (default) devices are only detached/unsubscribed when they are removed from the device group.

deviceIdTemplate: string

A text template for converting the lowercase mac field to any deviceId that is desired by the cloud configuration. This template is used to generate a Device ID that is then used to attach to the cloud and subscribe to topics. If no deviceIdTemplate is supplied, defaults to using the lowercase MAC address of the device.

NOTE: this should not be used if you are using the deviceIdTemplate on the device group that is connected to this. The Device ID should be generated using that template instead.

group: string

Device Group that contains the devices this cloud connector is concerned with. The connector will attach and subscribe to topics for devices contained in this group.

subscribeTopics: string[]

Per device topics to subscribe to. Incoming messages on these topics will arrive in pipelines as cloud type events.

Supports text templating. deviceId is available in the text template.

string
Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "type": "mqtt",
          "config": {
            "devices": {
              "attachAll": true,
              "detachMissing": true,
              "deviceIdTemplate": "{{ .mac | ToUpper }}",
              "group": "my-sensors",
              "subscribeTopics": [
                "sensors/sensor_{{ .deviceId }}/commands"
              ]
            },
            "host": "iothub.myserver.net",
            "port": "8883",
            "scheme": "tcps"
          }
        }
      }
    }
  }
}

CloudMessage

A statically configured message to send to the cloud. Currently only used by Cloud Connectors that support the connectMessage parameter.

message: object

The message body

topic: string

Topic the message is on

Example
{
  "message": "object",
  "topic": "string"
}

Config

Top level configuration for the Edge Connect Service. Must be wrapped in the service key.

actions: object

Defines the ConnectionActions that can be used in ConnectionSequences.

A map of unique identifier to a ConnectionAction definition.

ConnectionActions defined here can be reused in multiple ConnectionSequences.

api: RestAPI
cloud: Cloud
connections: object

Defines the ConnectionSequences that will handle processing of BLE connections.

A map of unique identifier to a ConnectionSequence definition.

ConnectionSequences are triggered by a connect filter.

filters: object

Defines the Filters available for use in Pipelines.

A map of unique identifier to a definition of a Filter.

Filters defined here can be reused in multiple Pipelines.

groups: object

Defines the DeviceGroups that can be referenced by Pipelines.

A map of unique identifier to DeviceGroup definition.

health: Health
log: Log
matchers: object

Defines the Matchers that can be referenced by Pipelines or the matcher filter.

A map of matcher ID's to key/value pairs

metadata: Metadata
metrics: Metrics
pipelines: object

Defines the Pipelines of Filters that events will flow through.

A map of unique identifier to a Pipeline definition.

Example
{
  "service": {
    "filters": {
      "eddyf": {
        "type": "eddystone"
      },
      "ruuvif": {
        "type": "ruuvi"
      }
    },
    "pipelines": {
      "eddypipe": {
        "filters": [
          "eddyf",
          "my-mqtt"
        ],
        "eventType": "advertisement",
        "groups": [
          "east-wing-eddystones"
        ]
      },
      "ruuvipipe": {
        "filters": [
          "ruuvif",
          "my-mqtt"
        ],
        "eventType": "advertisement"
      }
    },
    "metrics": {
      "reporting": {
        "intervalMinutes": 10
      }
    },
    "health": {
      "reporting": {
        "intervalMinutes": 10
      }
    },
    "api": {
      "port": 62307,
      "devmode": true
    },
    "log": {
      "level": "info",
      "printTimestamps": false,
      "printJSONEvents": false,
      "eventHistory": 0,
      "includeUnmatchedHistory": false
    },
    "groups": {
      "east-wing-eddystones": {
        "type": "static",
        "config": {
          "absenceMinutes": 5,
          "exclude": [
            "abcdef7",
            "abcdef8"
          ],
          "include": [
            "abcdef5",
            "abcdef6"
          ]
        }
      }
    },
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "type": "mqtt",
          "config": {
            "base": "",
            "host": "iothub.myserver.net",
            "port": 8883,
            "scheme": "tcps"
          }
        }
      }
    }
  }
}

ConnectionAction

Action to take once BLE Connection is established. Chained together in a ConnectionSequence.

config: object

Configuration information for the particular type of Action used. Described in the documentation for each Action type.

type: string

The unique type of the Action, must match the type of one of the available ConnectionActions.

Example
{
  "service": {
    "actions": {
      "read-custom-char": {
        "type": "read",
        "config": {
          "characteristic": "2a26",
          "outputKey": "battery",
          "service": "375aee4c-6dea-5105-9074-14d5ba44f766"
        }
      }
    }
  }
}

ConnectionSequence

Sequence of ConnectionActions to run upon BLE Connection. Triggered by the connect filter.

actions: string[]

List of ConnectionAction identifiers.

References the actions defined on Config.

string
allowEarlyExit: boolean false

Allow for the connection to exit, but proceed with the rest of the pipeline. Default behavior (false) will end the pipeline if the connection ends prematurely. This does not allow errors to proceed, only actions that return nil.

attempts: integer (int64) 5

When set to a value greater than 0, the set of actions for the connection will be attempted the number of specified times. Note that this only applies to when a connection is successfully made to a device. If a device is not present and the connection request times out, no further attempts to connect will occur until an advertisement from the device is seen again. This minimum number of attempts is 1. The maximum is 10.

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "connections": {
      "readBatteryConn": {
        "actions": [
          "read-custom-battery",
          "update-custom-metadata"
        ]
      }
    }
  }
}

ConverterInput

Used by the injectKeys parameter of the typeConvert Filter. Defines the source key, bytes (offset/count), and destination type of a []byte conversion

length: integer (int64) 0

Number of bytes to select starting from offset. Use 0 (default) to mean all bytes after offset.

offset: integer (int64) 0

Offset to select bytes from

source: string

Key containing the bytes to convert (supports dot-notation)

type: string

Type to convert the bytes to, see above for supported types

Example
{
  "length": 9,
  "offset": 3,
  "source": "rawData",
  "type": "base64"
}

DeviceGroup

Describes the configuration for a group of devices. Groups can be used to restrict a Pipeline to only see events from certain devices.

They can also be used to define a group of devices that are expected to be present, or should be excluded.

Only types static or persistent are currently supported.

config: object

Configuration information for the particular type of DeviceGroup used. Described in the documentation for each DeviceGroup type.

type: string

The unique type of the DeviceGroup, must match the type of one of the available DeviceGroups

Example
{
  "service": {
    "groups": {
      "my-eddystones": {
        "type": "static",
        "config": {
          "absenceMinutes": 19,
          "exclude": [
            "eddymac4",
            "eddymac5",
            "eddymac6"
          ],
          "include": [
            "eddymac1",
            "eddymac2",
            "eddymac3"
          ]
        }
      }
    }
  }
}

DeviceGroupBattery

enabled: boolean false
failPercent: number (float) 1

The percentage at which to trigger a Status of Fail

warnPercent: number (float) 20

The percentage at which to trigger a Status of Warn. Anything greater than this will be Status OK

Example
{
  "enabled": "boolean",
  "failPercent": "number (float)",
  "warnPercent": "number (float)"
}

EncodedField

For use with the decodeLTV and decodeType filter/action. EncodedField describes one field in an EncodedType. A string template can be specified to manipulate the decoded data, this will be output as a string.

If field length is set to 0, a template must be specified in order to compute a field. This can be useful for including items based on the index (id) of the containing EncodedType instance , or for incorporating other computed items like timestamps. In the case of a computed field, type is ignored and the output will be string unless convertTemplate is set a valid type for string conversion.

See the typeConvert filter for details on available types for byte array or string conversions.

key: string

The key to put the decoded data in

length: integer (int64)

The number of bytes that represents this fields value.

template: string

A template string to process the value with after decoding. The full event will be available as well as the decoded value as .item.value and the offset of the containing EncodedType as .item.id.

Note: this means the final value will be a string, unless this is a computed field. To create a computed field, the length must be set to 0, and the type must be a valid type converted from a string. See above in the EncodedField description for more details about computed fields.

type: string

The type of the data. E.g. string,int,etc Supports any of the types supported by the typeConvert filter when converting from []byte

Example
{
  "key": "string",
  "length": "integer (int64)",
  "template": "string",
  "type": "string"
}

EncodedLTV

For use with the decodeLTV filter/action. EncodedLTV describes a type containing multiple fields that can be encoded in a byte stream, identified by a type.

appendToArray: string

If set to a non-empty string, instances of this type will be appended to an array with this key, rather than merged with the main output event.

fields: EncodedField

The fields of the type, in order that they are encoded in the data.

EncodedField
id: integer (uint8)

The unique ID of the type this describes.

Example
{
  "appendToArray": "string",
  "fields": [
    {
      "key": "string",
      "length": "integer (int64)",
      "template": "string",
      "type": "string"
    }
  ],
  "id": "integer (uint8)"
}

EncodedType

For use with the decodeType filter/action. EncodedType describes a type containing multiple fields that can be encoded in a byte stream.

fields: EncodedField

The fields of the type, in order that they are encoded in the data.

EncodedField
Example
{
  "fields": [
    {
      "key": "string",
      "length": "integer (int64)",
      "template": "string",
      "type": "string"
    }
  ]
}

Filter

Filter describes the configuration for one Filter Node in a Pipeline

config: object

Configuration information for the particular type of Filter used. Described in the documentation for each Filter type.

type: string

The unique type of the Filter, must match the type of one of the available Filters

Example
{
  "config": "object",
  "type": "inject"
}

Health

reporting: Reporting
watchdogRestartMinutes: integer (int64) 10

The number of minutes with no advertisements processed that will trigger an auto restart of Bluetooth/HCI.

Example
{
  "service": {
    "health": {
      "reporting": {
        "filterId": "my-mqtt",
        "topic": "/health",
        "secFrequency": 900,
        "intervalMinutes": 0
      }
    }
  }
}

Log

Log describes the logging configuration

bleDebug: boolean false

If true, enable debug logging from the BLE layer

eventHistory: integer (int64) -1

Number of pipeline events to keep in memory in a rolling buffer, for debugging purposes. Can be accessed via /pipelines/events API endpoint Set to -1 to disable, which is the default. Maximum value 10000.

includeUnmatchedHistory: boolean false

Include pipeline events in history that don't match any pipelines.

level: string info

The log level. Valid options are: debug, info, error, fatal

printJSONEvents: boolean false

If true, events will be printed as indented JSON instead of the native "map:[key:value]" format note: this will have a significant performance penalty, use for debugging only

printTimestamps: boolean false

If true, log messages will contain timestamps.

suppressAdvDecodeErrors: boolean false

If true, advertisement decode errors will be suppressed

Example
{
  "service": {
    "log": {
      "level": "info",
      "printTimestamps": false,
      "printJSONEvents": false,
      "eventHistory": 0,
      "includeUnmatchedHistory": false
    }
  }
}

Matcher

Configures a set of key/value pairs for purposes of matching an input map. Allowable value types are string (match one value), []interface{} (match any of the values).

For example, the config below would match an event with: "key1"=("value1" OR "value2") AND "key2"="value3"

{ "key1": []interface{}{"value1", "value2"}, "key2": "value3", }

object
Example
{
  "rssi": ">-40",
  "serviceData.fd95": ""
}

MatcherSet

Configures a set of key/value pairs as well as a list of top level matchers

match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
Example
{
  "match": {
    "rssi": ">-40",
    "serviceData.fd95": ""
  },
  "matchAny": "boolean",
  "matchers": [
    "is-nearby",
    "is-my-device-type"
  ]
}

Metadata

Configures the initial map of metadata that is loaded at startup. Device specific identifiers, api keys, and other application specific items can be defined here for later lookup in Pipelines or ConnectionSequences.

devices: object

Device metadata to initialize

global: object

Global metadata to initialize

persistent: boolean

Store device and global metadata persistently on the file system. Metadata will be reloaded if Edge Connect restarts, including if the gateway is rebooted.

Example
{
  "global": {
    "secretAPIKey": "sdfjhsdfjkhsdfjk"
  },
  "devices": {
    "someMacAddress": {
      "mySensorID": "sensor1234124"
    }
  }
}

Metrics

reporting: Reporting
Example
{
  "service": {
    "metrics": {
      "reporting": {
        "filterId": "my-mqtt",
        "topic": "/metrics",
        "secFrequency": 60,
        "intervalMinutes": 0
      }
    }
  }
}

Pipeline

Pipeline describes the configuration for one event processing pipeline. Pipelines can process BLE advertisements device status events (new device discovered, device gone missing), and cloud events.

debug: boolean false

Enable debug logging

disabled: boolean false

If set to true, this pipeline will be disabled and will not process events.

eventType: string

The type of events to process in this Pipeline.

Supported options:

advertisement (default) for BLE advertising events

deviceStatus for events about newly discovered devices, devices that have disappeared, and (optionally) batteryLevel

cloud for events from cloud subscriptions

filters: object[]

The list of Filters, in order, that event data will flow through.

The list can contain a mix of strings, or objects.

If a string is provided, it must match a named filter defined in the filters section of Config.

If an object is provided, it must have one key:value pair. The key must the the type of filter and the value must be the config object for that particular filter.

References the filters defined on Config

object
groups: string[]

The list of DeviceGroups to receive events for. Defaults to an empty list, which means this pipeline will receive all events that match its eventType, regardless of DeviceGroup.

References the groups defined on Config

string
match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "pipelines": {
      "eddypipe": {
        "filters": [
          "eddyf",
          {
            "inject": {
              "keyPairs": {
                "source": "an inline filter!"
              }
            }
          },
          "my-mqtt"
        ],
        "eventType": "advertisement",
        "groups": [
          "east-wing-eddystones"
        ]
      }
    }
  }
}

ReduceConfig

Configuration for processing of the reduce filter.

reduce: string

Reduce template The array of values extracted with the value template will be passed into this template under the key __items (type []interface{}) for processing.

value: string

Value template used to collect an array of values from a collection of maps. The array of collected values is passed to the reduce function under key __items.

Example
{
  "reduce": "{{ maxf .__items }}",
  "value": "{{ .rssi }}"
}

Reporting

intervalMinutes: integer (int64) 10

The frequency in minutes in which data will be reported to cloud-based monitoring.

Example
{
  "service": {
    "metrics": {
      "reporting": {
        "filterId": "my-mqtt",
        "topic": "/metrics",
        "secFrequency": 60,
        "intervalMinutes": 0
      }
    },
    "health": {
      "reporting": {
        "filterId": "my-mqtt",
        "topic": "/health",
        "secFrequency": 900,
        "intervalMinutes": 0
      }
    }
  }
}

RestAPI

RestAPI describes the configuration for the API server running inside of Edge Connect

devmode: boolean false

If devmode is set to true, the API server is accessible from any IP, not just localhost. If set to false, the API is only available locally.

port: integer (int64) 62307

The port to host the API server on

Example
{
  "service": {
    "api": {
      "port": 62307,
      "devmode": true
    }
  }
}

Template

Templates are strings used to compute strings or other values. They can be used for a number of key/value pairs in configuration. Refer to each filter / action / cloud connector for places in which templates can be used.

See Edge Connect Templates for more detail.

Example
"object"

Connection Actions

encrypt

Attempts to enable encryption using previously obtained encryption information. If the encryption information is not available, this command will fail.

Output: None

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "encrypt-comm": {
        "type": "encrypt"
      }
    }
  }
}

loop

The loop action allows you to perform a connection sequence in a loop. There are 3 modes of operation for the loop action:

  • In count mode, the connection sequence is executed N times by providing count.
  • In matcher mode, the connection sequence is executed while the matcher is true.
  • In collection mode, the connection sequence is executed with each item from the collection stored in item.id/item.value.

Output: output of the underlying connection se quence

collection: string

Iterate over a collection must be a template that outputs a map[string]interface{} or []interface

condition: PolicySet
count: integer (int64)

Provide the number of iterations to run the loop to enable count mode.

debug: boolean false

Enable debug logging

id: string

The ID of the Connection Sequence that should be looped

match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "loop-example": {
        "type": "loop",
        "config": {
          "id": "read-more-data",
          "match": {
            "more-data": "true"
          }
        }
      }
    }
  }
}

notificationControl

Enable/disable notifications/indications for a characteristic

This action enables/disables notifications for a characteristic. To receive notifications, use the wait action.

characteristic: string

The UUID of characteristic to read supports templating

debug: boolean false

Enable debug logging

enable: boolean

Enable or disable notifications/indications for the characteristic

indication: object

If true, indications are enabled for the characteristic boolean or template string

service: string

The UUID of the service to which the characteristic belongs supports templating

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "turn-on-notis": {
        "type": "notificationControl",
        "config": {
          "characteristic": "2a26",
          "enable": false,
          "indication": true,
          "service": "375aee4c-6dea-5105-9074-14d5ba44f766"
        }
      }
    }
  }
}

pair

Attempts to create a pairing with the connected device.

Edge Connect will defer to the pairing parameters specified in the device pairing response. If bonding is specified, the encryption key will be stored locally. If the device is already paired, this action may fail. Legacy and LESC pairings are supported. JustWorks, Passkey, and OOB Data are all supported pairing methods.

To use Passkey, supply the key passkey within the input map. The Passkey must be either a numeric string ("123456") or a number (123456). Valid values are 0-999999, inclusive.

To use OOB Data, specify the key oobData in the input map. The OOB Data must be specified as bytes encoded in a base64 string or a byte array.

Note: The actual pairing method used, regardless of the specified key, is based on the table in the Bluetooth specification found here: Core v5.0 Vol 3, Part H, 2.3.5.1 Tables 2.6, 2.7, and 2.8

The use of Passkey and OOB Data are mutually exclusive. If both are specified, execution will fail with an error.

Output: The input map without changes

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "pair-with-device": {
        "type": "pair"
      }
    }
  }
}

read

Read the value of a characteristic

Output: This action adds outputKey containing the data read from the characteristic as an array of bytes.

Data from this action can be sent to the write action by using an output key of writeData see the write action docs for more details.

characteristic: string

The UUID of characteristic to read supports templating

debug: boolean false

Enable debug logging

outputKey: string

The map key for the output data. Supports dot notation and text templating.

service: string

The UUID of the service to which the characteristic belongs supports templating

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "read-custom-char": {
        "type": "read",
        "config": {
          "characteristic": "2a26",
          "outputKey": "battery",
          "service": "375aee4c-6dea-5105-9074-14d5ba44f766"
        }
      }
    }
  }
}

readBattery

Attempts to read the battery level characteristic from the standard GATT Battery Service. The service UUID is 180f and the value characteristic UUID is 180a.

Output: The battery level as a percentage (0-100) with an output key as specified in the configuration.

debug: boolean false

Enable debug logging

outputKey: string batteryLevel

The key name used to store the battery level Supports dot notation and text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "read-the-battery": {
        "type": "readBattery",
        "config": {
          "outputKey": "batteryLevel "
        }
      }
    }
  }
}

readDeviceInfo

Read all available characteristics of the device information service if available. All data is placed into a map using the specified output key.

Output: Outputs the following keys with their values when the data is present: mfgName, modelNumber, serialNumber, hwRev, swRev, fwRev, systemId, ieeeCertList, pnpId.

debug: boolean false

Enable debug logging

outputKey: string

Specifies the key to be used for the output. Supports dot notation and text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "read-all-the-device-info": {
        "type": "readDeviceInfo",
        "config": {
          "outputKey": "deviceInfo"
        }
      }
    }
  }
}

run

TODO: docs

debug: boolean false

Enable debug logging

id: string
if: MatcherSet
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "run-example": {
        "type": "run",
        "config": {
          "id": "read-more-data",
          "if": {
            "match": {
              "needToRead": "true"
            }
          }
        }
      }
    }
  }
}

wait

Wait pauses a set of actions until some behavior occurs. Typical waiting patterns are for a certain mount of time, or to await a notification/indication to occur.

Output: Waiting for a notification will output the input map plus the notification data. Waiting for a certain period of time pass data through to the next action.

characteristic: string

UUID of characteristic to wait for a notification from

debug: boolean false

Enable debug logging

indicationOverride: string

todo: scrub Dynamically override notification or indication modes with this template

interval: string

The amount of time to wait for. Only valid when the mode is "time". When the mode is "time", this specifies how long to wait. When the mode is "notification", this specifies how long to wait for the notification. If the notification is not received in that time, a nil result will be placed in the output key.

keepNotificationsEnabled: boolean

When the mode is "notification", setting this true will prevent the notifications from being disabled

mode: string

The type of wait to perform. The options are: time, notification, indication

multi: boolean

collect multiple notifications/indications until a timeout is reached must recieve at least one notification/indication for success combine with: outputMode = append/array mode = notification/indication

outputKey: string

When the mode is "notification", this specifies the output key for the notification data. Supports dot notation/templating.

outputMode: string replace

When the mode is "notification", this specifies the output mode "replace" will replace the contents with the new notification data (outputs []byte) "append" will append the new notification data to old notification data (outputs []byte) "array" will add the new notification data to an array of notification data (outputs [][]byte) When mode is "append", the last item to be appended is also inserted into the "lastItem" key. options: replace, append, array

service: string

UUID of the service to wait for a notification from

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "wait-for-something": {
        "type": "wait",
        "config": {
          "interval": "10s",
          "keepNotificationsEnabled": false,
          "mode": "time",
          "outputKey": "",
          "outputMode": ""
        }
      }
    }
  }
}

write

Writes data to a characteristic.

If the input event contains any of the following data payload keys with the specified types, data from the event will be converted to bytes, deleted from the event and written to the specified service/characteristic. If no data payload key is present, the data provided in the data configuration item will be written, In the case that data is not set and no data payload key is present, an error will be returned.

Data Payload Keys: writeData: hex string -> []byte or []byte (no conversion) writeBase64: base64 string -> []byte or []interface{} with base64 strings -> [][]byte writeString: ascii string -> []byte

Output: None

acknowledge: AcknowledgeConfig
characteristic: string

UUID of characteristic to read supports templating

data: string

The data to write to the characteristic formatted as a hexadecimal or base64 string. While data is not required, if no data payload key (see above) is present this action will report an error.

debug: boolean false

Enable debug logging

header: string

Add a template or hexstring header

headerEveryWrite: boolean false

Add the header to every write in chunked mode

maxWriteSize: integer (int64) 0

Set maximum number of bytes to write at once (0 for disabled)

service: string

UUID of the service to which the characteristic belongs supports templating

verbose: boolean false

Enable verbose logging

withResponse: object true

Should perform write and wait for response? boolean or template

Example
{
  "service": {
    "actions": {
      "write-something": {
        "type": "write",
        "config": {
          "characteristic": "2a26",
          "data": "01ae489c25",
          "service": "375aee4c-6dea-5105-9074-14d5ba44f766"
        }
      }
    }
  }
}

Cloud Connectors

azuredps

This cloud connector provides per-device connections to Azure IoT Hub, with connections provisioned by Azure DPS. Each device that communicates with this cloud connector will get a dedicated connection with authorization from the Azure DPS service.

Cloud to device messages arrive in pipelines as an event with cloud eventType. The payload is included in the payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

DirectMethods also fire as cloud eventType events, but they also include a requestId key. To respond to the DirectMethod, publish to this cloud connector and make sure to include the requestId in the event map. The requestId doesn't need to be in the actual payload published to Azure, just in the event map that reaches the publish filter.

DirectMethods in Edge Connect only support map/object input and map/object response, not primitives.

capabilityModelIdKey: string capabilityModelId

The key that contains the Capability Model ID of the device.

debug: boolean false

Enable debug logging

devices: object

Device configuration, primarily for translating MAC address to Device IDs

deviceIdTemplate: string

A text template for converting the lowercase mac field to any deviceId that is desired by the cloud configuration. This template is used to generate a Device ID that is then used to attach to the cloud and subscribe to topics. If no deviceIdTemplate is supplied, defaults to using the lowercase MAC address of the device.

directMethods: object

Direct Methods A map of capabilityModelIds to a list of commands that they support

directMethods: string[]

A list of Direct Methods to subscribe to for all device types

string
host: string

The DPS Registration Host URL

idScope: string

The ID Scope of the Azure DPS Service. A unique value used by the IoT Hub Device Provisioning Service.

nonPersistentMaxCount: integer (int64) 1000

If set to > 0, this will set the maximum number of messages the MQTT memorystore will hold before dropping messages Must be used with persistent=false

persistent: boolean false

If set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be reloaded upon restart or reboot if they were not yet processed.

persistentMaxSize: string 1GiB

If set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore can consume before dropping messages. Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB. Must be used with persistent=true

previewAPI: boolean false

Use the new preview API of DPS

reconnectTimeout: string 1m

How long to wait before retrying to connect a failed/disconnected device to IOT Hub This is used when a device is waiting for approval, gets blocked, or gets otherwise disconnected. Supports durations in the form of 1s 5m 1h etc.

sasKey: string

The Shared Access Signature key to use to generate device keys when authenticating with Azure DPS.

unwrapCloudPayload: boolean false

Put the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-dps": {
          "type": "azuredps",
          "config": {
            "devices": {
              "deviceIdTemplate": "my_device_{{ .mac }}"
            },
            "host": "https://global.azure-devices-provisioning.net",
            "idScope": "0123f0_redacted",
            "sasKey": "abcdf_redacted_abcd"
          }
        }
      }
    }
  }
}

azureiot

This cloud connector provides a connection to the Azure IoT Device cloud.

Supports publishing telemetry and receiving cloud commands, but does not support topic based publishing, or topic based subscriptions.

Cloud to device messages arrive in pipelines as an event with cloud eventType. The payload is included in the payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

DirectMethods also fire as cloud eventType events, but they also include a requestId key. To respond to the DirectMethod, publish to this cloud connector and make sure to include the requestId in the event map. The requestId doesn't need to be in the actual payload published to Azure, just in the event map that reaches the publish filter.

DirectMethods in Edge Connect only support map/object input and map/object response, not primitives.

connectionString: string

The connection string provided by Azure IoT for the connecting device.

debug: boolean false

Enable debug logging

directMethods: string[]

Direct Methods to subscribe to

string
nonPersistentMaxCount: integer (int64) 1000

If set to > 0, this will set the maximum number of messages the MQTT memorystore will hold before dropping messages Must be used with persistent=false

persistent: boolean false

If set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be reloaded upon restart or reboot if they were not yet processed.

persistentMaxSize: string 1GiB

If set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore can consume before dropping messages. Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB. Must be used with persistent=true

reconnectTimeout: string 1m

How long to wait before retrying to connect to IOT Hub Supports durations in the form of 1s 5m 1h etc.

unwrapCloudPayload: boolean false

Put the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-azure": {
          "type": "azureiot",
          "config": {
            "connectionString": "azureiot:connectionstring"
          }
        }
      }
    }
  }
}

azureiotcentral

This cloud connector provides per-device connections to the Azure IoT Central Cloud. Each device that communicates with this cloud connector will get a dedicated connection with authorization from the Azure DPS service.

Commands fire as cloud eventType events, and include a requestId key. To respond to the Command, publish to this cloud connector and make sure to include the requestId in the event map. The requestId doesn't need to be in the actual payload published to Azure, just in the event map that reaches the publish filter.

Commands in Edge Connect only support map/object input and map/object response, not primitives.

capabilityModelIdKey: string capabilityModelId

The key that contains the Capability Model ID of the device.

debug: boolean false

Enable debug logging

devices: object

Device configuration, primarily for translating MAC address to Device IDs

commands: object

Commands A map of capabilityModelIds to a list of commands that they support

deviceIdTemplate: string

A text template for converting the lowercase mac field to any deviceId that is desired by the cloud configuration. This template is used to generate a Device ID that is then used to attach to the cloud and subscribe to topics. If no deviceIdTemplate is supplied, defaults to using the lowercase MAC address of the device.

directMethods: string[]

A list of Direct Methods to subscribe to for all device types

string
idScope: string

The ID Scope of the Azure IOT Central Application. A unique value used by the IoT Hub Device Provisioning Service. Can be found in the Administration/Device Connection page on the IOT Central site.

nonPersistentMaxCount: integer (int64) 1000

If set to > 0, this will set the maximum number of messages the MQTT memorystore will hold before dropping messages Must be used with persistent=false

persistent: boolean false

If set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be reloaded upon restart or reboot if they were not yet processed.

persistentMaxSize: string 1GiB

If set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore can consume before dropping messages. Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB. Must be used with persistent=true

previewAPI: boolean false

Use the new preview API of IOT Central

reconnectTimeout: string 1m

How long to wait before retrying to connect a failed/disconnected device to IOT Central This is used when a device is waiting for approval, gets blocked, or gets otherwise disconnected. Supports durations in the form of 1s 5m 1h etc.

sasKey: string

The Shared Access Signature key to use to generate device keys when authenticating with Azure IOT Central. Can be found in the Administration/Device Connection page on the IOT Central site.

unwrapCloudPayload: boolean false

Put the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-iotcentral": {
          "type": "azureiotcentral",
          "config": {
            "capabilityModelIdKey": "",
            "devices": {
              "deviceIdTemplate": "my_device_{{ .mac }}"
            },
            "idScope": "0123f0_redacted",
            "sasKey": "abcdf_redacted_abcd"
          }
        }
      }
    }
  }
}

digitalTwins

This connector sends sensor telemetry data to Microsoft Azure Digital Twins. All devices, sensors, matchers, and user defined functions must already be setup in Digital Twins. The device must also have a role that allows it to update sensor values. The cloud connector simply authenticates the device (the Gateway) and then routes telemetry data for each sensor over MQTT.

Supports publishing but does not support subscriptions.

baseURL: string

The BaseURL of the digital twins instance to use

debug: boolean false

Enable debug logging

deviceHardwareId: string

The device hardwareId in Digital Twins that matches the Gateway running Edge Connect and for which the SAS token is issued.

nonPersistentMaxCount: integer (int64) 1000

If set to > 0, this will set the maximum number of messages the MQTT memorystore will hold before dropping messages Must be used with persistent=false

persistent: boolean false

If set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be reloaded upon restart or reboot if they were not yet processed.

persistentMaxSize: string 1GiB

If set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore can consume before dropping messages. Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB. Must be used with persistent=true

sasToken: string

A Shared Access Signature that has been generated for this deviceId

sensorHardwareIdKey: string

A key in the incoming data that maps to the sensor hardwareId for the particular sensor in Digital Twins

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-dt": {
          "type": "digitalTwins",
          "config": {
            "baseURL": "mydigitaltwinsinstance.westcentralus.azuresmartspaces.net",
            "deviceHardwareId": "D149731826-00310",
            "sasToken": "SharedAccessSignature id=D149731826-00310&se=44456789124&kv=1&sig=djmMcgXRRDBdvIIJZCogvxRynxUniyCwGlmUF7vgB6TlLvk%3D",
            "sensorHardwareIdKey": "mac"
          }
        }
      }
    }
  }
}

googlecloudiot

This cloud connector provides a connection to the Google Cloud IoT Core service.

Supports publishing on topics and subscribing to topics. Also supports Device configuration via linking to a Device Group.

For devices to be attached to a Gateway successfully, they first need to be "bound" in the Google Cloud IOT Core API/settings. At startup, or when dynamically attached, an "attach" message is sent to Google to let it know the device is online. This will fail if the device is not already "bound" on the Google side.

Cloud to device messages arrive in pipelines as a cloud eventType. The topic is included in the topic key and the payload is included in the payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

connectMessage: CloudMessage
debug: boolean false

Enable debug logging

devices: CloudConnectorDevices
gatewayId: string

ID of this Gateway in Google Cloud. Required by Google to start with a lowercase character, so if the Gateway serial number is used, make sure to lowercase it.

nonPersistentMaxCount: integer (int64) 1000

If set to > 0, this will set the maximum number of messages the MQTT memorystore will hold before dropping messages Must be used with persistent=false

persistent: boolean false

If set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be reloaded upon restart or reboot if they were not yet processed.

persistentMaxSize: string 1GiB

If set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore can consume before dropping messages. Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB. Must be used with persistent=true

privateKey: string

Private Key that matches the Public Key for this Gateway that was provided to Google.

projectId: string

Google Project ID

region: string

Google Region the project is in

registryId: string

Google IOT Registry ID

subscribeTopics: string[]

Topics to subscribe to. Incoming messages on these topics will arrive in pipelines as cloud type events.

Supports text templating.

string
unwrapCloudPayload: boolean false

Put the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "googlecloud": {
          "type": "googlecloudiot",
          "config": {
            "gatewayId": "gatewaySerialLowercased",
            "privateKey": "....",
            "projectId": "myproject",
            "region": "uswest",
            "registryId": "myregistry"
          }
        }
      }
    }
  }
}

http

This cloud connector represents an HTTP destination using the URL and method specified.

Support publishing but no subscriptions.

debug: boolean false

Enable debug logging

headers: object

Headers contains a map of key and value pairs to place in the headers section of the HTTP request. Typically, these headers would include things like an API key or other authentication data. Supports text templating.

method: string

Tells the filter which HTTP command to use to send data. Valid options are POST and PUT.

persistent: boolean false

Enable persistent storage for failed requests

retryDelayMultiplier: number (double) 1.1

Retry delay multiplier, the retry delay will be multiplied by this value on each request error

retryDisable: boolean false

Disable retrying a request on error

retryInitialDelay: string 1s

Retry initial delay

retryMaxAttempts: integer (int64)

Maximum retry attempts If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded

retryMaxDelay: string 30m

Maximum delay between any retry

retryOfflineDelay: string 1m

Retry delay (fixed) when server is unreachable

retryTimeout: string 30m

How long to keep retrying a request when getting an error If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded

timeout: integer (int64) 30

A single HTTP request attempt will timeout after this length of time. The timeout is specified as an integer number of seconds. The default timeout is 30 seconds.

url: string

The HTTP url to send data Supports text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-http": {
          "type": "http",
          "config": {
            "headers": {
              "AuthToken": "something-secret"
            },
            "method": "POST",
            "url": "http://myserver.com/path"
          }
        }
      }
    }
  }
}

mqtt

This cloud connector provides a connection to an MQTT broker.

Support publishing on topics and subscriptions on topics.

Cloud to device messages arrive in pipelines as an event with cloud eventType. The payload is included in the payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

base: string

The base address of the broker. This is required by some brokers, such as AWS IoT

clientId: string the hostname (typically the serial number of the gateway)

The ClientID to use in the MQTT connection.

connectMessage: CloudMessage
credentials: object

A set of base64 encoded TLS credentials.

ca: string

Certificate authority (may be optional as some certificates already contain this information)

cert: string

TLS certificate

key: string

TLS private key

debug: boolean false

Enable debug logging

devices: CloudConnectorDevices
host: string

The host address of the broker

nonPersistentMaxCount: integer (int64) 1000

If set to > 0, this will set the maximum number of messages the MQTT memorystore will hold before dropping messages Must be used with persistent=false

persistent: boolean false

If set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be reloaded upon restart or reboot if they were not yet processed.

persistentMaxSize: string 1GiB

If set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore can consume before dropping messages. Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB. Must be used with persistent=true

port: integer (int64)

The port of the broker

scheme: string

The communication protocol of the broker. Options are: tcp, tcps, wss, ssl

subscribeTopics: string[]

Topics to subscribe to. Incoming messages on these topics will arrive in pipelines as cloud type events.

Supports text templating.

string
unwrapCloudPayload: boolean false

Put the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "type": "mqtt",
          "config": {
            "base": "",
            "host": "iothub.myserver.net",
            "port": 8883,
            "scheme": "tcps"
          }
        }
      }
    }
  }
}

websocket

This cloud connector represents a websocket connection

binaryMode: boolean false

Enable binary mode for messages to cloud If false, messages will be sent to the cloud in text mode

debug: boolean false

Enable debug logging

headers: object

Headers contains a map of key and value pairs to place in the headers section of the HTTP request. Typically, these headers would include things like an API key or other authentication data.

persistent: boolean false

Enable persistent storage for failed requests

retryDelayMultiplier: number (double) 1.1

Retry delay multiplier, the retry delay will be multiplied by this value on each request error

retryDisable: boolean false

Disable retrying a request on error

retryInitialDelay: string 1s

Retry initial delay

retryMaxAttempts: integer (int64)

Maximum retry attempts If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded

retryMaxDelay: string 30m

Maximum delay between any retry

retryOfflineDelay: string 1m

Retry delay (fixed) when server is unreachable

retryTimeout: string 30m

How long to keep retrying a request when getting an error If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded

url: string

The websocket url to connect to

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "cloud": {
      "connectors": {
        "my-websocket": {
          "type": "websocket",
          "config": {
            "headers": {
              "AuthToken": "something-secret"
            },
            "url": "wss://server.com/xyz"
          }
        }
      }
    }
  }
}

Device Group Types

persistent

Persistent device groups operate the same as static device groups, with the exception that dynamically added devices persist across reboots. This makes persistent groups better suited for dynamic provisioning, while static groups are better suited for pre-configured device lists.

absenceMinutes: integer (int64) 5

The number of minutes to tolerate a device being missing before reporting it

batteryEvents: DeviceGroupBattery
debug: boolean false

Enable debug logging

deviceIdTemplate: string

A template for converting an advertisement into a Device ID to identify unique devices. If omitted, the Device ID will be the MAC address in all lowercase w/ no colons.

disableMonitoring: boolean false

Disable sending monitoring events for this group to the Edge Direct

exclude: string[]

Deprecated: The list of mac addresses to exclude from the device group.

string
excludeAllByDefault: boolean true

Deprecated: If set, a device is excluded unless it is in the include list.

include: string[]

The list of mac addresses to include in the device group. Overrides the exclude list.

string
includeMatchers: MatcherSet
match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "groups": {
      "my-eddystones": {
        "type": "persistent",
        "config": {
          "absenceMinutes": 19,
          "exclude": [
            "eddymac4",
            "eddymac5",
            "eddymac6"
          ],
          "include": [
            "eddymac1",
            "eddymac2",
            "eddymac3"
          ]
        }
      }
    }
  }
}

static

A static Device Group tracks devices based on an include list.

If an includeList is provided, devices must match the include list.

If both are omitted, all devices are matched to this group.

Any device in the group is considered present if it has been seen within absenceMinutes.

Any device in the group that goes missing for absenceMinutes will be considered not present.

Any time a new device is discovered, or the presence changes from true to false or vice versa, a Device Status event will be fired. See Pipeline for information on how to subscribe to Device Status events.

Devices in the include list that are not seen after absenceMinutes from startup are considered not present, and a device status event will be fired with present=false.

absenceMinutes: integer (int64) 5

The number of minutes to tolerate a device being missing before reporting it

batteryEvents: DeviceGroupBattery
debug: boolean false

Enable debug logging

deviceIdTemplate: string

A template for converting an advertisement into a Device ID to identify unique devices. If omitted, the Device ID will be the MAC address in all lowercase w/ no colons.

disableMonitoring: boolean false

Disable sending monitoring events for this group to the Edge Direct

exclude: string[]

Deprecated: The list of mac addresses to exclude from the device group.

string
excludeAllByDefault: boolean true

Deprecated: If set, a device is excluded unless it is in the include list.

include: string[]

The list of mac addresses to include in the device group. Overrides the exclude list.

string
includeMatchers: MatcherSet
match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "groups": {
      "my-eddystones": {
        "type": "static",
        "config": {
          "absenceMinutes": 19,
          "exclude": [
            "eddymac4",
            "eddymac5",
            "eddymac6"
          ],
          "include": [
            "eddymac1",
            "eddymac2",
            "eddymac3"
          ]
        }
      }
    }
  }
}

Use as Filter or Action

append

This filter appends the data in the item key onto the array in the array key. If the array key does not exist, a new array is created, with the item value as the initial element.

Output: The input event with the source data appended to the target key.

array: string

The key of the array to append the item to. Supports dot notation and text templating.

debug: boolean false

Enable debug logging

deleteItem: boolean

If true, delete the original item key/value after appending to the array.

item: string

The key of the item to append to the array. Supports dot notation and text templating.r

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-append": {
        "type": "append",
        "config": {
          "array": "array",
          "item": "item"
        }
      }
    }
  }
}

decodeLTV

This filter decodes binary L(ength) (T)type (V)alue data into a map. Data can be in the format of a singular LTV or repeated LTVLTVLTVLTV.

For streams of primitive types in predictable order, the typeConvert filter should be used instead. The intent of this filter is to read streams of complex types that have multiple fields. Each LTV instance can be in unpredictable order, but the fields inside of the LTV must be of predictable order.

Each LTV in the byte stream represents one instance of an EncodedLTV. The length byte of the object is read, then the type byte. The type is used to lookup an EncodedLTV definition, which then describes how to read each field of the type. By default, each field from each type is merged into one final output event, with all keys in it. If there are to be multiple instances of a given EncodedLTV, they can be collected into an Array using the appendToArray property on EncodedLTV.

See the documentation for EncodedLTV and EncodedField for more details. To see the available primitive types available see the documentation for the typeConvert filter.

dataKey: string data

The key to read the data from.

debug: boolean false

Enable debug logging

lengthInclusive: boolean false

LengthInclusive describes whether the length includes the length byte itself

outputKey: string decoded

The key to store decoded data in

typeInclusive: boolean false

TypeInclusive describes whether the length includes the type byte

types: object

A map of friendly names to EncodedType descriptions of the types that appear in the data.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "decode-my-data": {
        "type": "decodeLTV",
        "config": {
          "dataKey": "data",
          "lengthInclusive": true,
          "outputKey": "decoded",
          "typeInclusive": true,
          "types": {
            "event": {
              "appendToArray": "events",
              "fields": [
                {
                  "key": "eventType",
                  "length": 4,
                  "type": "intLE"
                },
                {
                  "key": "eventData",
                  "length": 8,
                  "type": "intLE"
                }
              ],
              "id": 3
            },
            "metadata": {
              "fields": [
                {
                  "key": "serialNumber",
                  "length": 4,
                  "type": "intLE"
                },
                {
                  "key": "deviceName",
                  "length": 16,
                  "type": "string"
                }
              ],
              "id": 1
            },
            "telemetry": {
              "fields": [
                {
                  "key": "xPos",
                  "length": 8,
                  "type": "floatLE"
                },
                {
                  "key": "yPos",
                  "length": 8,
                  "type": "floatLE"
                }
              ],
              "id": 2
            }
          }
        }
      }
    }
  }
}

decodeType

This filter decodes binary data of a single fixed type into a map. Data can be in the format of a singular value or repeated values of the same type.

This filter is very similar to the decodeLTV filter, but works with one fixed type. The data stream cannot include length/type information, but rather contains repeated instances of the EncodedType, with only the field data present.

By default, values are collected into an array in the outputKey field. If outputMap is set to true, then the fields will be placed in a map inside the outputKey, with subsequent instances of fields replacing the values of previous fields.

See the documentation for EncodedType and EncodedField for more details. To see the available primitive types available see the documentation for the typeConvert filter.

dataKey: string data

The key to read the data from.

debug: boolean false

Enable debug logging

outputKey: string decoded

The key to store decoded data in

outputMap: boolean false

If set to true, the object(s) that are decoded will be merged into one output map, rather than appended to an array.

type: EncodedType
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "decode-my-fixed-data": {
        "type": "decodeType",
        "config": {
          "dataKey": "data",
          "outputKey": "decoded",
          "type": {
            "fields": [
              {
                "key": "serialNumber",
                "length": 4,
                "type": "intLE"
              },
              {
                "key": "deviceName",
                "length": 16,
                "type": "string"
              }
            ]
          }
        }
      }
    }
  }
}

delete

This filter deletes the specified keys from the input map.

Output: The output map is a copy of the input map with the specified keys deleted.

debug: boolean false

Enable debug logging

keys: string[]

Keys to delete

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "delete-bad-keys": {
        "type": "delete",
        "config": {
          "keys": [
            "extraneous-key",
            "and-another-one-too"
          ]
        }
      }
    }
  }
}

hash

This filter calculates, appends or validates hash values Supported algorithms: md5 sha1 sha224 sha256 sha384 sha512 crc32-ieee crc64-ecma crc64-iso crc16-ccitt-false crc16-ccitt

Supported types for inputKey: string []byte

Output: In append mode, the outputKey will contain the data from inputKey with the hash value appended In compute mode, the outputKey will contain the hash value calculated from data in the inputKey In validate mode, the outputKey will contain the data in the inputKey with the hash removed In hmac mode, the outputKey will contain the hmac calculated from the hmacKey and inputKey In expect mode, the hash value calculated from data in the inputKey will be compared to the value specified in the expect field, if the hashes match the event will be emitted, otherwise nil is emitted.

Endianness: when computing a hash the input endianness must be little endian when reading/writing a hash value as []byte, the default endianness is little endian when reading/writing a hash value as string, the default endianness is little endian (except for crc16)

algorithm: string

Set hash algorithm

append: boolean

Enable append mode

compute: boolean

Enable compute mode

debug: boolean false

Enable debug logging

expect: string

Enable expect mode

hashBytesBigEndian: boolean false

Handle hash array as big endian

hashStringBigEndian: boolean false

Handle hash strings as big endian Default is false for all algorithms except crc16

hmac: boolean false

enable HMAC mode

hmacKey: string

Set the HMAC key (supports templating, hexstring or base64) Must be set if hmac == true

inputKey: string

Define the input key Supports dot notation and text templating.

outputKey: string

Define the output key Supports dot notation and text templating.

outputSize: integer (int64) 0

Set output size If default hash output size < outputSize, will pad hash output with 0's If default hash output size > outputSize, will truncate hash output if outputSize == 0, default for hash is used

verbose: boolean false

Enable verbose logging

verify: boolean

Enable verify mode (assumes input has hash appended)

Example
{
  "service": {
    "filters": {
      "decode-resp": {
        "type": "hash",
        "config": {
          "algorithm": "crc16-ccitt-false",
          "append": false,
          "compute": false,
          "inputKey": "dataToVerify",
          "outputKey": "data",
          "verify": true
        }
      }
    }
  }
}

httpFetch

This filter performs an HTTP request against a specified endpoint.

Output: The filter outputs the HTTP response body to the defined outputKey.

The HTTP response body will be converted based on the content-type header. application/json -> map[string]interface{} text/plain -> string all other types -> []byte

body: string none (empty body)

The HTTP body to use in the request (template)

bodyFormatter: string json

The formatter used to encode the HTTP request body

cacheMaxItems: integer (int64) 64

Max Cache size in items

contentTypeOutputKey: string none (HTTP response Content-Type will not be output in the event)

Defines the output key for the HTTP response Content-Type in the event map.

debug: boolean false

Enable debug logging

headers: object

Headers contains a map of key and value pairs to place in the headers section of the HTTP request. Typically, these headers would include things like an API key or other authentication data. Supports text templating.

interval: string 1s

The HTTP request cache time to live (duration string) Sets the lifetime for a cached HTTP response. Setting to a 0 or negative duration value will disable caching.

method: string GET

The HTTP body Supports text templating.

outputKey: string httpResponse

Defines the output key for the HTTP response body in the event map.

persistent: boolean false

Enable persistent cache

timeout: string 30s

HTTP request timeout (duration string).

tlsSkipVerify: boolean false

Skip TLS verification, for development only

url: string

The HTTP url to send data Supports text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "httpGet": {
        "type": "httpFetch",
        "config": {
          "headers": {
            "AuthToken": "something-secret"
          },
          "interval": "25s",
          "outputKey": "my-output-key",
          "url": "https://myserver.net/data"
        }
      }
    }
  }
}

inject

This filter injects keys into the output event map. The injected keys are specified as key/value pairs using the top level keyPairs parameter.

Templating is supported, see Edge Connect Templates for more detail.

There are two reserved key pairs: serial and timestamp. Adding either of these keys as with blank values will insert the serial number and timestamp (using the value to select the output format) into the output event map. The output event map will contain all keys and values from the input. If a key name collision occurs, the injected key will be ignored.

Supported timestamp values:

  • "s": epoch seconds
  • "ms": epoch milliseconds
  • "us": epoch microseconds
  • "ns": epoch nanoseconds
  • standard golang time formats (see https://golang.org/pkg/time/#pkg-constants) use the constant name (case-sensitive) for example:
    • "RFC3339": RFC3339 date string
    • "UnixDate": Unix date string

Output: Contains all keys from the input and the injected keys.

debug: boolean false

Enable debug logging

keyPairs: object

Defines a set of keys and values to add to the event map output. Supports dot notation and text templating.

replaceExisting: boolean false

Replace key value pairs that already exist, instead of ignoring them

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-inject": {
        "type": "inject",
        "config": {
          "keyPairs": {
            "customSerialUnderscoreMac": "{{ .serial }}_{{ .mac }}}",
            "my-key": "my-value",
            "serial": ""
          }
        }
      }
    }
  }
}

matcher

This filter applies matchers to the event map. An inline matcher may also be defined with the match key (see MatcherConfig for details).

At least one matcher or inline matcher must be defined. All matchers are applied to the input map to determine if the event map is a match.

Output: If all matchers match the event map, the event map is emitted, otherwise nil is emitted.

debug: boolean false

Enable debug logging

match: Matcher
matchAny: boolean false

Should we match any of the provided matchers (true)? Or all of the matchers (false)

matchers: string[]

The list of top-level matcher IDs to apply to the input map

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-matcher": {
        "type": "matcher",
        "config": {
          "match": {
            "key1": [
              "thisValue",
              "orThisValue"
            ],
            "key2": "onlyThisValue"
          },
          "matchers": [
            "match-command1",
            "match-command2"
          ]
        }
      }
    }
  }
}

metadataClear

Clears metadata on input. In global mode, any input map will clear the specified global metadata. In device mode, any input map will clear the specified metadata from the device.

Output: unmodified input

allDevices: boolean false

Perform device metadata operations on all devices?

debug: boolean false

Enable debug logging

global: boolean false

Perform global metadata operations?

keys: string[] empty

The metadata keys to delete, all keys are deleted if empty

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "clear-batt-metadata": {
        "type": "metadataClear",
        "config": {
          "keys": [
            "batteryLevel"
          ]
        }
      }
    }
  }
}

metadataGet

Adds metadata on to an input map

In global mode, the specified global metadata will be added to the input map.

In device mode, the device specific metadata will be added to the input map.

Output: Input map with requested metadata added

debug: boolean false

Enable debug logging

global: boolean

Perform global metadata operations?

keys: string[]

The metadata data keys to add, all keys are added to the input map if empty.

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "add-batt-metadata": {
        "type": "metadataGet",
        "config": {
          "keys": [
            "batteryLevel"
          ]
        }
      }
    }
  }
}

metadataSet

Sets metadata on input.

In global mode, the specified keys from an input map will be set in global metadata.

In device mode, the specified keys from the input will be set in device specific metadata.

Output: unmodified input

debug: boolean false

Enable debug logging

global: boolean

Perform global metadata operations?

keys: string[]

The metadata keys to filter on for a given device, all keys are used if empty

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "store-batt-metadata": {
        "type": "metadataSet",
        "config": {
          "keys": [
            "batteryLevel"
          ]
        }
      }
    }
  }
}

ntp

This filter starts an internal NTP client and will inject NTP response data into an input event. Set getMaxOffset to add the maximum clock offset from the history window to the input event Set getHistory to add the full NTP request history for the given history window to the input event

At least one of getMaxOffset, getHistory must be set to true.

Output: Input map with NTP maximum clock offset or history injected

debug: boolean false

Enable debug logging

getHistory: boolean false

Add ntp sync history for the history window to input event?

getLastSuccess: boolean false

Add last successful ntp sync into input event?

getMaxOffset: boolean false

Add maximum clock offset from history window to input event?

historyWindow: string 1h

How far back to look in the NTP sync history when processing an event historyCount = (historyWindow/syncInterval) + 1 historyCount must be <= 1000

host: string 3.us.pool.ntp.org

Which NTP server to query

syncInterval: string 1m

NTP server query interval

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "ntp-monitor": {
        "type": "ntp",
        "config": {
          "getMaxOffset": true,
          "historyWindow": "30m",
          "host": "time.google.com",
          "syncInterval": "30s"
        }
      }
    }
  }
}

publish

Publish to a Cloud Connector. Publishes the whole event unless payloadKey or payloadsKey is specified. For topic based publishing, use the topic or payloadsKey options.

connector: string

ID of the Cloud Connector to publish to, defined in the Cloud Connectors Config.

debug: boolean false

Enable debug logging

format: string json

The format of the data to publish. Supported options are json and cbor.

payloadKey: string

The key of the payload to send. If left empty, the whole event map is sent.

payloadsKey: string

This key must point to a map of topic strings to payloads. Each entry in that map will be published to its respective topic.

timeout: string 10s

Timeout for publishing (negative for no timeout)

topic: string

The topic on which to publish outgoing messages. Supports text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "publishPayload": {
        "type": "publish",
        "config": {
          "connector": "my-cloud",
          "payloadKey": "payload",
          "topic": "my-topic"
        }
      }
    }
  }
}

reduce

This filter is used to reduce a collection of maps into a single value. For example, to calculate the mean rssi for an aggregated set of advertisement events. This filter is generally paired with the aggregate filter preceding it, or after collecting of notifications from a device.

Key concepts: value template The value template is used to get the relevant value out of each individual map for reducing. This value is then stored in an array that is passed to the reduce template. reduce template The reduce template is used to calculate a single value from the array of outputs of the value template.

Depending on the type of collection being processed, the data will be handled differently: array mode: all events in the array as a single group, one value outputted map mode: all events in the map are treated as a single group, one value outputted mapArray mode: events in each sub-array are treated as a single group, one value per key in the input map

debug: boolean false

Enable debug logging

key: string

Key that contains the collection of data to reduce. If set, this key will be used to locate the collection in the event. If unset, the whole event will be treated as the collection. supports templating, dot notation

values: object

Map of values to reduce/process from each aggregate. Each entry is a key value pair of the new output mapped to the configuration of the reducer to generate that output.

As an example, this configuration would get the largest rssi from the aggregate and store it in key max-rssi.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "rssi-calculations": {
        "type": "reduce",
        "config": {
          "values": {
            "average-rssi": {
              "reduce": "{{ meanf .__items }}",
              "value": "{{ .rssi }}"
            }
          }
        }
      }
    }
  }
}

remap

This filter remaps keys into the output. The keys to be remapped are specified as key/value pairs of "old key" to "new key" using the top level "keyPairs" key. Keys that are not found will be ignored.

Output: Contains all keys from the input, with specified keys remapped.

debug: boolean false

Enable debug logging

keyPairs: object

Defines a mapping of input keys to output keys for remapping. Supports dot notation and text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-remap": {
        "type": "remap",
        "config": {
          "keyPairs": {
            "oldKey1": "newKey1",
            "oldKey2": "newKey2"
          }
        }
      }
    }
  }
}

select

This filter selects only the specified keys from the input map.

Output: The output map contains only the specified keys from the input map, if none of the keys are present, an empty map is returned.

debug: boolean false

Enable debug logging

keys: string[]

Keys to select Supports dot notation and text templating.

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-select": {
        "type": "select",
        "config": {
          "keys": [
            "rssi",
            "mac",
            "my.nested.key"
          ]
        }
      }
    }
  }
}

sort

This filter is used to sort a collection of maps by a specific value.

Key concepts: value The value template is used to get a relevant value out of an individual map for sorting. The value template is executed on each event in a group of events and the output is stored in an array that is passed to the sorter. sorter The sorter will take the array of outputs from the value template and use it to sort the maps that the values were extracted from. The sorter can only handle numeric and string types, and all types in an array must match.

Depending on the collection being processed, the data will be handled differently: array mode: all events in the array as a single group, one value outputted map mode: all events in the map are treated as a single group, one value outputted mapArray mode: events in each sub-array are treated as a single group, one value per key in the input map

debug: boolean false

Enable debug logging

descending: boolean false

If true items will be sorted in descending order

key: string

If set, this key will be used to locate the data set in the event. If unset, the whole event will be treated as the data set. supports templating, dot notation

maxEntries: integer (int64) 0

If >0, the first N items will be returned in the sorted array. If there are less than N items in the sorted array, all items are returned. If <=0, all items will be returned.

outputKey: string sorted

Set the output key for the sorted data. If omitted, defaults to sorted

value: string

Value template used to collect an array of values from a collection of maps. This array of collected values is used to sort the underlying maps.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "sort-by-rssi": {
        "type": "sort",
        "config": {
          "descending": true,
          "maxEntries": 2,
          "value": "{{ .rssi }}"
        }
      }
    }
  }
}

transform

This filter transforms values using templates and a limited set of available functions.

debug: boolean false

Enable debug logging

keyPairs: object

A map of keys to transformation templates. The value of each key is looked up, then transformed using the template.

See Edge Connect Templates for more detail.

For example, to transform a mac address to upper case with colons, you would map the mac key to the template string:

{{ .mac | ToUpper | AddColonsToMac }}

Also supports dot notation in key or value.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-transform": {
        "type": "transform",
        "config": {
          "keyPairs": {
            "mac": "{{ .mac | ToUpper | AddColonsToMac }}"
          }
        }
      }
    }
  }
}

typeConvert

This filter converts map keys from one type to another. Additionally, you can convert and inject, where a converted value is injected into the map, this allows selecting offset/length. The key can be specified using dot-notation.

Supported conversions:

  • any type to:
    • string (using fmt.Sprintf())
  • []byte to:
    • base64: standard base64 encoding
    • hex: ascii hex (lowercase)
    • intLE, intBE: integer (greedy conversion, will consume 1,2,4 or 8 bytes ignoring trailing bytes)
    • uintLE, uintBE: unsigned integer (greedy conversion, will consume 1,2,4 or 8 bytes ignoring trailing bytes)
    • floatLE, floatBE: floating point (greedy conversion, will consume 4 or 8 bytes ignoring trailing bytes)
    • fix88LE, fix88BE: fixed point 8.8
  • string to:
    • int: string to int64
    • uint: string to uint64
    • float: string to float64
    • []byte: base64/base64url/asciihex string to []byte

Output: If keys are defined in convertKeys:

    The filter will output a map with the specified keys in converted to the specified type If a single conversion fails, the remaining conversions will be processed If you wish to make a more specific conversion, use injectKeys and set the same source/destination keys

If keys are defined in injectKeys:

  • The filter will output a map with the specified keys injected
  • If a single inject fails, the other injections will be processed
  • injectKeys will only handle a []byte input so there is no interface{}->string allowed
  • You cannot inject into a map that does not exist

The actions are handled in the following order:

  1. process all injectKeys
  2. process all convertKeys

In the case that all operations fail, the input map will be passed through unchanged

convertKeys: object

Keys to convert Specify key-type conversions to perform Keys supports dot notation and text templating.

debug: boolean false

Enable debug logging

injectKeys: object

Keys to inject Specify conversion-injections to perform. Keys supports dot notation and text templating.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "convert-it": {
        "type": "typeConvert",
        "config": {
          "convertKeys": {
            "theKeyToConvert": "hex"
          },
          "injectKeys": {
            "theKeyToInject": {
              "length": 8,
              "offset": 1,
              "source": "nestedMap.keyWithBytesToConvert",
              "type": "intLE"
            }
          }
        }
      }
    }
  }
}

unwrap

This filter unwraps a key in the incoming data. For example, if the incoming data is "{"payload":{"key":"value"}}, and the key specified is set to "payload", the output will be "{"key":"value"}".

Any conflicting keys are replaced. The unwrapped keys are always placed at the top level, even if dot notation is used.

Any keys

Output: The input data with the specified key unwrapped.

debug: boolean false

Enable debug logging

key: string

The key to unwrap. Must target a map.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-wrap": {
        "type": "unwrap",
        "config": {
          "key": "payload"
        }
      }
    }
  }
}

wrap

This filter wraps the incoming data with the provided key value. For example, if the incoming data is "{"key":"value"}, and the key is set to "payload", the output will be "{"payload":{"key":"value"}}".

Output: The wrapped input data.

debug: boolean false

Enable debug logging

key: string

The key used to wrap the incoming data set. Supports dot notation and text templating.

keysToWrap: string[]

The particular keys to wrap. If left empty, all keys will be wrapped. Supports dot notation and text templating.

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-wrap": {
        "type": "wrap",
        "config": {
          "key": "payload"
        }
      }
    }
  }
}

Pipeline Filters

aggregate

This filter aggregates incoming data. On a defined interval or maximum data count, it will emit all aggregated advertisements. There are three modes in which this filter can operate: array, map, and mapArray.

In the array mode, the filter will aggregate all incoming messages into a single array.

In map mode, the filter will keep only the last message from each device.

In mapArray mode, the filter will keep all messages for each device as separate arrays of data keyed on all present devices.

Data is published from this filter either on a defined interval or when a specified maximum size is reached. At least one of these options must be specified in the configuration. If both are specified, whichever condition that occurs first will cause data to be published.

Outputs: All data which is kept will be passed through.

arrayMax: integer (int64) 500

Maximum length of the storage array. Only applies in array and mapArray modes.

arrayOutputKey: string "aggregate"

When in array mode, or map mode with convertMapToArray set to true, wrap the output array in this key.

convertMapToArray: boolean false

When in map mode, convert the output map into an array of the entries instead of a map. This allows for capturing one unique value per Key, but outputting them in array form.

debug: boolean false

Enable debug logging

deleteKey: boolean false

Deletes key from the aggregated object(s)

disableEmpty: boolean false

Disable emitting empty aggregates

interval: string

The interval specifies how often this filter should publish aggregated data. It is specified as a string of number plus unit. Valid units are s for seconds, m for minutes, and h for hours.

key: string mac

The key to use for aggregation in map modes. Used if map or mapArray mode are used.

mapMax: integer (int64) 20000

Maximum length of the storage map. Only applies to map and mapArray modes.

maxCount: integer (int64) 0

Maximum number of events to hold in the aggregator. Applies to all modes. If > 0, overrides mapMax and arrayMax. If <= 0 (default), mapMax and arrayMax will be used.

mode: string

The operation mode for the aggregate filter. The valid options are: array, map, and mapArray.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-agg": {
        "type": "aggregate",
        "config": {
          "arrayMax": 0,
          "disableEmpty": false,
          "interval": "25s",
          "key": "mac",
          "mapMax": 900,
          "maxCount": 0,
          "mode": "map"
        }
      }
    }
  }
}

connect

This filter triggers a BLE connection and a subsequent ConnectionSequence of Actions to be run.

Output: The event map emitted by the ConnectionSequence after it has run.

cacheGattDb: boolean false

Cache the GATT database of this device when true

debug: boolean false

Enable debug logging

id: string

The ID of the Connection Sequence that should be triggered every time this filter is reached

interval: string

The interval on which connection sequences should run. The minimum connection interval is a function of the connection timeout with a hard minimum of 1 minute. The connection interval cannot be less than 4 times the timeout. Setting an interval of 0 will enable on-demand connections. For example, to achieve a 1 minute connection interval, the timeout must be set to 15 seconds.

timeout: object 10

Set the length of time to wait for a successful connection in seconds.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-connect": {
        "type": "connect",
        "config": {
          "cacheGattDb": false,
          "id": "read-battery-life",
          "interval": "30m",
          "timeout": 20
        }
      }
    }
  }
}

discoverDevice

This filter adds any device that flows through it to a Device Group. See the documentation for Device Groups for more information.

If the deviceId field is in the input map, that value will be used as the unique ID of the device added. Otherwise, the Device Group's Device ID Template will be used. This defaults to the mac field, but can be templatized to extract other fields out of the event map or compute a deviceId.

If the field addDevices is present, then that is expected to be a list of device IDs to add, and deviceId is ignored. These must be exact device IDs, and are not fed through the Device Group's Device ID Template.

If the field replaceDevices is present, the devices in the device group are completely replaced with the members of the replaceDevices array. These must be exact device IDs, and are not fed through the Device Group's Device ID Template.

Output: Contains all keys from the input

debug: boolean false

Enable debug logging

groupId: string

The Device Group ID to add devices to

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "discover-for-my-group": {
        "type": "discoverDevice",
        "config": {
          "groupId": "my-ibeacons"
        }
      }
    }
  }
}

eddystone

This filter processes Eddystone based beacon data. It handles processing URL, URI, and TLM Eddystone payloads. Each type of Eddystone data is treated as a separate advertising payload.

Output: All available Eddystone fields are emitted from this filter as well as mac address and RSSI.

No configuration is required for this filter.

debug: boolean false

Enable debug logging

ignoreEID: boolean false

Ignore EID advertising payloads

ignoreTLM: boolean false

Ignore TLM advertising payloads

ignoreUID: boolean false

Ignore UID advertising payloads

ignoreURL: boolean false

Ignore URL advertising payloads

passthrough: boolean false

Passthrough non-eddystone events

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-eddy": {
        "type": "eddystone",
        "config": {
          "ignoreURL": true
        }
      }
    }
  }
}

enocean

This filter parses enocean sensor data to a map

Output: The filter outputs all available data from the enabled enocean sensors and adds the mac address and rssi of the tag.

debug: boolean false

Enable debug logging

types: string[]

Enabled Sensor Types (available: emdcb, emswb)

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-enocean": {
        "type": "enocean",
        "config": {
          "types": [
            "emdcb",
            "emswb"
          ]
        }
      }
    }
  }
}

fwupdate

Update firmware on a device.

Supported Modes: thingsee (based on nordic) default activation via write 0xff -> f26fb784a2ae54c9b4c6950714c9789e/f26f7fffa2ae54c9b4c6950714c9789e. nordic (nordic bootloader) default activation via nordic buttonless dfu service

A fwupdate operation has the following steps:

  • match target device (via target, or thingsee filter)
  • connect and run activation connection sequence
  • disconnect
  • post activation delay
  • connect and run updater connection sequence
  • disconnect
activationDisable: boolean false

Disable activation sequence

activationSequence: string none, will use default for `type`

Custom activation sequence id

activationTimeout: string 30s

Set activation connection timeout

debug: boolean false

Enable debug logging

firmwareBytes: string

Select source of the firmware bytes (must be template)

postActivationDelay: string 500ms

Set post activation delay

target: MatcherSet
type: string thingsee

DFU type set the dfu type

updaterTimeout: string 30s

Set updater connection timeout

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-fwupdate": {
        "type": "fwupdate"
      }
    }
  }
}

ibeacon

This filter parses iBeacon payloads and outputs all available iBeacon fields.

Output: All available iBeacon fields and their values.

debug: boolean false

Enable debug logging

passthrough: boolean false

Passthrough non-iBeacon events

uuidFilter: string

If specified, only iBeacon UUIDs which pass the filter will be processed further. This filter is specified as a regular expression.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-ibeacon": {
        "type": "ibeacon",
        "config": {
          "uuidFilter": "aabbccddeeff1122334455667788990[123]"
        }
      }
    }
  }
}

isensor

This filter parses door sensor data from the iSensor brand door open/closed sensor.

Output: The current state of the sensor along with mac address, RSSI, and manufacturer id. The fields are keyed as mac, rssi, mfgid, and open. If open is true, the door is open.

No configuration is required for this filter.

debug: boolean false

Enable debug logging

devices: string[]

Defines a list of MFG IDs from which data should be collected. This list is added to the built in list. The IDs are specified as uint16 values in big-endian string hex format

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-isensor": {
        "type": "isensor",
        "config": {
          "devices": [
            "1095"
          ]
        }
      }
    }
  }
}

iterator

This filter iterates through an aggregate and outputs the input map with the iterated value injected into item.value and item.id (key or idx).

Supported aggregate types: []interface{} map[string]interface{}

debug: boolean false

Enable debug logging

forEach: string[]

ForEach can be used to modify every element in an iterable, rather than split it (the default behavior). If forEach is set, the filters listed in forEach will be run on each element of the iterable, rather than emitting each element as a new event.

string
key: string

The key containing the values to iterate over Supports dot notation and text templating.

max: integer (int64) 1000

Maximum number of items to emit from iteration

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "iterate-array": {
        "type": "iterator",
        "config": {
          "key": "arrayOfThings",
          "max": 0
        }
      }
    }
  }
}

minew

This filter parses minew sensor data to a map

Output: The filter outputs all available data from the enabled minew sensors and adds the mac address and rssi of the tag.

debug: boolean false

Enable debug logging

types: string[]

Enabled Sensor Types (available: s1,e6)

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-minew": {
        "type": "minew",
        "config": {
          "types": [
            "s1"
          ]
        }
      }
    }
  }
}

occupancy

This filter provides occupancy state messages from a Haltian Thingsee BLE occupancy sensor. There are 2 versions of the thingsee firmware (v1, v2) which determine how occupancy state is calculated.

The v1 sensor has one counter that increments everytime movement is detected, on overflow the count is reset to zero. In raw mode, the output contains the mac address, RSSI, and the count value from the device. In regular mode, the output replaces the count with state where true signifies occupied.

The v2 sensor is interval based and provides a motion count over the last 10 intervals with an incrementing interval counter. There is only one mode for handling v2 sensors.

v2 occupancy state is calculated by summing motion counts from the last N intervals (un/occupiedCount). If the sum is equal or greater than the threshold (un/OccupiedThreshold) the state will be changed accordingly with the occupied state taking precedence in a tie. Using the interval counter, incoming data is aligned with the history in the occupancy filter.

v2 output includes: occupied: true/false occupied state history: counts from the last historyCount intervals, -1 is empty lastSeen: last time sensor was seen lastChanged: last time sensor changed occupied state batteryLevel: battery level in % fwVersion: firmware version interval: interval length in seconds counter: incrementing interval counter

Output: see above

debug: boolean false

Enable debug logging

historyLength: integer (int64) 120

History length (in intervals) (v2 only)

mode: string regular

The mode in which to operate (v1 only). Options are 'regular' and 'raw'.

occupiedCount: integer (int64) 3

Number of intervals to sum the occupied count over (>0) (v2 only)

occupiedThreshold: integer (int64) 3

Threshold for occupied count to trigger occupied state (>0) (v2 only)

outputHistory: boolean false

Output history (v2 only)

unoccupiedCount: integer (int64) 12

Number of intervals to sum the unoccupied count over (>0) (v2 only)

unoccupiedThreshold: integer (int64) 1

Threshold for unoccupied count to trigger unoccupied state (>0) (v2 only)

updateIntervalSec: integer (int64) 600

Update interval in seconds if there is no state change (>=0, 0=always update) (v2 only)

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-occ": {
        "type": "occupancy",
        "config": {
          "mode": "raw"
        }
      }
    }
  }
}

removeDevice

This filter removes any device that flows through it from a Device Group. See the documentation for Device Groups for more information.

If the deviceId field is in the input map, that value will be used as the unique ID of the device added. Otherwise, the Device Group's Device ID Template will be used. This defaults to the mac field, but can be templatized to extract other fields out of the event map or compute a deviceId.

If the field removeDevices is present, then that is expected to be a list of device IDs to remove, and deviceId is ignored. These must be exact device IDs, and are not fed through the Device Group's Device ID Template.

Output: Contains all keys from the input

debug: boolean false

Enable debug logging

groupId: string

The Device Group ID to add devices to

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "remove-from-my-group": {
        "type": "removeDevice",
        "config": {
          "groupId": "my-ibeacons"
        }
      }
    }
  }
}

ruuvi

This filter parses Ruuvi Tag broadcasts that send out Ruuvi v3 and v5 custom formats. The available data fields are: temperature, pressure, humidity, accelerometer, battery, tx power, movement count, and sequence number.

Output: The filter outputs all available data from the Ruuvi tag and adds the mac address and rssi of the tag.

No configuration is required for this filter.

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "my-ruuvi": {
        "type": "ruuvi"
      }
    }
  }
}

throttle

This filter throttles emission of events by counter or timeout. Events are identified by the key specified in the configuration

In counter mode: Every N-th event matching the id will be emitted (where N = count).

In timeout mode: An event will be emitted if the timeout has elapsed since the last event emitted matching the id. There is no caching of the input events, if no new event is processed, no event will be emitted when the timeout has elapsed.

Output: If unthrottled: a copy of the input event If throttled: nil

count: integer (int64)

Throttle with a counter

debug: boolean false

Enable debug logging

key: string "mac"

Keys to throttle on

maxCount: integer (int64) 1000

Maximum number of id's to track, after hitting this limit, unknown id's will be ignored.

timeout: string

Throttle with a timeout

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "send-every-30s": {
        "type": "throttle",
        "config": {
          "key": "mac",
          "timeout": "30s"
        }
      }
    }
  }
}