n

Rigado Edge Connect API Reference

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

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

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

Configuration Elements

Cloud

Cloud connection configuration definition

connectors: object

Defines the cloud Connectors to connect to.

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

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

Example
{
  "connectors": "object"
}

CloudConnector

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

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

config: object

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

type: string

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

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

CloudConnectorDevices

Device configuration for connectors that support device based subscriptions.

attachAll: boolean false

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

detachMissing: boolean false

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

deviceIdTemplate: string

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

group: string

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

subscribeTopics: string[]

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

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

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

Config

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

actions: object

Defines the ConnectionActions that can be used in ConnectionSequences.

A map of unique identifier to a ConnectionAction definition.

ConnectionActions defined here can be reused in multiple ConnectionSequences.

api: RestAPI
cloud: Cloud
connections: object

Defines the ConnectionSequences that will handle processing of BLE connections.

A map of unique identifier to a ConnectionSequence definition.

ConnectionSequences are triggered by a connect filter.

filters: object

Defines the Filters available for use in Pipelines.

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

Filters defined here can be reused in multiple Pipelines.

groups: object

Defines the DeviceGroups that can be referenced by Pipelines.

A map of unique identifier to DeviceGroup definition.

health: Health
log: Log
matchers: object

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

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

metadata: Metadata
metrics: Metrics
pipelines: object

Defines the Pipelines of Filters that events will flow through.

A map of unique identifier to a Pipeline definition.

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

ConnectionAction

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

config: object

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

type: string

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

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

ConnectionSequence

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

actions: string[]

List of ConnectionAction identifiers.

References the actions defined on Config.

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

ConverterInput

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

length: integer (int64) 0

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

offset: integer (int64) 0

Offset to select bytes from

source: string

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

type: string

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

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

DeviceGroup

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

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

Only types static or persistent are currently supported.

config: object

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

type: string

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

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

DeviceGroupBatteryConfig

enabled: boolean false
failPercent: number (float) 1

The percentage at which to trigger a Status of Fail

warnPercent: number (float) 20

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

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

Filter

Filter describes the configuration for one Filter Node in a Pipeline

config: object

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

type: string

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

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

Health

reporting: Reporting
watchdogRestartMinutes: integer (int64) 10

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

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

Log

Log describes the logging configuration

level: string info

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

printTimestamps: boolean false

If true, log messages will contain timestamps.

suppressAdvDecodeErrors: boolean false

If true, advertisement decode errors will be suppressed

Example
{
  "service": {
    "log": {
      "level": "info",
      "printTimestamps": false
    }
  }
}

MatcherConfig

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

match: MatcherDefinition
matchers: string[]

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

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

MatcherDefinition

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

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

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

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

Metadata

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

devices: object

Device metadata to initialize

global: object

Global metadata to initialize

persistent: boolean

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

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

Metrics

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

Pipeline

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

debug: boolean false

Enable debug logging

disabled: boolean false

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

eventType: string

The type of events to process in this Pipeline.

Supported options:

advertisement (default) for BLE advertising events

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

cloud for events from cloud subscriptions

filters: string[]

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

References the filters defined on Config

string
groups: string[]

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

References the groups defined on Config

string
match: MatcherDefinition
matchers: string[]

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

string
verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "pipelines": {
      "eddypipe": {
        "filters": [
          "eddyf",
          "my-mqtt"
        ],
        "eventType": "advertisements",
        "groups": [
          "east-wing-eddystones"
        ]
      }
    }
  }
}

Reporting

intervalMinutes: integer (int64) 10

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

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

RestAPI

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

devmode: boolean false

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

port: integer (int64) 62307

The port to host the API server on

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

Connection Actions

enableNotifications

Enable notifications/indications for a characteristic

This action enable notifications for a characteristic. To receive notifications, use the wait action.

characteristic: string

The UUID of characteristic to read

debug: boolean false

Enable debug logging

indication: boolean

If true, indications are enabled for the characteristic

service: string

The UUID of the service to which the characteristic belongs

verbose: boolean false

Enable verbose logging

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

encrypt

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

Output: None

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

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

loop

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

In count mode, the connection sequence is executed N times by providing count. In condition mode, the connection sequence is executed while the condition is true.

Output: output of the underlying connection sequence

condition: PolicySet
count: integer (int64)

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

debug: boolean false

Enable debug logging

id: string

The ID of the Connection Sequence that should be looped

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "actions": {
      "loop-example": {
        "type": "loop",
        "config": {
          "condition": {
            "more-data-true": {
              "allowOnMatch": true,
              "keys": [
                {
                  "key": "more-data",
                  "value": "true"
                }
              ]
            }
          },
          "id": "read-more-data"
        }
      }
    }
  }
}

