Pipeline Components

Use these components to build your Pipelines and Connection Sequences


Pipeline Filters

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

NameTypeDescriptionRequired
arrayMaxintegerMaximum length of the storage array. Only applies in array and mapArray modes.
Example: 33
No
arrayOutputKeystringWhen in array mode, or map mode with convertMapToArray set to true, wrap the output array in this key.
Example: "myItems"
No
convertMapToArraybooleanWhen 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
deleteKeybooleanDeletes key from the aggregated object(s)No
disableEmptybooleanDisable emitting empty aggregates
Example: true
No
intervalstringThe 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
joinMapsbooleanJoin maps in map mode. If true, joins the current event with the previous event for a device.No
keystringThe key to use for aggregation in map modes. Used if map or mapArray mode are used.
Example: "mac"
No
mapMaxintegerMaximum length of the storage map. Only applies to map and mapArray modes.
Example: 42
No
maxCountintegerMaximum 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
modestringThe 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

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

NameTypeDescriptionRequired
keystring
templating
dot notation
The key containing the values to chunk, if blank the whole event map will be chunked.Yes
sizeint64
templating
Maximum number of items to emit in each chunkYes

Example

{
  "service": {
    "filters": {
      "25-chunker": {
        "config": {
          "key": "values",
          "size": 25
        },
        "type": "chunk"
      }
    }
  }
}

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

NameTypeDescriptionRequired
cacheGattDbbooleanCache the GATT database of this device when true
Example: true
No
idstringThe ID of the Connection Sequence that should be triggered every time this filter is reached
Example: "read-battery-life"
Yes
intervalstringThe 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

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

NameTypeDescriptionRequired
groupsstringArrayThe device group(s) to iterate over. Can be a single Device Group ID (string) or an array of Device Group IDs.Yes
includeAbsentDevicesboolAlso include devices that are not currently "present" but are members of the device groupNo

Example

{
  "service": {
    "filters": {
      "iterate-array": {
        "config": {
          "groups": "my-devices"
        },
        "type": "deviceGroupIterator"
      }
    }
  }
}

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

NameTypeDescriptionRequired
groupIdstring
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

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

NameTypeDescriptionRequired
ignoreEIDbooleanIgnore EID advertising payloadsNo
ignoreTLMbooleanIgnore TLM advertising payloadsNo
ignoreUIDbooleanIgnore UID advertising payloadsNo
ignoreURLbooleanIgnore URL advertising payloadsNo
passthroughbooleanPassthrough non-eddystone eventsNo

Example

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

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

NameTypeDescriptionRequired
typesarrayEnabled Sensor Types (available: emdcb, emswb)
Example: [ "emdcb"]
No

Example

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

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

NameTypeDescriptionRequired
activationDisablebooleanDisable activation sequenceNo
activationSequencestringCustom activation sequence idNo
activationTimeoutpositiveDurationSet activation connection timeoutNo
firmwareBytesstringSelect source of the firmware bytes (must be template)
Example: "{{ .keyWithFirmwareBytes }}"
Yes
postActivationDelaypositiveDurationSet post activation delayNo
targetMatcherConfigNo
typestringDFU type
set the dfu type
Example: "nordic"
No
updaterTimeoutpositiveDurationSet updater connection timeoutNo

Example

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

ibeacon

Pipeline Filter

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

Output: All available iBeacon fields and their values.

Fields

NameTypeDescriptionRequired
passthroughbooleanPassthrough non-iBeacon eventsNo
uuidFilterstringIf 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

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

NameTypeDescriptionRequired
devicesarrayDefines 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

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

NameTypeDescriptionRequired
forEacharrayForEach 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
keystring
templating
dot notation
The key containing the values to iterate overYes
maxintegerMaximum number of items to emit from iterationNo

Example

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

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

NameTypeDescriptionRequired
authKeystringAuthentication Key for authenticated S1 payloadsNo
typesarrayEnabled Sensor Types (available: s1,e6)
Example: [ "s1"]
No

Example

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

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

Fields

NameTypeDescriptionRequired
historyLengthintegerHistory length (in intervals) (v2 only)No
modestringThe mode in which to operate (v1 only). Options are 'regular' and 'raw'.
Example: "raw"
No
occupiedCountintegerNumber of intervals to sum the occupied count over (>0) (v2 only)No
occupiedThresholdintegerThreshold for occupied count to trigger occupied state (>0) (v2 only)No
outputHistorybooleanOutput history (v2 only)No
unoccupiedCountintegerNumber of intervals to sum the unoccupied count over (>0) (v2 only)No
unoccupiedThresholdintegerThreshold for unoccupied count to trigger unoccupied state (>0) (v2 only)No
updateIntervalSecintegerUpdate 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

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

