Pipeline Components
Use these components to build your Pipelines and Connection Sequences
Pipeline Filters
aggregate
aggregate
Pipeline Filter
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
arrayMax | integer | Maximum length of the storage array. Only applies in array and mapArray modes. Example: 33 | No |
arrayOutputKey | string | When in array mode, or map mode with convertMapToArray set to true, wrap the output array in this key. Example: "myItems" | No |
convertMapToArray | boolean | 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. Example: true | No |
deleteKey | boolean | Deletes key from the aggregated object(s) | No |
disableEmpty | boolean | Disable emitting empty aggregates Example: true | No |
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. Example: "10s" | No |
joinMaps | boolean | Join maps in map mode. If true, joins the current event with the previous event for a device. | No |
key | string | The key to use for aggregation in map modes. Used if map or mapArray mode are used. Example: "mac" | No |
mapMax | integer | Maximum length of the storage map. Only applies to map and mapArray modes. Example: 42 | No |
maxCount | integer | 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. Example: 5000 | No |
mode | string | The operation mode for the aggregate filter. The valid options are: array, map, and mapArray. Example: "map" | No |
Example
{
"service": {
"filters": {
"my-agg": {
"config": {
"arrayMax": 0,
"disableEmpty": false,
"interval": "25s",
"key": "mac",
"mapMax": 900,
"maxCount": 0,
"mode": "map"
},
"type": "aggregate"
}
}
}
}
chunk
chunk
Pipeline Filter
This filter iterates through an aggregate and breaks it into chunks of N items.
If key is non-empty (the aggregate is nested), the emitted events will be the input event with
the aggregate value replaced with a chunked aggregate.
Supported aggregate types:
[]any
[]map[string]any
map[string]any
Fields
Name | Type | Description | Required |
---|---|---|---|
key | string ✅ templating ✅ dot notation | The key containing the values to chunk, if blank the whole event map will be chunked. | Yes |
size | int64 ✅ templating | Maximum number of items to emit in each chunk | Yes |
Example
{
"service": {
"filters": {
"25-chunker": {
"config": {
"key": "values",
"size": 25
},
"type": "chunk"
}
}
}
}
connect
connect
Pipeline Filter
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
cacheGattDb | boolean | Cache the GATT database of this device when true Example: true | No |
id | string | The ID of the Connection Sequence that should be triggered every time this filter is reached Example: "read-battery-life" | Yes |
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. Example: "30m" | Yes |
timeout | ? | Set the length of time to wait for a successful connection in seconds. Example: "20" | No |
Example
{
"service": {
"filters": {
"my-connect": {
"config": {
"cacheGattDb": false,
"id": "read-battery-life",
"interval": "30m",
"timeout": 20
},
"type": "connect"
}
}
}
}
deviceGroupIterator
deviceGroupIterator
Pipeline Filter
This filter iterates through members of a device group and outputs
a new event for each device consisting of the input map with the
Device ID for each device injected into item.deviceId
.
Using this filter will essentially cause a pipeline to fan-out and execute
the following steps in the pipeline for each device in the specified device group.
Fields
Name | Type | Description | Required |
---|---|---|---|
groups | stringArray | The device group(s) to iterate over. Can be a single Device Group ID (string) or an array of Device Group IDs. | Yes |
includeAbsentDevices | bool | Also include devices that are not currently "present" but are members of the device group | No |
Example
{
"service": {
"filters": {
"iterate-array": {
"config": {
"groups": "my-devices"
},
"type": "deviceGroupIterator"
}
}
}
}
discoverDevice
discoverDevice
Pipeline Filter
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
Fields
Name | Type | Description | Required |
---|---|---|---|
groupId | string ✅ templating | The ID of the Device Group for which you want to change membership. Example: "my-ibeacons" | Yes |
Example
{
"service": {
"filters": {
"discover-for-my-group": {
"config": {
"groupId": "my-ibeacons"
},
"type": "discoverDevice"
}
}
}
}
eddystone
eddystone
Pipeline Filter
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
ignoreEID | boolean | Ignore EID advertising payloads | No |
ignoreTLM | boolean | Ignore TLM advertising payloads | No |
ignoreUID | boolean | Ignore UID advertising payloads | No |
ignoreURL | boolean | Ignore URL advertising payloads | No |
passthrough | boolean | Passthrough non-eddystone events | No |
Example
{
"service": {
"filters": {
"my-eddy": {
"config": {
"ignoreURL": true
},
"type": "eddystone"
}
}
}
}
enocean
enocean
Pipeline Filter
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
types | array | Enabled Sensor Types (available: emdcb, emswb) Example: [ "emdcb"] | No |
Example
{
"service": {
"filters": {
"my-enocean": {
"config": {
"types": [
"emdcb",
"emswb"
]
},
"type": "enocean"
}
}
}
}
fwupdate
fwupdate
Pipeline Filter
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
Fields
Name | Type | Description | Required |
---|---|---|---|
activationDisable | boolean | Disable activation sequence | No |
activationSequence | string | Custom activation sequence id | No |
activationTimeout | positiveDuration | Set activation connection timeout | No |
firmwareBytes | string | Select source of the firmware bytes (must be template) Example: "{{ .keyWithFirmwareBytes }}" | Yes |
postActivationDelay | positiveDuration | Set post activation delay | No |
target | MatcherConfig | No | |
type | string | DFU type set the dfu type Example: "nordic" | No |
updaterTimeout | positiveDuration | Set updater connection timeout | No |
Example
{
"service": {
"filters": {
"my-fwupdate": {
"type": "fwupdate"
}
}
}
}
ibeacon
ibeacon
Pipeline Filter
This filter parses iBeacon payloads and outputs
all available iBeacon fields.
Output: All available iBeacon fields and their values.
Fields
Name | Type | Description | Required |
---|---|---|---|
passthrough | boolean | Passthrough non-iBeacon events | No |
uuidFilter | string | If specified, only iBeacon UUIDs which pass the filter will be processed further. This filter is specified as a regular expression. Example: "aabbccddeeff1122334455667788990[123]" | No |
Example
{
"service": {
"filters": {
"my-ibeacon": {
"config": {
"uuidFilter": "aabbccddeeff1122334455667788990[123]"
},
"type": "ibeacon"
}
}
}
}
isensor
isensor
Pipeline Filter
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
devices | array | 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 Example: "\"1095\"" | No |
Example
{
"service": {
"filters": {
"my-isensor": {
"config": {
"devices": [
"1095"
]
},
"type": "isensor"
}
}
}
}
iterator
iterator
Pipeline Filter
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{}
Fields
Name | Type | Description | Required |
---|---|---|---|
forEach | array | 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. | No |
key | string ✅ templating ✅ dot notation | The key containing the values to iterate over | Yes |
max | integer | Maximum number of items to emit from iteration | No |
Example
{
"service": {
"filters": {
"iterate-array": {
"config": {
"key": "arrayOfThings",
"max": 0
},
"type": "iterator"
}
}
}
}
minew
minew
Pipeline Filter
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
authKey | string | Authentication Key for authenticated S1 payloads | No |
types | array | Enabled Sensor Types (available: s1,e6) Example: [ "s1"] | No |
Example
{
"service": {
"filters": {
"my-minew": {
"config": {
"types": [
"s1"
]
},
"type": "minew"
}
}
}
}
occupancy
occupancy
Pipeline Filter
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
wheretrue
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 statehistory
: counts from the lasthistoryCount
intervals, -1 is emptylastSeen
: last time sensor was seenlastChanged
: last time sensor changedoccupied
statebatteryLevel
: battery level in %fwVersion
: firmware versioninterval
: interval length in secondscounter
: incrementing interval counter
Output: see above
Fields
Name | Type | Description | Required |
---|---|---|---|
historyLength | integer | History length (in intervals) (v2 only) | No |
mode | string | The mode in which to operate (v1 only). Options are 'regular' and 'raw'. Example: "raw" | No |
occupiedCount | integer | Number of intervals to sum the occupied count over (>0) (v2 only) | No |
occupiedThreshold | integer | Threshold for occupied count to trigger occupied state (>0) (v2 only) | No |
outputHistory | boolean | Output history (v2 only) | No |
unoccupiedCount | integer | Number of intervals to sum the unoccupied count over (>0) (v2 only) | No |
unoccupiedThreshold | integer | Threshold for unoccupied count to trigger unoccupied state (>0) (v2 only) | No |
updateIntervalSec | integer | Update interval in seconds if there is no state change (>=0, 0=always update) (v2 only) | No |
Example
{
"service": {
"filters": {
"my-occ": {
"config": {
"mode": "raw"
},
"type": "occupancy"
}
}
}
}
removeDevice
removeDevice
Pipeline Filter
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
Fields
Name | Type | Description | Required |
---|---|---|---|
groupId | string ✅ templating | The ID of the Device Group for which you want to change membership. Example: "my-ibeacons" | Yes |
Example
{
"service": {
"filters": {
"remove-from-my-group": {
"config": {
"groupId": "my-ibeacons"
},
"type": "removeDevice"
}
}
}
}
ruuvi
ruuvi
Pipeline Filter
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.
Example
{
"service": {
"filters": {
"my-ruuvi": {
"type": "ruuvi"
}
}
}
}
throttle
throttle
Pipeline Filter
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
Fields
Name | Type | Description | Required |
---|---|---|---|
count | integer | Throttle with a counter Example: 10 | No |
ignoreFirstEvent | boolean | Ignore the first event, regardless of count/timeout - wait until count/timeout is reached before emitting. | No |
key | string | Keys to throttle on | No |
maxCount | integer | Maximum number of id's to track, after hitting this limit, unknown id's will be ignored. | No |
timeout | positiveDuration | Throttle with a timeout | No |
Example
{
"service": {
"filters": {
"send-every-30s": {
"config": {
"key": "mac",
"timeout": 30000000000
},
"type": "throttle"
}
}
}
}
Use as Filter or Action
append
append
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
array | string ✅ templating ✅ dot notation | The key of the array to append the item to. Example: "item" | Yes |
deleteItem | boolean | If true, delete the original item key/value after appending to the array. Example: false | No |
item | string ✅ templating ✅ dot notation | The key of the item to append to the array. Example: "item" | Yes |
Example
{
"service": {
"filters": {
"my-append": {
"config": {
"array": "array",
"item": "item"
},
"type": "append"
}
}
}
}
cipherDecrypt
cipherDecrypt
Pipeline FilterConnection Action
Decrypts encrypted data in the input
into decrypted bytes stored in the output
key. If decryption fails or the input
is invalid, the filter will error and execution will not proceed.
Fields
Name | Type | Description | Required |
---|---|---|---|
additionalData | bytes ✅ templating | Additional data bytes - only used with AEAD ciphers | No |
cipher | string ✅ templating | Cipher name and mode supported: - aes-ecb - aes-cbc (requires IV) - aes-ctr (requires IV) - aes-cfb (requires IV) - aes-ofb (requires IV) - aes-gcm (AEAD) - aes-eax (AEAD) | Yes |
input | bytes ✅ templating | Input bytes - encrypt: the un-encrypted bytes, decrypt: the encrypted bytes | Yes |
iv | bytes ✅ templating | Initialization vector bytes - only used with ciphers that require an IV | No |
key | bytes ✅ templating | Cipher key bytes | Yes |
keystoreInput | KeystoreKey | Input bytes from keystore - encrypt only | No |
keystoreKey | string | name of key in the keystore Example: "myKey" | Yes |
nonce | bytes ✅ templating | Nonce bytes - only used with AEAD ciphers | No |
output | string ✅ templating | Key to output the result of the operation in the event map | No |
publicKey | boolean | if using a keypair, use the public key? Example: true | No |
Example
{
"service": {
"filters": {
"decrypter": {
"config": {
"additionalData": null,
"cipher": "aes",
"input": "{{.ciphertext}}",
"iv": null,
"key": "{{.key}}",
"nonce": null,
"output": "plaintext"
},
"type": "cipherDecrypt"
}
}
}
}
cipherEncrypt
cipherEncrypt
Pipeline FilterConnection Action
Encrypts data in the input
into encrypted bytes stored in the output
key. If encryption fails or the input
is invalid, the filter will error and execution will not proceed.
Fields
Name | Type | Description | Required |
---|---|---|---|
additionalData | bytes ✅ templating | Additional data bytes - only used with AEAD ciphers | No |
cipher | string ✅ templating | Cipher name and mode supported: - aes-ecb - aes-cbc (requires IV) - aes-ctr (requires IV) - aes-cfb (requires IV) - aes-ofb (requires IV) - aes-gcm (AEAD) - aes-eax (AEAD) | Yes |
input | bytes ✅ templating | Input bytes - encrypt: the un-encrypted bytes, decrypt: the encrypted bytes | Yes |
iv | bytes ✅ templating | Initialization vector bytes - only used with ciphers that require an IV | No |
key | bytes ✅ templating | Cipher key bytes | Yes |
keystoreInput | KeystoreKey | Input bytes from keystore - encrypt only | No |
keystoreKey | string | name of key in the keystore Example: "myKey" | Yes |
nonce | bytes ✅ templating | Nonce bytes - only used with AEAD ciphers | No |
output | string ✅ templating | Key to output the result of the operation in the event map | No |
publicKey | boolean | if using a keypair, use the public key? Example: true | No |
Example
{
"service": {
"filters": {
"encrypter": {
"config": {
"additionalData": null,
"cipher": "aes",
"input": "{{.plaintext}}",
"iv": null,
"key": "{{.key}}",
"nonce": null,
"output": "ciphertext"
},
"type": "cipherEncrypt"
}
}
}
}
decodeLTV
decodeLTV
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
dataKey | string | The key to read the data from. | No |
lengthInclusive | boolean | LengthInclusive describes whether the length includes the length byte itself | No |
outputKey | string | The key to store decoded data in | No |
typeInclusive | boolean | TypeInclusive describes whether the length includes the type byte | No |
types | map of string to EncodedLTV | A map of friendly names to EncodedType descriptions of the types that appear in the data. | Yes |
Example
{
"service": {
"filters": {
"decode-my-data": {
"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
}
}
},
"type": "decodeLTV"
}
}
}
}
decodeType
decodeType
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
dataKey | string | The key to read the data from. | No |
outputKey | string | The key to store decoded data in | No |
outputMap | boolean | If set to true, the object(s) that are decoded will be merged into one output map, rather than appended to an array. | No |
type | EncodedType | Yes |
Example
{
"service": {
"filters": {
"decode-my-fixed-data": {
"config": {
"dataKey": "data",
"outputKey": "decoded",
"type": {
"fields": [
{
"key": "serialNumber",
"length": 4,
"type": "intLE"
},
{
"key": "deviceName",
"length": 16,
"type": "string"
}
]
}
},
"type": "decodeType"
}
}
}
}
delete
delete
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
keys | array | Keys to delete | Yes |
Example
{
"service": {
"filters": {
"delete-bad-keys": {
"config": {
"keys": [
"extraneous-key",
"and-another-one-too"
]
},
"type": "delete"
}
}
}
}
deviceReport
deviceReport
Pipeline FilterConnection Action
This filter fetches information about devices in device groups and seen nearby.
Fields
Name | Type | Description | Required |
---|---|---|---|
groups | stringArray ✅ templating | Restrict report to only these device groups. If empty all device groups will be reported including devices that have been detected but that are not in groups. Can be a device group ID (string), regular expression (string starting with ^ or ending with $) or an array of device group IDs or regular expressions | No |
includeProps | bool ✅ templating | Include the props for each device in the report. This has performance impact, especially for persistent props. Props are include in each device in the props key. | No |
includeUnknownDevices | bool ✅ templating | Includes devices that don't match a declared device type and aren't in a device group.They are not included by default. | No |
outputAsArray | bool ✅ templating | Output report as an array instead of a map? | No |
outputKey | string ✅ templating ✅ dot notation | Output key for report | No |
Example
{
"service": {
"filters": {
"dg-info-all": {
"config": {
"groups": "^.*\\.provisioned",
"outputAsArray": true,
"outputKey": "provisionedDevices"
},
"type": "deviceReport"
}
}
}
}
emitEvent
emitEvent
Pipeline FilterConnection Action
This filter is used to emit a new user defined event to feed back into pipeline processing.
The new emitted event can then be matched to pipelines based on the eventType
.
The current pipeline that contains this filter will continue execution with the unchanged input event.
Fields
Name | Type | Description | Required |
---|---|---|---|
eventType | string | Define the emitted event type. Example: "ovenPreheated" | Yes |
payloadKey | string ✅ templating ✅ dot notation | Define the payload key in the current event to emit in the new event. The key must contain a value of type map[string]interface{} to be emitted. + If payloadKey is empty, the whole event map will be emitted in the new event. + If an error is encountered (bad key, type, template error), no new event is emitted. Example: "oven.status" | No |
Example
{
"service": {
"filters": {
"oven-preheated-notifier": {
"config": {
"eventType": "ovenPreheated",
"payloadKey": "oven.status"
},
"type": "emitEvent"
}
}
}
}
hash
hash
Pipeline FilterConnection Action
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)
Fields
Name | Type | Description | Required |
---|---|---|---|
algorithm | string | Set hash algorithm Example: "md5" | Yes |
append | boolean | Enable append mode | No |
compute | boolean | Enable compute mode | No |
expect | string ✅ templating | Enable expect mode | No |
hashBytesBigEndian | boolean | Handle hash array as big endian | No |
hashStringBigEndian | boolean | Handle hash strings as big endian Default is false for all algorithms except crc16 | No |
hmac | boolean | enable HMAC mode | No |
hmacKey | string ✅ templating | Set the HMAC key (supports template, hexstring or base64) Must be set if hmac == true and hmacKeystoreKey is not set Example: "{{ .key }}" | No |
hmacKeystoreKey | string | Set the HMAC key from a secret from the keystore (secret must be []byte or a hex/base64 string) Example: "mySecretKey" | No |
inputKey | string ✅ templating ✅ dot notation | Define the input key | Yes |
outputKey | string ✅ templating ✅ dot notation | Define the output key | Yes |
outputSize | integer | 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 Example: 16 | No |
verify | boolean | Enable verify mode (assumes input has hash appended) | No |
Example
{
"service": {
"filters": {
"decode-resp": {
"config": {
"algorithm": "crc16-ccitt-false",
"append": false,
"compute": false,
"inputKey": "dataToVerify",
"outputKey": "data",
"verify": true
},
"type": "hash"
}
}
}
}
history
history
Pipeline FilterConnection Action
This filter collects historical values for a device.
Events for a device are identified by the key
specified in the configuration.
The value for an event is determined by the value
template.
The history filter will emit a history event (device event with history added in (optional)) if the condition
evaluates to true.
The options for condition
are:
always
(default) returns true.change
returns true if the device event yields a value that is not the same as the previous value, a history event will be emitted.threshold
returns true if the device event yields a value that exceeds any defined threshold.thresholdZone
returns true if the device event yields a value that exits a device's threshold zone.
A custom condition
can be defined with a template which produces a value that can be converted to a boolean.
The history data for the device can be accessed via the following keys in the template:
.__history
([]interface{}) history values (including current value) sorted by ascending time.__historyCurrent
(interface{}) the current value.__historyPrevious
(interface{}) the previous value
threshold
/ thresholdZone
conditions can define high and low thresholds and hysteresis.
The threshold zones are the following:
unknown
new deviceok
no threshold exceeded.low
low threshold has been exceeded, and value has not increased above the low hysteresis value.high
high threshold has been exceeded, and value has not decreased below the high hysteresis value.
The threshold hysteresis values are used to debounce the threshold zone transitions, note that the hysteresis values default to 0.
To exit a threshold exceeded zone, the current value must meet the following criteria:
high
v < (thresholdHigh - thresholdHysteresisHigh)low
v > (thresholdLow + thresholdHysteresisLow)
Output:
If condition
evaluates to:
error
nilfalse
niltrue
the input event with the history ([]interface{}) stored inoutputKey
Fields
Name | Type | Description | Required |
---|---|---|---|
condition | string ✅ templating | Set the condition to determine when an event will be emitted for a device.options: always, condition, template (see overview) Example: "{{ gt .__historyCurrent .__historyPrevious }} (notify when the current \u003e previous)" | No |
deviceId | string ✅ templating | DeviceId to uniquely identify device | No |
historyCount | integer | Set history length by count. If the limit is reached, old values will be replaced by new values. note: if used with historyDuration , sets max number of history values saved over the duration, will default.if used without historyDuration , sets max number of history values, will not default Example: 10 | No |
historyDuration | positiveDuration ✅ templating | Set history length by duration string (also see historyCount ) | No |
historyTimeout | positiveDuration ✅ templating | History timeout which will enable reporting history at an interval if condition is not matched.If set, the historyStateChanged key will be added to the history output which will be set to true when condition is matched, and false when a history timeout occurs. | No |
maxDeviceCount | integer | Maximum number of unique devices to track. Once the limit is reached, the oldest devices will be replaced by new devices | No |
omitHistory | boolean | Omit history data when emitting history event (passthrough device event only) | No |
outputKey | string ✅ templating | Key to output history in event map | No |
thresholdHigh | number | Threshold values for threshold condition, one or both must be defined when threshold condition is selected. If the value from a device event exceeds either of these thresholds a device history event will be emitted Example: 12.34 | No |
thresholdHysteresisHigh | number | No | |
thresholdHysteresisLow | number | Threshold hysteresis values. Example: 1.5 | No |
thresholdLow | number | No | |
value | string ✅ templating ✅ dot notation | Value to track history for Example: "rssi" | Yes |
Example
{
"service": {
"filters": {
"rssi-changed": {
"config": {
"condition": "change",
"deviceId": "mac",
"historyCount": 10,
"historyDuration": 60000000000,
"value": "{{.rssi}}"
},
"type": "history"
}
}
}
}
httpFetch
httpFetch
Pipeline FilterConnection Action
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
Fields
Name | Type | Description | Required |
---|---|---|---|
body | string ✅ templating | The HTTP body to use in the request If the template returns a []byte value, the raw []byte is used as the HTTP request body. If the template returns a non-[]byte value, the non-[]byte value is encoded by the bodyFormatter to produce the HTTP request body. Example: "{{ .body }}" | No |
bodyFormatter | string | The formatter used to encode the HTTP request body. Available options: json, jsongz, base64json, cbor Example: "cbor" | No |
ca | string | Additional CAs to append to system certpool CA certs must be base64 encoded pem format | No |
cacheMaxItems | integer | Max Cache size in items | No |
contentTypeOutputKey | string ✅ templating | Defines the output key for the HTTP response Content-Type in the event map. Example: "contentType" | No |
headers | object ✅ templating | 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. | No |
interval | string | 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. | No |
method | string ✅ templating | The HTTP method, can be GET , POST , PUT Example: "POST" | No |
outputKey | string ✅ templating | Defines the output key for the HTTP response body in the event map. | No |
passthroughHTTPError | boolean | Emit an event when an HTTP response contains a non-successful HTTP status (see successStatuses). note: all other errors will cause a nil event to be emitted (server unreachable, etc). | No |
persistent | boolean | Enable persistent cache | No |
statusKey | string ✅ templating | Defines the output key for the HTTP status code in the event map | No |
successfulStatuses | array | Define the httpStatus codes that are considered successful. A response will only be cached if the status code is in this list. | No |
timeout | positiveDuration ✅ templating | HTTP request timeout (duration string) | No |
url | string ✅ templating | The HTTP url to send data Example: "https://myserver.net/data" | Yes |
Example
{
"service": {
"filters": {
"httpGet": {
"config": {
"headers": {
"AuthToken": "something-secret"
},
"interval": "25s",
"outputKey": "my-output-key",
"url": "https://myserver.net/data"
},
"type": "httpFetch"
}
}
}
}
inject
inject
Pipeline FilterConnection Action
This filter injects keys into the output event map. The injected keys are specified
as key/value pairs using the top level keyPairs
parameter.
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 secondsms
: epoch millisecondsus
: epoch microsecondsns
: 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 stringUnixDate
: Unix date string
Output: Contains all keys from the input and the injected keys.
Fields
Name | Type | Description | Required |
---|---|---|---|
keyPairs | object ✅ templating ✅ dot notation | Defines a set of keys and values to add to the event map output. | No |
replaceExisting | boolean | Replace key value pairs that already exist, instead of ignoring them | No |
Example
{
"service": {
"filters": {
"my-inject": {
"config": {
"keyPairs": {
"customSerialUnderscoreMac": "{{ .serial }}_{{ .mac }}}",
"my-key": "my-value",
"serial": ""
}
},
"type": "inject"
}
}
}
}
keystoreDelete
keystoreDelete
Pipeline FilterConnection Action
This filter deletes keys that have been defined in the keystore
Output:
The output event is the same as the input event on success, nil on error.
Fields
Name | Type | Description | Required |
---|---|---|---|
keystoreKey | string | Keystore key to operate on, must be pre-defined in the keystore | Yes |
Example
{
"service": {
"filters": {
"delete-key": {
"config": {
"keystoreKey": "myKey"
},
"type": "keystoreDelete"
}
}
}
}
keystoreSet
keystoreSet
Pipeline FilterConnection Action
This filter sets keys that have been defined in the keystore
Output:
The output event is the same as the input event on success, nil on error.
Fields
Example
{
"service": {
"filters": {
"set-keypair": {
"config": {
"keystoreKey": "myKeypair",
"setPrivateKey": "{{.prv}}",
"setPublicKey": "{{.pub}}"
},
"type": "keystoreSet"
}
}
}
}
matcher
matcher
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
match | ? | Keys to match (all keys) for an inline definition (see MatcherDefinition ), or a Template to evaluate and match to a true value. | No |
matchAny | boolean | Should we match any of the provided matchers (true)? Or all of the matchers (false) | No |
matchers | array | The list of top-level matcher IDs to apply to the input map Example: [ "is-nearby", "is-my-device-type"] | No |
Example
{
"service": {
"filters": {
"my-matcher": {
"config": {
"match": {
"key1": [
"thisValue",
"orThisValue"
],
"key2": "onlyThisValue"
},
"matchers": [
"match-command1",
"match-command2"
]
},
"type": "matcher"
}
}
}
}
metadataClear
metadataClear
Pipeline FilterConnection Action
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
Fields
Name | Type | Description | Required |
---|---|---|---|
allDevices | boolean | Perform device metadata operations on all devices? | No |
global | boolean | Perform global metadata operations? | No |
keys | array | The metadata keys to delete, all keys are deleted if empty | No |
Example
{
"service": {
"filters": {
"clear-batt-metadata": {
"config": {
"keys": [
"batteryLevel"
]
},
"type": "metadataClear"
}
}
}
}
metadataGet
metadataGet
Pipeline FilterConnection Action
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
Fields
Name | Type | Description | Required |
---|---|---|---|
global | boolean | Perform global metadata operations? | Yes |
keys | array | The metadata data keys to add, all keys are added to the input map if empty. | No |
Example
{
"service": {
"filters": {
"add-batt-metadata": {
"config": {
"keys": [
"batteryLevel"
]
},
"type": "metadataGet"
}
}
}
}
metadataSet
metadataSet
Pipeline FilterConnection Action
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
Fields
Name | Type | Description | Required |
---|---|---|---|
global | boolean | Perform global metadata operations? | Yes |
keys | array | The metadata keys to filter on for a given device, all keys are used if empty | No |
Example
{
"service": {
"filters": {
"store-batt-metadata": {
"config": {
"keys": [
"batteryLevel"
]
},
"type": "metadataSet"
}
}
}
}
ntp
ntp
Pipeline FilterConnection Action
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
Fields
Name | Type | Description | Required |
---|---|---|---|
getHistory | boolean | Add ntp sync history for the history window to input event? | No |
getLastSuccess | boolean | Add last successful ntp sync into input event? | No |
getMaxOffset | boolean | Add maximum clock offset from history window to input event? | No |
historyWindow | string | How far back to look in the NTP sync history when processing an event historyCount = (historyWindow/syncInterval) + 1 historyCount must be <= 1000 | No |
host | string | Which NTP server to query | No |
syncInterval | string | NTP server query interval | No |
Example
{
"service": {
"filters": {
"ntp-monitor": {
"config": {
"getMaxOffset": true,
"historyWindow": "30m",
"host": "time.google.com",
"syncInterval": "30s"
},
"type": "ntp"
}
}
}
}
propSet
propSet
Pipeline FilterConnection Action
Sets props on the current Device. These props must either be defined in the DeviceType for this device, or the
DeviceType must support unknown props. See DeviceType
for more details. To fetch these props, use the Device.Props
template function.
Fields
Name | Type | Description | Required |
---|---|---|---|
keyPairs | object ✅ templating ✅ dot notation | Defines a set of keys and values to set in the Device Props. | No |
Example
{
"service": {
"filters": {
"set-the-props": {
"config": {
"keyPairs": {
"location": "upstairs",
"room": "kitchen",
"serial": 12345
}
},
"type": "propSet"
}
}
}
}
publish
publish
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
attempts | integer | How many attempts to make when publishing a payload. Will only attempt more than once when a retryable error is returned. | No |
connector | string | ID of the Cloud Connector to publish to, defined in the Cloud Connectors Config. Example: "my-azure" | Yes |
format | string | The format of the data to publish. Supported options are json and cbor . Example: "json" | No |
maxPayloadSize | integer | Maximum payload size, if <= 0 there is no limit. | No |
payloadKey | string | The key of the payload to send. If left empty, the whole event map is sent. | No |
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. | No |
retryDelay | positiveDuration ✅ templating | How long to wait before attempting a retry | No |
timeout | positiveDuration ✅ templating | Timeout for publishing (negative for no timeout) | No |
topic | string ✅ templating | The topic on which to publish outgoing messages. | No |
Example
{
"service": {
"filters": {
"publishPayload": {
"config": {
"connector": "my-cloud",
"payloadKey": "payload",
"topic": "my-topic"
},
"type": "publish"
}
}
}
}
reduce
reduce
Pipeline FilterConnection Action
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
Fields
Name | Type | Description | Required |
---|---|---|---|
key | string ✅ templating ✅ dot notation | 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. Example: "myAggregatedValues" | No |
values | map of string to ReduceConfig | 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 . Example: { "max-rssi": { "reduce": "{{ maxf .__items}}", "value": "{{.rssi}}" }} | Yes |
Example
{
"service": {
"filters": {
"rssi-calculations": {
"config": {
"values": {
"average-rssi": {
"reduce": "{{ meanf .__items }}",
"value": "{{ .rssi }}"
}
}
},
"type": "reduce"
}
}
}
}
remap
remap
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
keyPairs | object ✅ templating ✅ dot notation | Defines a mapping of input keys to output keys for remapping. | Yes |
Example
{
"service": {
"filters": {
"my-remap": {
"config": {
"keyPairs": {
"oldKey1": "newKey1",
"oldKey2": "newKey2"
}
},
"type": "remap"
}
}
}
}
select
select
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
keys | array ✅ templating ✅ dot notation | Keys to select | No |
Example
{
"service": {
"filters": {
"my-select": {
"config": {
"keys": [
"rssi",
"mac",
"my.nested.key"
]
},
"type": "select"
}
}
}
}
sort
sort
Pipeline FilterConnection Action
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 depending on the selected mode:
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
Fields
Name | Type | Description | Required |
---|---|---|---|
descending | boolean | If true items will be sorted in descending order | No |
key | string ✅ templating ✅ dot notation | 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. Example: "myAggregatedValues" | No |
maxEntries | integer | 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. | No |
outputKey | string ✅ templating ✅ dot notation | Set the output key for the sorted data. | No |
value | string ✅ templating | 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. Example: "{{ return .rssi }}" | Yes |
Example
{
"service": {
"filters": {
"sort-by-rssi": {
"config": {
"descending": true,
"maxEntries": 2,
"value": "{{ .rssi }}"
},
"type": "sort"
}
}
}
}
transform
transform
Pipeline FilterConnection Action
This filter transforms values using templates and a limited set of available functions.
Fields
Name | Type | Description | Required |
---|---|---|---|
keyPairs | object ✅ templating | A map of keys to transformation templates. The value of each key is looked up, then transformed using the template. 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 }} | Yes |
Example
{
"service": {
"filters": {
"my-transform": {
"config": {
"keyPairs": {
"mac": "{{ .mac | ToUpper | AddColonsToMac }}"
}
},
"type": "transform"
}
}
}
}
typeConvert
typeConvert
Pipeline FilterConnection Action
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.
Supported conversions:
any type (except []byte) to:
string
(usingfmt.Sprintf
)
[]byte to:
base64
: standard base64 encodinghex
: 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 int64uint
: string to uint64float
: 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:
- process all
injectKeys
- process all
convertKeys
In the case that all operations fail, the input map will be passed through unchanged.
Fields
Name | Type | Description | Required |
---|---|---|---|
convertKeys | object ✅ templating ✅ dot notation | Keys to convert Specify key-type conversions to perform | No |
injectKeys | map of string to ConverterInput | Keys to inject Specify conversion-injections to perform. | No |
Example
{
"service": {
"filters": {
"convert-it": {
"config": {
"convertKeys": {
"theKeyToConvert": "hex"
},
"injectKeys": {
"theKeyToInject": {
"length": 8,
"offset": 1,
"source": "nestedMap.keyWithBytesToConvert",
"type": "intLE"
}
}
},
"type": "typeConvert"
}
}
}
}
unwrap
unwrap
Pipeline FilterConnection Action
unwrap
takes a nested map from the event map and places all keys of the nested map at the top level of the event map.
given the input event map below and the key
a.b
:
{
"a":{
"x": 2,
"b":{
"c":1
}
}
}
``json output (key:
a.b`)
{
"a":{
"x": 2,
},
"c":1
}
Any conflicting keys between the top level event map and the nested map will be replaced with values from the nested map.
The unwrapped keys are always placed at the top level, even if dot notation is used.
Output: The input data with the specified key unwrapped.
**Fields**
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| `key` |string | The key to unwrap. Must target a map. <br />_Example:_ `"payload"` | Yes|
**Example**
```json Config
{
"service": {
"filters": {
"my-wrap": {
"config": {
"key": "payload"
},
"type": "unwrap"
}
}
}
}
wrap
wrap
Pipeline FilterConnection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
key | string ✅ templating ✅ dot notation | The key used to wrap the incoming data set. Example: "payload" | Yes |
keysToWrap | array ✅ templating ✅ dot notation | The particular keys to wrap. If left empty, all keys will be wrapped. | No |
Example
{
"service": {
"filters": {
"my-wrap": {
"config": {
"key": "payload"
},
"type": "wrap"
}
}
}
}
Connection Actions
awsmqttble
awsmqttble
Connection Action
Amazon FreeRTOS MQTT over BLE proxy
This action is used to run an mqtt-ble proxy between an Amazon FreeRTOS device and AWS IoT Core via an MQTT cloud connector.
The underlying MQTT cloud connector must have permissions to Connect/Publish/Subscribe/Receive to the device's topics.
Output: nil
Fields
Name | Type | Description | Required |
---|---|---|---|
connector | string | MQTT cloud connector This MQTT cloud connector will be used to connect to AWS IoT Core Example: "my-aws-connector" | Yes |
forcePairing | boolean | Force pairing Example: true | No |
idleTimeout | positiveDuration | No | |
subscribeTopics | stringArray | No | |
tolerateBrokerMismatch | boolean | Tolerate device requesting a different broker endpoint than the mqtt connector Example: true | No |
Example
{
"service": {
"actions": {
"mqtt-ble": {
"config": {
"connector": "aws",
"idleTimeout": 30000000000
},
"type": "awsmqttble"
}
}
}
}
encrypt
encrypt
Connection Action
Attempts to enable encryption using previously obtained encryption information.
If the encryption information is not available, this command will fail.
Output: None
Example
{
"service": {
"actions": {
"encrypt-comm": {
"type": "encrypt"
}
}
}
}
kkm
kkm
Connection Action
Reads/writes data to the specified KKM device. Supported devices types are
display
and socialDistance
. Each type of device has a specific configuration.
Fields
Name | Type | Description | Required |
---|---|---|---|
device | string | The type of device this action will interact with. Valid values aredisplay and socialDistance . | Yes |
displayConfig | KKMEslConfig | No | |
outputKey | string ✅ templating ✅ dot notation | The key to which output data will be written. If not specified for the socialDistance device, the default output key is contactRecords . | No |
socialBand | KKMSocialBandConfig | No |
Example
{
"service": {
"actions": {
"loop-example": {
"config": {
"device": "display",
"displayConfig": {
"mode": "play",
"nodeId": 2
},
"outputKey": ""
},
"type": "kkm"
}
}
}
}
loop
loop
Connection Action
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 providingcount
. - 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 initem.id/item.value
.
Output: output of the underlying connection sequence
Fields
Name | Type | Description | Required |
---|---|---|---|
collection | string ✅ templating | Iterate over a collection must be a template that outputs a map[string]interface{} or []interface | No |
count | integer | Provide the number of iterations to run the loop to enable count mode. | No |
id | string | The ID of the Connection Sequence that should be looped Example: "read-notifications" | Yes |
match | ? | Keys to match (all keys) for an inline definition (see MatcherDefinition ), or a Template to evaluate and match to a true value. | No |
matchAny | boolean | Should we match any of the provided matchers (true)? Or all of the matchers (false) | No |
matchers | array | The list of top-level matcher IDs to apply to the input map Example: [ "is-nearby", "is-my-device-type"] | No |
runAtLeastOnce | boolean | Run the loop at least once when using matcher mode. Ignored in count and collection mode. Example: true | No |
Example
{
"service": {
"actions": {
"loop-example": {
"config": {
"id": "read-more-data",
"match": {
"more-data": "true"
}
},
"type": "loop"
}
}
}
}
notificationControl
notificationControl
Connection Action
Enable/disable notifications/indications for a characteristic
This action enables/disables notifications for a characteristic.
To receive notifications, use the wait action.
Fields
Name | Type | Description | Required |
---|---|---|---|
characteristic | string ✅ templating | The UUID of characteristic to read Example: "2a26" | Yes |
enable | boolean | Enable or disable notifications/indications for the characteristic Example: true | Yes |
indication | ? ✅ templating | If true, indications are enabled for the characteristic boolean or template string Example: "true" | No |
service | string ✅ templating | The UUID of the service to which the characteristic belongs Example: "375aee4c-6dea-5105-9074-14d5ba44f766" | Yes |
Example
{
"service": {
"actions": {
"turn-on-notis": {
"config": {
"characteristic": "2a26",
"enable": false,
"indication": true,
"service": "375aee4c-6dea-5105-9074-14d5ba44f766"
},
"type": "notificationControl"
}
}
}
}
pair
pair
Connection Action
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
Example
{
"service": {
"actions": {
"pair-with-device": {
"type": "pair"
}
}
}
}
read
read
Connection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
characteristic | string ✅ templating | The UUID of characteristic to read | Yes |
longRead | bool ✅ templating | Specifies that the reads of this characteristic are longer than the maximum read length for BLE. In this case, the Read Blob operation will be used to read the data | No |
mode | string ✅ templating | Specifies how the output data should be treated: - If replace , existing data will be replaced when read. outputs ([]byte)- If append , the read data will be appended to an existing key. outputs ([]byte)- If array , each read will be placed into an array of read data. outputs ([][]byte)A new key will be added if the key does not exist upon the first read in append or array mode. | No |
outputKey | string ✅ templating ✅ dot notation | The map key for the output data. | Yes |
service | string ✅ templating | The UUID of the service to which the characteristic belongs. | Yes |
Example
{
"service": {
"actions": {
"read-custom-char": {
"config": {
"characteristic": "2a26",
"longRead": false,
"mode": "append",
"outputKey": "logs",
"service": "375aee4c-6dea-5105-9074-14d5ba44f766"
},
"type": "read"
}
}
}
}
readBattery
readBattery
Connection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
outputKey | string ✅ templating ✅ dot notation | The key name used to store the battery level Example: "batteryLevel" | No |
Example
{
"service": {
"actions": {
"read-the-battery": {
"config": {
"outputKey": "batteryLevel "
},
"type": "readBattery"
}
}
}
}
readDeviceInfo
readDeviceInfo
Connection Action
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
.
Fields
Name | Type | Description | Required |
---|---|---|---|
outputKey | string ✅ templating ✅ dot notation | Specifies the key to be used for the output. Example: "deviceInfo" | Yes |
Example
{
"service": {
"actions": {
"read-all-the-device-info": {
"config": {
"outputKey": "deviceInfo"
},
"type": "readDeviceInfo"
}
}
}
}
run
run
Connection Action
Runs another connection sequence with an optional condition.
The connection sequence specified by the id
parameter is run before this action completes and moves to the next
action in this sequence.
When the if
parameter is supplied the sequence is only run if the matchers in the condition pass. If the matchers
do not pass, execution proceeds to the next action subsequent to this one, rather than exit.
Fields
Name | Type | Description | Required |
---|---|---|---|
id | string | The ID of the connection sequence to run. Example: "read-notifications" | Yes |
if | MatcherConfig | No |
Example
{
"service": {
"actions": {
"run-example": {
"config": {
"id": "read-more-data",
"if": {
"match": {
"needToRead": "true"
}
}
},
"type": "run"
}
}
}
}
wait
wait
Connection Action
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.
Fields
Name | Type | Description | Required |
---|---|---|---|
allowNotificationTimeout | boolean | When the mode is notification , setting this true will allow a connection sequence to continue with no error when waiting for a notification times out. The data field will not be set in the output event. | No |
characteristic | string ✅ templating | UUID of characteristic to wait for a notification from Example: "2a26" | No |
indicationOverride | ? ✅ templating | Dynamically override notification or indication modes with this template | No |
interval | positiveDuration ✅ templating | The amount of time to wait for: - 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. | Yes |
keepNotificationsEnabled | boolean | When the mode is notification , setting this true will prevent the notifications from being disabled | No |
mode | string | The type of wait to perform. The options are: time, notification, indication Example: "time" | Yes |
multi | boolean | If true, collect multiple notifications/indications until none are received for the specified interval. Must receive at least one notification/indication for success. - Combine with: - outputMode = append/array- mode = notification/indication- multiWaitForInterface = false/true | No |
multiWaitForInterval | boolean | When multi is set to true, this field adjusts the waiting behavior. The default behavior is to wait for notifications untilno notifications are received for the specified interval. When this field is set to true, wait will gather notifications until the interval has beenreached. | No |
outputKey | string ✅ templating ✅ dot notation | When the mode is notification , this specifies the output key for the notification data | No |
outputMode | string | 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. | No |
service | string ✅ templating | The UUID of the service to wait for a notification from Example: "375aee4c-6dea-5105-9074-14d5ba44f766" | No |
Example
{
"service": {
"actions": {
"wait-for-something": {
"config": {
"interval": 10000000000,
"keepNotificationsEnabled": false,
"mode": "time",
"outputKey": "",
"outputMode": ""
},
"type": "wait"
}
}
}
}
write
write
Connection Action
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 -> [][]bytewriteString
: ascii string -> []byte
Output: None
Fields
Name | Type | Description | Required |
---|---|---|---|
acknowledge | AcknowledgeConfig | No | |
characteristic | string ✅ templating | UUID of characteristic to read Example: "2a26" | Yes |
data | string ✅ templating | 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. Example: "01ae489c25" | No |
header | string ✅ templating | Add a template or hexstring header | No |
headerEveryWrite | boolean | Add the header to every write in chunked mode | No |
maxWriteSize | integer | Set maximum number of bytes to write at once (0 for disabled) | No |
service | string ✅ templating | UUID of the service to which the characteristic belongs Example: "375aee4c-6dea-5105-9074-14d5ba44f766" | Yes |
withResponse | ? | Should perform write and wait for response? boolean or template | No |
Example
{
"service": {
"actions": {
"write-something": {
"config": {
"characteristic": "2a26",
"data": "01ae489c25",
"service": "375aee4c-6dea-5105-9074-14d5ba44f766"
},
"type": "write"
}
}
}
}
Config Model Reference
AcknowledgeConfig
AcknowledgeConfig
AcknowledgeConfig is used to receive and validate an acknowledgement after writing to a characteristic with the write
action.
If an acknowledgement fails validation, the write action stops and returns an error.
Referenced By:
write
Fields
Name | Type | Description | Required |
---|---|---|---|
ackMessageCount | integer | Setting to wait for acknowledgement every N messages | No |
characteristic | string | UUID of characteristic Example: "2a26" | Yes |
indication | boolean | Acknowledgement will be an indication instead of a notification? | No |
keepNotificationsEnabled | boolean | Keep notifications on characteristic enabled after receiving an acknowledgement? | No |
match | ? | Keys to match (all keys) for an inline definition (see MatcherDefinition ), or a Template to evaluate and match to a true value. | No |
matchAny | boolean | Should we match any of the provided matchers (true)? Or all of the matchers (false) | No |
matchers | array | The list of top-level matcher IDs to apply to the input map Example: [ "is-nearby", "is-my-device-type"] | No |
outputMode | string | Acknowledgement data output mode "replace", "array" or "append" | No |
service | string | UUID of the service Example: "375aee4c-6dea-5105-9074-14d5ba44f766" | Yes |
timeout | string | Acknowledgement timeout | Yes |
ConverterInput
ConverterInput
Used by the injectKeys
parameter of the typeConvert
Filter.
Defines the source key, bytes (offset/count), and destination type of a []byte
conversion
Referenced By:
typeConvert
Fields
Name | Type | Description | Required |
---|---|---|---|
length | integer | Number of bytes to select starting from offset . Use 0 (default) to mean all bytes after offset . Example: 9 | No |
offset | integer | Offset to select bytes from Example: 3 | No |
source | string ✅ dot notation | Key containing the bytes to convert Example: "rawData" | Yes |
type | string | Type to convert the bytes to, see above for supported types Example: "base64" | Yes |
EncodedField
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.
Referenced By:
EncodedLTV EncodedType
Fields
Name | Type | Description | Required |
---|---|---|---|
key | string ✅ templating | The key to put the decoded data in | Yes |
length | integer | The number of bytes that represents this fields value. | No |
template | string ✅ templating | 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 EncodedFielddescription for more details about computed fields. | No |
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 | Yes |
EncodedLTV
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.
Referenced By:
decodeLTV
Fields
Name | Type | Description | Required |
---|---|---|---|
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. | No |
fields | array of EncodedField | The fields of the type, in order that they are encoded in the data. | Yes |
id | integer | The unique ID of the type this describes. | Yes |
EncodedType
EncodedType
For use with the decodeType
filter/action. EncodedType describes a type containing multiple fields that can be encoded in a byte stream.
Referenced By:
decodeType
Fields
Name | Type | Description | Required |
---|---|---|---|
fields | array of EncodedField | The fields of the type, in order that they are encoded in the data. | Yes |
KKMEslConfig
KKMEslConfig
Describes configuration for KKM Electronic Shelf Labels. Must be used with the kkm
action.
Referenced By:
kkm
Fields
Name | Type | Description | Required |
---|---|---|---|
mode | string ✅ templating | Mode specifies the operation to be performed on the display. Valid options are play and download. If download is specified, then playAfterDownload is used to control the behavior upon successful download. | Yes |
nodeId | int64 ✅ templating | NodeId is the id of the node to play or to which the picture //data is downloaded. Generally, valid values are 0,1,2,3. | No |
pictureData | bytes ✅ templating | PictureData is the data for the picture to be downloaded. Required when the mode is download. | Yes |
pictureId | int64 ✅ templating | PictureId is the id of the picture that will be downloaded to the display. If the PictureId already exists on the device the download will be skipped. If PlayAfterDownload is true, the node with the matching PictureId will be played. Required for download mode. | Yes |
playAfterDownload | bool ✅ templating | PlayAfterDownload denotes that a downloaded image should be played once the download is successful. If not specified, the picture will only be downloaded to the device. | No |
Example
{
"mode": "play",
"nodeId": 2
}
KKMSocialBandConfig
KKMSocialBandConfig
Describes configuration for KKM Social Bands. Must be used with the kkm
action.
Referenced By:
kkm
Fields
Name | Type | Description | Required |
---|---|---|---|
advPower | integer | Not documented. This is only for testing and development purposes. | No |
alarmAction | integer | This value specifies the behavior of the band when an alarm occurs. The options are off (0), vibrate (2), audible (8), vibrate and audible (10) | No |
alarmDelay | integer | This value specifies the amount of time that must pass while two devices are within range of each other before an alarm will activate. Value is seconds | No |
alarmDistance | integer | This value controls the distance at which the social distance bands will alarm. It is specified in .1 m units. Note that 1.8m is ~6ft. | No |
alarmInterval | integer | This value specifies the time between alarms when an alarm occurs. Specified in 100ms increments. | No |
keepAfterRead | boolean | If set to true, keep after read leaves the contact records on the band. Otherwise, they are cleared once they are successfully read from the device. | No |
recordDelay | integer | This value specifies the amount of time that must pass while two devices are within alarm range of each other before a contact record will be recorded. | No |
KeystoreKey
KeystoreKey
Specify a key to use from the keystore.
Referenced By:
cipherDecrypt cipherEncrypt
Fields
Name | Type | Description | Required |
---|---|---|---|
keystoreKey | string | name of key in the keystore Example: "myKey" | Yes |
publicKey | boolean | if using a keypair, use the public key? Example: true | No |
MatcherConfig
MatcherConfig
Configures a set of key/value pairs as well as a list of top level matchers
Referenced By:
fwupdate managed persistent persistent run static static
Fields
Name | Type | Description | Required |
---|---|---|---|
match | ? | Keys to match (all keys) for an inline definition (see MatcherDefinition ), or a Template to evaluate and match to a true value. | No |
matchAny | boolean | Should we match any of the provided matchers (true)? Or all of the matchers (false) | No |
matchers | array | The list of top-level matcher IDs to apply to the input map Example: [ "is-nearby", "is-my-device-type"] | No |
ReduceConfig
ReduceConfig
Configuration for processing of the reduce
filter.
Referenced By:
reduce
Fields
Name | Type | Description | Required |
---|---|---|---|
reduce | string ✅ templating | 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. Example: "{{ maxf .__items }}" | Yes |
value | string ✅ templating | Value template used to collect an array of values from a collection of maps. If the items in the collection is not a map, then the value will be wrapped in the key item .The array of collected values is passed to the reduce function under key __items . Example: "{{ .rssi }}" | Yes |
Updated over 1 year ago