pair

Attempts to create a pairing with the connected device. If the device is already paired, this action will fail. Currently only supports pairing via LE Legacy Just Works encryption, LE Secure Connections are not yet supported.

Output: None

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

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

read

Read the value of a characteristic

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

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

characteristic: string

The UUID of characteristic to read

debug: boolean false

Enable debug logging

outputKey: string

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

service: string

The UUID of the service to which the characteristic belongs

verbose: boolean false

Enable verbose logging

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

readBattery

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

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

debug: boolean false

Enable debug logging

outputKey: string batteryLevel

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

verbose: boolean false

Enable verbose logging

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

readDeviceInfo

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

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

debug: boolean false

Enable debug logging

outputKey: string

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

verbose: boolean false

Enable verbose logging

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

wait

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

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

debug: boolean false

Enable debug logging

interval: string

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

keepNotificationsEnabled: boolean

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

mode: string

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

outputKey: string

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

outputMode: string replace

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

verbose: boolean false

Enable verbose logging

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

write

Writes data to a characteristic.

If the input to this action contains the key writeData, then the value of that key will be written to the specified characteristic rather than the value specified in data.

If the input contains the key writeBase64, then the data will be base64 decoded and then written. This option also supports an array of base64 strings, which will cause multiple writes.

Output: None

characteristic: string

The UUID of characteristic to read

data: string

The data to write to the characteristic. This is formatted as a hexadecimal string. If the incoming payload contains the key "writeData", the value for that key will be written to the characteristic instead of this value. While Data is not required, if a prior read action does not send data to this action to write and this property is not defined, this action will report an error.

debug: boolean false

Enable debug logging

service: string

The UUID of the service to which the characteristic belongs

verbose: boolean false

Enable verbose logging

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

Cloud Connectors

azureiot

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

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

connectionString: string

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

debug: boolean false

Enable debug logging

persistent: boolean false

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

verbose: boolean false

Enable verbose logging

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

digitalTwins

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

Supports publishing but does not support subscriptions.

baseURL: string

The BaseURL of the digital twins instance to use

debug: boolean false

Enable debug logging

deviceHardwareId: string

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

persistent: boolean false

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

sasToken: string

A Shared Access Signature that has been generated for this deviceId

sensorHardwareIdKey: string

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

verbose: boolean false

Enable verbose logging

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

googlecloudiot

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

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

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

debug: boolean false

Enable debug logging

devices: CloudConnectorDevices
gatewayId: string

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

persistent: boolean false

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

privateKey: string

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

projectId: string

Google Project ID

region: string

Google Region the project is in

registryId: string

Google IOT Registry ID

subscribeTopics: string[]

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

Supports text templating.

string
verbose: boolean false

Enable verbose logging

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

http

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

Support publishing but no subscriptions.

debug: boolean false

Enable debug logging

headers: object

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

method: string

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

timeout: integer (int64) 30

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

url: string

The HTTP url to send data Supports text templating.

verbose: boolean false

Enable verbose logging

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

mqtt

This cloud connector provides a connection to an MQTT broker.

Support publishing on topics and subscriptions on topics.

base: string

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

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

The ClientID to use in the MQTT connection.

credentials: object

A set of base64 encoded TLS credentials.

ca: string

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

cert: string

TLS certificate

key: string

TLS private key

debug: boolean false

Enable debug logging

devices: CloudConnectorDevices
host: string

The host address of the broker

persistent: boolean false

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

port: integer (int64)

The port of the broker

scheme: string

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

subscribeTopics: string[]

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

Supports text templating.

string
verbose: boolean false

Enable verbose logging

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

Device Group Types

persistent

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

absenceMinutes: integer (int64) 5

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

batteryEvents: DeviceGroupBatteryConfig
debug: boolean false

Enable debug logging

disableMonitoring: boolean false

Disable sending monitoring events for this group to the Edge Direct

exclude: string[]

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

string
excludeAllByDefault: boolean true

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

include: string[]

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

string
includeMatchers: MatcherConfig
verbose: boolean false

Enable verbose logging

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

static

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

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

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

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

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

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

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

absenceMinutes: integer (int64) 5

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

batteryEvents: DeviceGroupBatteryConfig
debug: boolean false

Enable debug logging

disableMonitoring: boolean false

Disable sending monitoring events for this group to the Edge Direct

exclude: string[]

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

string
excludeAllByDefault: boolean true

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

include: string[]

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

string
includeMatchers: MatcherConfig
verbose: boolean false

Enable verbose logging

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

Use as Filter or Action

delete

This filter deletes the specified keys from the input map.

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

debug: boolean false

Enable debug logging

keys: string[]