NameTypeDescriptionRequired
groupIdstring
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

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

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

NameTypeDescriptionRequired
countintegerThrottle with a counter
Example: 10
No
ignoreFirstEventbooleanIgnore the first event, regardless of count/timeout - wait until count/timeout is reached before emitting.No
keystringKeys to throttle onNo
maxCountintegerMaximum number of id's to track, after hitting this limit, unknown id's will be ignored.No
timeoutpositiveDurationThrottle with a timeoutNo

Example

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

Use as Filter or Action

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

NameTypeDescriptionRequired
arraystring
templating
dot notation
The key of the array to append the item to.
Example: "item"
Yes
deleteItembooleanIf true, delete the original item key/value after appending to the array.
Example: false
No
itemstring
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

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

NameTypeDescriptionRequired
additionalDatabytes
templating
Additional data bytes - only used with AEAD ciphersNo
cipherstring
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
inputbytes
templating
Input bytes - encrypt: the un-encrypted bytes, decrypt: the encrypted bytesYes
ivbytes
templating
Initialization vector bytes - only used with ciphers that require an IVNo
keybytes
templating
Cipher key bytesYes
keystoreInputKeystoreKeyInput bytes from keystore - encrypt onlyNo
keystoreKeystringname of key in the keystore
Example: "myKey"
Yes
noncebytes
templating
Nonce bytes - only used with AEAD ciphersNo
outputstring
templating
Key to output the result of the operation in the event mapNo
publicKeybooleanif 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

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

NameTypeDescriptionRequired
additionalDatabytes
templating
Additional data bytes - only used with AEAD ciphersNo
cipherstring
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
inputbytes
templating
Input bytes - encrypt: the un-encrypted bytes, decrypt: the encrypted bytesYes
ivbytes
templating
Initialization vector bytes - only used with ciphers that require an IVNo
keybytes
templating
Cipher key bytesYes
keystoreInputKeystoreKeyInput bytes from keystore - encrypt onlyNo
keystoreKeystringname of key in the keystore
Example: "myKey"
Yes
noncebytes
templating
Nonce bytes - only used with AEAD ciphersNo
outputstring
templating
Key to output the result of the operation in the event mapNo
publicKeybooleanif 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

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

NameTypeDescriptionRequired
dataKeystringThe key to read the data from.No
lengthInclusivebooleanLengthInclusive describes whether the length includes the length byte itselfNo
outputKeystringThe key to store decoded data inNo
typeInclusivebooleanTypeInclusive describes whether the length includes the type byteNo
typesmap of string to EncodedLTVA 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

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

NameTypeDescriptionRequired
dataKeystringThe key to read the data from.No
outputKeystringThe key to store decoded data inNo
outputMapbooleanIf set to true, the object(s) that are decoded will be merged into one output map, rather than appended to an array.No
typeEncodedTypeYes

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

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

NameTypeDescriptionRequired
keysarrayKeys to deleteYes

Example

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

deviceReport

Pipeline FilterConnection Action

This filter fetches information about devices in device groups and seen nearby.

Fields

NameTypeDescriptionRequired
groupsstringArray
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 expressionsNo
includePropsbool
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
includeUnknownDevicesbool
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
outputAsArraybool
templating
Output report as an array instead of a map?No
outputKeystring
templating
dot notation
Output key for reportNo

Example

{
  "service": {
    "filters": {
      "dg-info-all": {
        "config": {
          "groups": "^.*\\.provisioned",
          "outputAsArray": true,
          "outputKey": "provisionedDevices"
        },
        "type": "deviceReport"
      }
    }
  }
}

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

NameTypeDescriptionRequired
eventTypestringDefine the emitted event type.
Example: "ovenPreheated"
Yes
payloadKeystring
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

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

NameTypeDescriptionRequired
algorithmstringSet hash algorithm
Example: "md5"
Yes
appendbooleanEnable append modeNo
computebooleanEnable compute modeNo
expectstring
templating
Enable expect modeNo
hashBytesBigEndianbooleanHandle hash array as big endianNo
hashStringBigEndianbooleanHandle hash strings as big endian
Default is false for all algorithms except crc16
No
hmacbooleanenable HMAC modeNo
hmacKeystring
templating
Set the HMAC key (supports template, hexstring or base64)
Must be set if hmac == true and hmacKeystoreKey is not set
Example: "{{ .key }}"
No
hmacKeystoreKeystringSet the HMAC key from a secret from the keystore (secret must be []byte or a hex/base64 string)
Example: "mySecretKey"
No
inputKeystring
templating
dot notation
Define the input keyYes
outputKeystring
templating
dot notation
Define the output keyYes
outputSizeintegerSet 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
verifybooleanEnable 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

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 device
  • ok 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 nil
  • false nil
  • true the input event with the history ([]interface{}) stored in outputKey

