Templating in Edge Connect Configurations

Many configuration options in Edge Connect provide facilities for templating. This allows for substituting and calculating keys and values at runtime, which can be extremely powerful.

Templating Basics

Templates can be used to calculate values, do simple string manipulations, or to refer to values already in the event map. Templates are used within string keys or values in a configuration, and are declared using double curly braces, (e.g.: {{ }}) Not every key/value pair supports templating; the ones that do are called out in the Configuration.

Accessing Pipeline Data

When possible, template execution has access to the current event map of data flowing through a pipeline. Depending on the type of pipeline, this might be the advertisement data, data from the cloud, or device status events. To access fields in the event map prefix the key with . (e.g: {{ .mac }}).

Templating String Values

Computing strings is the main usage of templates. For example, generating an MQTT topic based on a MAC address or transforming some data from the cloud before it is written to a device.

Here is a basic example that accesses the key mac and passes it to the ToUpper function to uppercase, then passes that value to the AddColonsToMac function. The string deviceId_ that is outside of the template is prepended to the result of the template string.

{
  "rigado-edge-connect": {
    "service": {
      "filters": {
        "injectf": {
          "config": {
            "keyPairs": {
              "serverDeviceId": "device_{{ AddColonsToMac (ToUpper .mac) }}"
            }
          },
          "type": "inject"
        }
      }
    }
  },
  "type": "APP_SET"
}

The relevant values in the event map beforehand:

{
  "mac":"ffabffabffab"
}

And after processing:

{
  "mac":"ffabffabffab",
  "serverDeviceId":"device_FF:AB:FF:AB:FF:AB"
}

Note that multiple templates together can be chained together. Example of concatenating three values:

{
  "rigado-edge-connect": {
    "service": {
      "filters": {
        "injectf": {
          "config": {
            "keyPairs": {
              "multipleTemplates": "{{ .mac }}_{{ Serial }}_{{ Timestamp }}"
            }
          },
          "type": "inject"
        }
      }
    }
  },
  "type": "APP_SET"
}

Templating Non-String Values

Templates are generally used to compute a string. Some filters, such as inject, transform, write, and decode support using templates to return non-string data by using the special return function:

{
  "rigado-edge-connect": {
    "service": {
      "filters": {
        "injectf": {
          "config": {
            "keyPairs": {
              "thisIsBytesNow": "{{ return (\"stringThatShouldBeBytes\" ToBytesBE) }}"
            }
          },
          "type": "inject"
        }
      }
    }
  },
  "type": "APP_SET"
}

Edge Connect Template Functions

The templating in Edge Connect is based on Golang Text Templates. This functionality is extended by incorporating all of the Sprig Template Functions and by adding a wide selection of Edge Connect specific functions, documented below.

String Functions

ToUpper

Arguments

string s to uppercase

Output

string s uppercased

ToLower

Arguments

string s to lowercase

Output

string s lowercased

AddColonsToMac

Arguments

string s to add colons to

Output

string s split with colons every 2 characters

Edge Connect Information Functions

Serial

Arguments

none

Output

string Gateway serial number

ScannerMac

Arguments

none

Output

string MAC address of the Bluetooth radio (radio0) in big endian hexstring, in lowercase with no colons

ECVersion

Arguments

none

Output

string Edge Connect version string

ECHash

Arguments

none

Output

string Edge Connect build hash

ECBuildInfo

Arguments

none

Output

string Edge Connect build information (architecture, os)

Metadata / Utility Functions

DeviceMetadata

Arguments

string d deviceId
string k metadata key to fetch

Output

any type metadata for device d, stored in k

GlobalMetadata

Arguments

string k metadata key to fetch

Output

any type global metadata stored in k

Device

Arguments

none

Functions on returned Device

ID the device ID of this Device
Type the type of this Device
Report deviceReport object describing the current health and state of the device
Props map of key value pairs for each property on this device

Output

object Device object with functions on it

DeviceGroup

Arguments

string a ID of the device group

Functions on returned DeviceGroup

AllIncluded []string of all deviceIds in the Device Group
AllPresent []string of all deviceIds currently present in the Device Group
Report Full details about every device.

Output

object a DeviceGroup object with functions on it

EventType

Arguments

none

Output

object the eventType of the current event flowing through the
pipeline

ReflectInt64

Arguments

number a number to convert to int64. Use this function when the input is of an unusual type, such as a typedef, and normal int64 conversion is not working

Output

int64 the converted number

Timestamp

Arguments

none

Output

Time current UTC time

fromJson, mustFromJson

Arguments

string/[]byte a a json encoded object

Variants

fromJson: errors are ignored
mustFromJson: errors are NOT ignored

Output

map/array/float64/string json data encoded in a

ToMap

Arguments

any type a

Output

map a converted to a map