Keys to delete

string
verbose: boolean false

Enable verbose logging

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

hash

This filter calculates, appends or validates hash values Supported algorithms: crc16-ccitt-false

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

algorithm: string

Set hash algorithm

append: boolean

Enable append mode

compute: boolean

Enable compute mode

debug: boolean false

Enable debug logging

inputKey: string

Define the input key Supports dot notation and text templating.

outputKey: string

Define the output key Supports dot notation and text templating.

verbose: boolean false

Enable verbose logging

verify: boolean

Enable verify mode (assumes input has hash appended)

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

inject

This filter injects keys into the output JSON data. 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 JSON. The output JSON will contain all keys and values from the input. If a key name collision occurs, the injected key will be ignored.

Supported timestamp values:

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

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

debug: boolean false

Enable debug logging

keyPairs: object

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

replaceExisting: boolean false

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

verbose: boolean false

Enable verbose logging

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

matcher

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

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

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

debug: boolean false

Enable debug logging

match: MatcherDefinition
matchers: string[]

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

string
verbose: boolean false

Enable verbose logging

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

metadataClear

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

Output: unmodified input

allDevices: boolean false

Perform device metadata operations on all devices?

debug: boolean false

Enable debug logging

global: boolean false

Perform global metadata operations?

keys: string[] empty

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

string
verbose: boolean false

Enable verbose logging

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

metadataGet

Adds metadata on to an input map

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

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

Output: Input map with requested metadata added

debug: boolean false

Enable debug logging

global: boolean

Perform global metadata operations?

keys: string[]

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

string
verbose: boolean false

Enable verbose logging

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

metadataSet

Sets metadata on input.

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

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

Output: unmodified input

debug: boolean false

Enable debug logging

global: boolean

Perform global metadata operations?

keys: string[]

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

string
verbose: boolean false

Enable verbose logging

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

remap

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

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

debug: boolean false

Enable debug logging

keyPairs: object

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

verbose: boolean false

Enable verbose logging

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

select

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

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

debug: boolean false

Enable debug logging

keys: string[]

Keys to select Supports dot notation and text templating.

string
verbose: boolean false

Enable verbose logging

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

transform

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

debug: boolean false

Enable debug logging

keyPairs: object

A map of keys to transformation templates. The value of each key is looked up, then transformed using the template. Templates follow the golang Text Template format. All values in the input map are available using dot notation. For top level values, start with a dot, e.g. .mac. A few helper functions are also available:

  • ToUpper
  • ToLower
  • AddColonsToMac
  • ToHex
  • ToBase64
  • Serial
  • Timestamp

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

{{ .mac | ToUpper | AddColonsToMac }}

Also supports dot notation in key or value.

verbose: boolean false

Enable verbose logging

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

typeConvert

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

Supported conversions:

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

Output: If keys are defined in convertKeys:

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

If keys are defined in injectKeys:

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

The actions are handled in the following order:

  1. process all injectKeys
  2. process all convertKeys

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

convertKeys: object

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

debug: boolean false

Enable debug logging

injectKeys: object

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

verbose: boolean false

Enable verbose logging

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

unwrap

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

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

Any keys

Output: The input data with the specified key unwrapped.

debug: boolean false

Enable debug logging

key: string

The key to unwrap. Must target a map.

verbose: boolean false

Enable verbose logging

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

wrap

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

Output: The wrapped input data.

debug: boolean false

Enable debug logging

key: string

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

keysToWrap: string[]

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

string
verbose: boolean false

Enable verbose logging

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

Pipeline Filters

aggregate

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

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

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

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

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

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

arrayMax: integer (int64)

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

arrayOutputKey: string "aggregate"

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

convertMapToArray: boolean false

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

debug: boolean false

Enable debug logging

deleteKey: boolean false

Deletes key from the aggregated object(s)

disableEmpty: boolean false

Disable emitting empty aggregates

interval: string

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

key: string mac

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

mapMax: integer (int64)

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

mode: string

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

verbose: boolean false

Enable verbose logging

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

connect

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

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

debug: boolean false

Enable debug logging

id: string

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

interval: string

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

timeout: integer (int64) 10

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

verbose: boolean false

Enable verbose logging

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

discoverDevice

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

The mac field in the input is used to determine which device to add. If the field addDevices is present, then that is expected to be a list of devices to add, and mac is ignored.

Output: Contains all keys from the input

debug: boolean false

Enable debug logging

groupId: string

The Device Group ID to add devices to

verbose: boolean false

Enable verbose logging

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

eddystone

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

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

No configuration is required for this filter.

debug: boolean false

Enable debug logging

ignoreEID: boolean false

Ignore EID advertising payloads