Fields

NameTypeDescriptionRequired
conditionstring
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
deviceIdstring
templating
DeviceId to uniquely identify deviceNo
historyCountintegerSet 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
historyDurationpositiveDuration
templating
Set history length by duration string (also see historyCount)No
historyTimeoutpositiveDuration
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
maxDeviceCountintegerMaximum number of unique devices to track. Once the limit is reached,
the oldest devices will be replaced by new devices
No
omitHistorybooleanOmit history data when emitting history event (passthrough device event only)No
outputKeystring
templating
Key to output history in event mapNo
thresholdHighnumberThreshold 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
thresholdHysteresisHighnumberNo
thresholdHysteresisLownumberThreshold hysteresis values.
Example: 1.5
No
thresholdLownumberNo
valuestring
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

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

NameTypeDescriptionRequired
bodystring
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
bodyFormatterstringThe formatter used to encode the HTTP request body.
Available options: json, jsongz, base64json, cbor
Example: "cbor"
No
castringAdditional CAs to append to system certpool
CA certs must be base64 encoded pem format
No
cacheMaxItemsintegerMax Cache size in itemsNo
contentTypeOutputKeystring
templating
Defines the output key for the HTTP response Content-Type in the event map.
Example: "contentType"
No
headersobject
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
intervalstringThe 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
methodstring
templating
The HTTP method, can be GET, POST, PUT
Example: "POST"
No
outputKeystring
templating
Defines the output key for the HTTP response body in the event map.No
passthroughHTTPErrorbooleanEmit 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
persistentbooleanEnable persistent cacheNo
statusKeystring
templating
Defines the output key for the HTTP status code in the event mapNo
successfulStatusesarrayDefine the httpStatus codes that are considered successful.
A response will only be cached if the status code is in this list.
No
timeoutpositiveDuration
templating
HTTP request timeout (duration string)No
urlstring
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

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:

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.

Fields

NameTypeDescriptionRequired
keyPairsobject
templating
dot notation
Defines a set of keys and values to add to the event map output.No
replaceExistingbooleanReplace key value pairs that already exist, instead of ignoring themNo

Example

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

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

NameTypeDescriptionRequired
keystoreKeystringKeystore key to operate on, must be pre-defined in the keystoreYes

Example

{
  "service": {
    "filters": {
      "delete-key": {
        "config": {
          "keystoreKey": "myKey"
        },
        "type": "keystoreDelete"
      }
    }
  }
}

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

NameTypeDescriptionRequired
keystoreKeystringKeystore key to operate on, must be pre-defined in the keystoreYes
setPrivateKeybytesNo
setPublicKeybytesNo
setSecretstringSecret to set in keystore
Only to be used on keys of type secret
No

Example

{
  "service": {
    "filters": {
      "set-keypair": {
        "config": {
          "keystoreKey": "myKeypair",
          "setPrivateKey": "{{.prv}}",
          "setPublicKey": "{{.pub}}"
        },
        "type": "keystoreSet"
      }
    }
  }
}

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

NameTypeDescriptionRequired
match?Keys to match (all keys) for an inline definition (see MatcherDefinition), or a Template to evaluate and match to a true value.No
matchAnybooleanShould we match any of the provided matchers (true)? Or all of the matchers (false)No
matchersarrayThe 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

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

NameTypeDescriptionRequired
allDevicesbooleanPerform device metadata operations on all devices?No
globalbooleanPerform global metadata operations?No
keysarrayThe metadata keys to delete, all keys are deleted if emptyNo

Example

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

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

NameTypeDescriptionRequired
globalbooleanPerform global metadata operations?Yes
keysarrayThe 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

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

NameTypeDescriptionRequired
globalbooleanPerform global metadata operations?Yes
keysarrayThe metadata keys to filter on for a given device, all keys are used if emptyNo

Example

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

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

