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

4.9.1. 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 an Edge Direct config, and are declared using double curly braces, such as: {{ }} Not every key/value pair supports templating - the ones that do are called out in the configuration documentation.

4.9.2. 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 .. For example: {{ .mac }}.

4.9.3. Templating String Values

Computing strings is the main usage of templates. You might need to generate an MQTT topic based on a MAC address, or transform 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 to add the colons to the MAC address. The string deviceId_ that is outside of the template is prepended to the result of the template string.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "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:

1
2
3
{
  "mac":"ffabffabffab"
}

And after processing:

1
2
3
4
{
  "mac":"ffabffabffab",
  "serverDeviceId":"device_FF:AB:FF:AB:FF:AB"
}

Note that you can also use multiple templates together, so you could concatenate three values like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "rigado-edge-connect": {
    "service": {
      "filters": {
        "injectf": {
          "config": {
            "keyPairs": {
              "multipleTemplates": "{{ .mac }}_{{ Serial }}_{{ Timestamp }}"
            }
          },
          "type": "inject"
        }
      }
    }
  },
  "type": "APP_SET"
}

4.9.4. 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. This can be done with the special return function.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "rigado-edge-connect": {
    "service": {
      "filters": {
        "injectf": {
          "config": {
            "keyPairs": {
              "thisIsBytesNow": "{{ return (\"stringThatShouldBeBytes\" ToBytesBE) }}"
            }
          },
          "type": "inject"
        }
      }
    }
  },
  "type": "APP_SET"
}

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

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

4.10.2. 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)

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

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:map/array/float64/string a DeviceGroup information object about device group a

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

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

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


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

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

Variants:

log: output in int64

logf: output in float64

Output:

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