ignoreTLM: boolean false

Ignore TLM advertising payloads

ignoreUID: boolean false

Ignore UID advertising payloads

ignoreURL: boolean false

Ignore URL advertising payloads

verbose: boolean false

Enable verbose logging

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

fwupdate

Updates firmware for devices that do not match the latest firmware. Currently only supports the thingsee sensor by Haltian.

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

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

httpGet

This filter performs a GET request against a specified endpoint. Currently supports either application/json or text/plain response body types.

Output: The filter outputs the server response to the defined outputKey

Interval: string

Specifies request intervals using golang duration strings. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

debug: boolean false

Enable debug logging

headers: object

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

outputKey: string

Defines the outputKey in the json. defaults to "httpResponse"

url: string

The HTTP url to send data Supports text templating.

verbose: boolean false

Enable verbose logging

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

ibeacon

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

Output: All available iBeacon fields and their values.

debug: boolean false

Enable debug logging

uuidFilter: string

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

verbose: boolean false

Enable verbose logging

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

isensor

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

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

No configuration is required for this filter.

debug: boolean false

Enable debug logging

devices: string[]

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

string
verbose: boolean false

Enable verbose logging

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

iterator

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

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

debug: boolean false

Enable debug logging

key: string

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

max: integer (int64) 1000

Maximum number of items to emit from iteration

verbose: boolean false

Enable verbose logging

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

minew

This filter parses minew sensor data to a map

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

debug: boolean false

Enable debug logging

types: string[]

Enabled Sensor Types (available: s1,e6)

string
verbose: boolean false

Enable verbose logging

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

occupancy

This filter provides occupancy state messages from a Haltian Thingsee BLE occupancy sensor. The output can be configured to run in raw mode or regular mode. Raw mode sends all data when received.

Regular mode only sends state changes as necessary. A state change occurs when activity is present for at least 2 of the last 3 minutes. In addition, the current state is sent once every 10 minutes.

Output: 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.

debug: boolean false

Enable debug logging

mode: string regular

The mode in which to operate. Options are 'regular' and 'raw'.

occupiedCount: integer (int64) 3

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

occupiedThreshold: integer (int64) 3

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

unoccupiedCount: integer (int64) 12

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

unoccupiedThreshold: integer (int64) 1

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

updateIntervalSec: integer (int64) 600

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

verbose: boolean false

Enable verbose logging

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

publish

Publish to a Cloud Connector. Publishes the whole event unless payloadKey is specified. Only supports Cloud Connectors that are not topic aware. For topic based publishing, use the publishTopic or publishMultiple filters.

connector: string

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

debug: boolean false

Enable debug logging

format: string json

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

payloadKey: string

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

verbose: boolean false

Enable verbose logging

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

publishMultiple

Publish multiple payloads to a Cloud Connector. Requires an input payload in the payloadsKey that contains a mapping of topics to payloads. For each entry in the map, the given payload will be published to the given topic. Only supports Cloud Connectors that are topic aware. For publishing to a non-topic aware connector, use the publish filter.

connector: string

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

debug: boolean false

Enable debug logging

format: string json

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

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.

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "publishMulti": {
        "type": "publishTopic",
        "config": {
          "connector": "my-cloud",
          "payloadsKey": "topics2payloads"
        }
      }
    }
  }
}

publishTopic

Publish to a Cloud Connector. Publishes the whole event unless payloadKey is specified. Only supports Cloud Connectors that are topic aware. For publishing to a non-topic aware connector, use the publish filter.

connector: string

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

debug: boolean false

Enable debug logging

format: string json

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

payloadKey: string

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

topic: string

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

verbose: boolean false

Enable verbose logging

Example
{
  "service": {
    "filters": {
      "publishOnTopic": {
        "type": "publishTopic",
        "config": {
          "connector": "my-cloud",
          "format": "cbor",
          "payloadKey": "payload",
          "topic": "telemetry"
        }
      }
    }
  }
}

removeDevice

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

The mac field in the input is used to determine which device to remove. If the field removeDevices is present, then that is expected to be a list of devices to remove, and mac is ignored.

Output: Contains all keys from the input

debug: boolean false

Enable debug logging

groupId: string

The Device Group ID to add devices to

verbose: boolean false

Enable verbose logging

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

ruuvi

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

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

No configuration is required for this filter.

debug: boolean false

Enable debug logging

verbose: boolean false

Enable verbose logging

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

throttle

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

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

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

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

count: integer (int64)

Throttle with a counter

debug: boolean false

Enable debug logging

key: string "mac"

Keys to throttle on

maxCount: integer (int64) 1000

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

timeout: string

Throttle with a timeout

verbose: boolean false

Enable verbose logging

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