NameTypeDescriptionRequired
getHistorybooleanAdd ntp sync history for the history window to input event?No
getLastSuccessbooleanAdd last successful ntp sync into input event?No
getMaxOffsetbooleanAdd maximum clock offset from history window to input event?No
historyWindowstringHow far back to look in the NTP sync history when processing an event
historyCount = (historyWindow/syncInterval) + 1
historyCount must be <= 1000
No
hoststringWhich NTP server to queryNo
syncIntervalstringNTP server query intervalNo

Example

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

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

NameTypeDescriptionRequired
keyPairsobject
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

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

NameTypeDescriptionRequired
attemptsintegerHow many attempts to make when publishing a payload.
Will only attempt more than once when a retryable error is returned.
No
connectorstringID of the Cloud Connector to publish to, defined in the Cloud Connectors Config.
Example: "my-azure"
Yes
formatstringThe format of the data to publish. Supported options are json and cbor.
Example: "json"
No
maxPayloadSizeintegerMaximum payload size, if <= 0 there is no limit.No
payloadKeystringThe key of the payload to send. If left empty, the whole event map is sent.No
payloadsKeystringThis key must point to a map of topic strings to payloads.
Each entry in that map will be published to its respective topic.
No
retryDelaypositiveDuration
templating
How long to wait before attempting a retryNo
timeoutpositiveDuration
templating
Timeout for publishing (negative for no timeout)No
topicstring
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

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

NameTypeDescriptionRequired
keystring
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
valuesmap of string to ReduceConfigMap 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

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

NameTypeDescriptionRequired
keyPairsobject
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

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

NameTypeDescriptionRequired
keysarray
templating
dot notation
Keys to selectNo

Example

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

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

NameTypeDescriptionRequired
descendingbooleanIf true items will be sorted in descending orderNo
keystring
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
maxEntriesintegerIf >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
outputKeystring
templating
dot notation
Set the output key for the sorted data.No
valuestring
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

Pipeline FilterConnection Action

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

Fields