ToBool

Arguments

any type a

Output

bool a converted to a bool

Byte Array Functions

RandomBytes

Arguments

int n number of bytes to generate

Output

[]byte n-bytes of cryptographically secure generated data

ToHex, ToHexLE, ToHexBE

Arguments

object v value to convert, can be (bool, int/8/16/32/64, uint/8/16/32/64, float32/64, string, []byte)

Variants

ToHex, ToHexLE: output in little endian order
ToHexBE: output in big endian order

Output

string hexstring of v converted to bytes

ToBytes, ToBytesLE, ToBytesBE

Arguments

object v value to convert, can be (bool, int/8/16/32/64, uint/8/16/32/64, float32/64, string, []byte)

Variants

ToBytes, ToBytesLE: output in little endian order
ToBytesBE: output in big endian order

Output

[]byte v converted to bytes

ToBase64, ToBase64LE, ToBase64BE

Arguments

object v value to convert, can be (bool, int/8/16/32/64, uint/8/16/32/64, float32/64, string, []byte)

Variants

ToBase64, ToBase64LE: output in little endian order
ToBase64BE: output in big endian order

Output

string base64 string of v converted to bytes

ByteStringToBytes, ByteStringToBytesLE, ByteStringToBytesBE

Arguments

string s hex or base64 (standard or url-safe) string

Variants

ByteStringToBytes, ByteStringToBytesLE: output in little endian order
ByteStringToBytesBE: output in big endian order

Output

[]byte the bytes encoded by s

NumberToBytesLE, NumberToBytesBE

Arguments

number v a number (int/8/16/32/64, uint/8/16/32/64, float32/64)
int n output size in bytes (1-8)

Variants

NumberToBytesLE: output in little endian order
NumberToBytesBE: output in big endian order

Output

[]byte n-bytes representing v

TypeConvert

Arguments

[]byte/string a item to convert string b output type ("intLE", "uintLE", "floatLE", ...)
number c offset to start conversion from (optional, >0)
number d length to read (optional, >0)

Output

object (the converted output) or error in case of failure

IBeacon

Arguments

[]byte/map a item to convert

Output

object map[string]object with all ibeacon info (same as our ibeacon filter) or error in case of failure

Bitwise Functions

bitwiseAnd

Arguments

uint a an unsigned int (uint/8/16/32/64)
uint64 b mask

Output

varies result of a&b (type of a)

bitwiseOr

Arguments

uint a an unsigned int (uint/8/16/32/64)
uint64 b mask

Output

varies result of a|b (type of a)

bitShift

Arguments

uint a an unsigned int (uint/8/16/32/64)
int b shift count (positive: a<<b, negative: a>>b)

Output

varies result of a<<b, negative: a>>b (type of a)

bitIsSet

Arguments

uint a an unsigned int (uint/8/16/32/64)
uint b bit index to check

Output

bool result of (a & (1 << b)) != 0

Float Functions

number arguments to any of these functions can be one of:

int/8/16/32/64
uint/8/16/32/64
float32/64
numeric string

add, addf

Arguments

number a
number b c d...

Variants

add: output in int64
addf: output in float64

Output

float64 result of a + b + c + d + e

abs,absf

Arguments

number a

Variants

abs: output in int64
absf: output in float64

Output

float64 absolute value of input

sub, subf

Arguments

number a
number b

Variants

sub: output in int64
subf: output in float64

Output

float64 result of a - b

mul,mulf

Arguments

number a
_number b

Variants

mul: output in int64
mulf: output in float64

Output

float64 result of a * b

div,divf

Arguments

number a
number b

Variants

div: output in int64
divf: output in float64

Output

float64 result of a / b

min,minf

Arguments

number a
number b c d...

Variants

min: output in int64
minf: output in float64

Output

float64 result of min(a, b, c, d, e)

max,maxf

Arguments

number a
number b c d...

Variants

max: output in int64
maxf: output in float64

Output

float64 result of max(a, b, c, d, e)

mean,meanf

Arguments

number a
number b c d...

Variants

mean: output in int64
meanf: output in float64

Output

float64 result of mean(a, b, c, d, e)

mode,modef

Arguments

number a
number b c d...

Variants

mode: output in int64
modef: output in float64

Output

float64 result of mode(a, b, c, d, e)

median,medianf

Arguments

number a
number b c d...

Variants

median: output in int64
medianf: output in float64

Output

float64 result of median(a, b, c, d, e)

stddev,stddevf

Arguments

number a
number b c d...

Variants

stddev: output in int64
stddevf: output in float64

Output

float64 result of stddev(a, b, c, d, e)

log, logf

Arguments

number a
number b c d...

Variants

log: output in int64
logf: output in float64

Output

float64 result of ln(a)/ln(b) (log base b of a)