BLE Connections
Configuring Edge Connect for Connection Based Devices
This document covers the Bluetooth Low Energy device connection functionality of Edge Connect.
Connections to devices are required when a device does not advertise all available data or when a device requires configuration or other custom actions. There are many reasons for this, but the main goal of Edge Connect is to provide support for connection-oriented data transfer.
Concepts
Edge Connect provides a set of Actions that are performed on a device to which it connects. The Actions performed when connected to a device are setup similar to a Pipeline. Edge Connect can connect, read, write, and collect multiple notifications within a connection session. In addition, BLE security features (Secure Connections and Legacy) Just Works, Pin Code, and OOB Pairing are supported for encrypted data transfer.
Actions
Edge Connect actions are single operations that are performed on a device upon a successful connection. Actions are operations such as read a characteristic or write data to a characteristic.
Connection Sequence
A connection sequence is a set of actions which are performed after a successful device connection. After the connection sequence, the output data from the sequence is accessible for later use.
Many filters are available for use in connection sequences. See the language reference for more details.
Configuring a connection pipeline
To configure Edge Connect to connect to a device, the connect filter is inserted into a pipeline. The connect filter initiates connections immediately or on a configurable interval.
When an advertisement goes through a pipeline and meets the connection criteria, Edge Connect will initiate a connection to that device. At that time, execution through the pipeline is paused until the connection sequence is completed.
Connection Sequence Setup
The connect filter Connect also requires the name of a Connection Sequence to perform upon successful connection. All actions in the sequence are performed in the order specified. Data from the previous action is passed forward to the next action.
Writing Data
The data to write using the write action is specified as a Hexadecimal string. This data is written regardless of the current value of the characteristic to which the write is performed. More options can be found in the Write documentation.
Output
After all actions are executed, the output data is added to the output of the connect filter in the current pipeline. All keys and data are passed on to the next filter in the pipeline. If the Connection Sequence fails for any reason, the key _connectionError is added to the event.
Example Configuration
The following example configuration connects to a Nordic Thingy52 device. It reads several properties from the device and receives some notifications for Acceleration data. In addition, data is written to update the advertising parameters.
{
"settings": {
"rigado-edge-connect": {
"service": {
"actions": {
"read-adv-name": {
"config": {
"characteristic": "ef680101-9b35-4933-9b10-52ffa9740042",
"outputKey": "advName",
"service": "ef680100-9b35-4933-9b10-52ffa9740042"
},
"type": "read"
},
"read-battery": {
"config": {
"outputKey": "battery"
},
"type": "readBattery"
},
"read-fw-version": {
"config": {
"characteristic": "ef680107-9b35-4933-9b10-52ffa9740042",
"outputKey": "fwVersion",
"service": "ef680100-9b35-4933-9b10-52ffa9740042"
},
"type": "read"
},
"set-adv-params": {
"config": {
"characteristic": "ef680102-9b35-4933-9b10-52ffa9740042",
"data": "010200",
"service": "ef680100-9b35-4933-9b10-52ffa9740042"
},
"type": "write"
},
"wait-motion-notif": {
"config": {
"characteristic": "ef680406-9b35-4933-9b10-52ffa9740042",
"interval": "5s",
"mode": "notification",
"outputKey": "motion",
"service": "ef680400-9b35-4933-9b10-52ffa9740042"
},
"type": "wait"
},
"wait-temp-notif": {
"config": {
"characteristic": "ef680201-9b35-4933-9b10-52ffa9740042",
"interval": "5s",
"mode": "notification",
"outputKey": "temperature",
"service": "ef680200-9b35-4933-9b10-52ffa9740042"
},
"type": "wait"
}
},
"cloud": {
"connectors": {
"http": {
"config": {
"method": "post",
"url": "https://testserver.net/test"
},
"type": "http"
}
}
},
"connections": {
"thingy": {
"actions": [
"read-battery",
"wait-temp-notif",
"wait-motion-notif",
"read-fw-version",
"read-adv-name",
"set-adv-params"
]
}
},
"filters": {
"agg": {
"config": {
"interval": "5m",
"key": "mac",
"mode": "map"
},
"type": "aggregate"
},
"connect": {
"config": {
"id": "thingy",
"interval": "5m",
"timeout": 10
},
"type": "connect"
},
"convert": {
"config": {
"convertKeys": {
"advName": "string",
"fwVersion": "hex",
"temperature": "hex"
},
"injectKeys": {
"x": {
"length": 2,
"offset": 0,
"source": "motion",
"type": "intBE"
},
"y": {
"length": 2,
"offset": 2,
"source": "motion",
"type": "intBE"
},
"z": {
"length": 2,
"offset": 4,
"source": "motion",
"type": "intBE"
}
}
},
"type": "typeConvert"
},
"inject": {
"config": {
"keyPairs": {
"serial": "",
"timestamp": "us"
}
},
"type": "inject"
},
"publish": {
"config": {
"connector": "http"
},
"type": "publish"
},
"select": {
"config": {
"keys": [
"mac",
"rssi",
"name",
"battery",
"temperature",
"motion",
"fwVersion",
"advName"
]
},
"type": "select"
},
"wrap": {
"config": {
"key": "testData"
},
"type": "wrap"
},
"wrapAccel": {
"config": {
"key": "accel",
"keysToWrap": [
"x",
"y",
"z"
]
},
"type": "wrap"
}
},
"groups": {
"things": {
"config": {
"include": [
"e98fa57c7a5f",
"e5178bec5303"
]
},
"type": "static"
}
},
"pipelines": {
"pubPipe": {
"filters": [
"connect",
"select",
"convert",
"wrapAccel",
"agg",
"wrap",
"inject",
"publish"
],
"groups": [
"things"
]
}
}
}
}
},
"type": "APP_SET"
}
Updated 3 months ago