NameTypeDescriptionRequired
keyPairsobject
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

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 (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.

Fields

NameTypeDescriptionRequired
convertKeysobject
templating
dot notation
Keys to convert
Specify key-type conversions to perform
No
injectKeysmap of string to ConverterInputKeys 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

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

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

NameTypeDescriptionRequired
keystring
templating
dot notation
The key used to wrap the incoming data set.
Example: "payload"
Yes
keysToWraparray
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

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

NameTypeDescriptionRequired
connectorstringMQTT cloud connector
This MQTT cloud connector will be used to connect to AWS IoT Core
Example: "my-aws-connector"
Yes
forcePairingbooleanForce pairing
Example: true
No
idleTimeoutpositiveDurationNo
subscribeTopicsstringArrayNo
tolerateBrokerMismatchbooleanTolerate 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

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

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

NameTypeDescriptionRequired
devicestringThe type of device this action will interact with. Valid values are
display and socialDistance.
Yes
displayConfigKKMEslConfigNo
outputKeystring
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
socialBandKKMSocialBandConfigNo

Example

{
  "service": {
    "actions": {
      "loop-example": {
        "config": {
          "device": "display",
          "displayConfig": {
            "mode": "play",
            "nodeId": 2
          },
          "outputKey": ""
        },
        "type": "kkm"
      }
    }
  }
}

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 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 sequence

Fields

NameTypeDescriptionRequired
collectionstring
templating
Iterate over a collection
must be a template that outputs a map[string]interface{} or []interface
No
countintegerProvide the number of iterations to run the loop to enable count mode.No
idstringThe 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
matchAnybooleanShould we match any of the provided matchers (true)? Or all of the matchers (false)No
matchersarrayThe list of top-level matcher IDs to apply to the input map
Example: [ "is-nearby", "is-my-device-type"]
No
runAtLeastOncebooleanRun 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

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

NameTypeDescriptionRequired
characteristicstring
templating
The UUID of characteristic to read
Example: "2a26"
Yes
enablebooleanEnable 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
servicestring
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

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

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

NameTypeDescriptionRequired
characteristicstring
templating
The UUID of characteristic to readYes
longReadbool
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 dataNo
modestring
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
outputKeystring
templating
dot notation
The map key for the output data.Yes
servicestring
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

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

NameTypeDescriptionRequired
outputKeystring
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

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

NameTypeDescriptionRequired
outputKeystring
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

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

NameTypeDescriptionRequired
idstringThe ID of the connection sequence to run.
Example: "read-notifications"
Yes
ifMatcherConfigNo

Example

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

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

NameTypeDescriptionRequired
allowNotificationTimeoutbooleanWhen 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
characteristicstring
templating
UUID of characteristic to wait for a notification from
Example: "2a26"
No
indicationOverride?
templating
Dynamically override notification or indication modes with this templateNo
intervalpositiveDuration
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
keepNotificationsEnabledbooleanWhen the mode is notification, setting this true will prevent the notifications from being disabledNo
modestringThe type of wait to perform. The options are: time, notification, indication
Example: "time"
Yes
multibooleanIf 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
multiWaitForIntervalbooleanWhen 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
outputKeystring
templating
dot notation
When the mode is notification, this specifies the output key for the notification dataNo
outputModestringWhen 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
servicestring
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

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 -> [][]byte
  • writeString: ascii string -> []byte

Output: None

Fields

NameTypeDescriptionRequired
acknowledgeAcknowledgeConfigNo
characteristicstring
templating
UUID of characteristic to read
Example: "2a26"
Yes
datastring
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
headerstring
templating
Add a template or hexstring headerNo
headerEveryWritebooleanAdd the header to every write in chunked modeNo
maxWriteSizeintegerSet maximum number of bytes to write at once (0 for disabled)No
servicestring
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 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

NameTypeDescriptionRequired
ackMessageCountintegerSetting to wait for acknowledgement every N messagesNo
characteristicstringUUID of characteristic
Example: "2a26"
Yes
indicationbooleanAcknowledgement will be an indication instead of a notification?No
keepNotificationsEnabledbooleanKeep 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
matchAnybooleanShould we match any of the provided matchers (true)? Or all of the matchers (false)No
matchersarrayThe list of top-level matcher IDs to apply to the input map
Example: [ "is-nearby", "is-my-device-type"]
No
outputModestringAcknowledgement data output mode "replace", "array" or "append"No
servicestringUUID of the service
Example: "375aee4c-6dea-5105-9074-14d5ba44f766"
Yes
timeoutstringAcknowledgement timeoutYes

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

NameTypeDescriptionRequired
lengthintegerNumber of bytes to select starting from offset. Use 0 (default) to mean all bytes after offset.
Example: 9
No
offsetintegerOffset to select bytes from
Example: 3
No
sourcestring
dot notation
Key containing the bytes to convert
Example: "rawData"
Yes
typestringType to convert the bytes to, see above for supported types
Example: "base64"
Yes

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

NameTypeDescriptionRequired
keystring
templating
The key to put the decoded data inYes
lengthintegerThe number of bytes that represents this fields value.No
templatestring
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 EncodedField
description for more details about computed fields.
No
typestringThe 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

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

NameTypeDescriptionRequired
appendToArraystringIf 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
fieldsarray of EncodedFieldThe fields of the type, in order that they are encoded in the data.Yes
idintegerThe unique ID of the type this describes.Yes

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

NameTypeDescriptionRequired
fieldsarray of EncodedFieldThe fields of the type, in order that they are encoded in the data.Yes

KKMEslConfig

Describes configuration for KKM Electronic Shelf Labels. Must be used with the kkm action.

Referenced By:
kkm  

Fields

NameTypeDescriptionRequired
modestring
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
nodeIdint64
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
pictureDatabytes
templating
PictureData is the data for the picture to be downloaded. Required when the mode is download.Yes
pictureIdint64
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
playAfterDownloadbool
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

Describes configuration for KKM Social Bands. Must be used with the kkm action.

Referenced By:
kkm  

Fields

NameTypeDescriptionRequired
advPowerintegerNot documented. This is only for testing and development purposes.No
alarmActionintegerThis 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
alarmDelayintegerThis 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
alarmDistanceintegerThis 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
alarmIntervalintegerThis value specifies the time between alarms when an alarm occurs. Specified in
100ms increments.
No
keepAfterReadbooleanIf 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
recordDelayintegerThis 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

Specify a key to use from the keystore.

Referenced By:
cipherDecrypt   cipherEncrypt  

Fields

NameTypeDescriptionRequired
keystoreKeystringname of key in the keystore
Example: "myKey"
Yes
publicKeybooleanif using a keypair, use the public key?
Example: true
No

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

NameTypeDescriptionRequired
match?Keys to match (all keys) for an inline definition (see MatcherDefinition), or a Template to evaluate and match to a true value.No
matchAnybooleanShould we match any of the provided matchers (true)? Or all of the matchers (false)No
matchersarrayThe list of top-level matcher IDs to apply to the input map
Example: [ "is-nearby", "is-my-device-type"]
No

ReduceConfig

Configuration for processing of the reduce filter.

Referenced By:
reduce  

Fields

NameTypeDescriptionRequired
reducestring
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
valuestring
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