Beacon Scanning & Reporting
Overview
Beacon scanning and reporting is a feature that allows you to configure one or multiple Mesh Nodes in a way, so that they scan for specific BLE advertising packets of surrounding beacons and report their BLE address and received signal strength (RSSI) to the gateway. The gateway then publishes each beacon report as an MQTT message to the BlueRange MQTT broker, so that any third party system can consume the measurements for various tasks like beacon detection, asset tracking or mesh diagnosis.
Enabling and configuring beacon scanning
In order to use the Beacon Scanning and Reporting feature in the BlueRange system, you need to configure both the policy of the Gateway and the policy of the Mesh Nodes accordingly. In the Gateway policy you can enable the feature, whereas in the Mesh Node policy different filters for the advertising packets can be configured. These filters will be considered by the Mesh Nodes to effectively reduce the number of advertising packets being processed and transferred over the mesh.
Configuring the Mesh Node Policy
Creating the mesh node policy
If no policy has been applied on the Mesh Nodes yet, you first have to create a new Policy and assign it to all Mesh Nodes that should participate in the beacon scanning. To create a new policy, navigate to > Devices > Configuration and add a new configuration:
Choose an arbitrary name and description, select the Platform Mesh Node and click Create Configuration. Then, add the setting Beacon Scanning to the policy, which enables beacon scanning and gives you to the possibility to configure several filters for scanning, that can be used to reduce the mesh load.
Configuring the beacon scanning filters
RSSI Filter
The RSSI filter is a filter that defines a threshold for the RSSI, so that advertising packets received with a lower RSSI will be dropped. This filter can be useful especially for indoor tracking use cases, where a lower RSSI often tends to be less important in terms of location accuracy due its higher noise.
Report Interval
The report interval defines the number of seconds between two subsequent mesh messages reported by one Mesh Node. A greater report interval often increases the size of the mesh message, as measurements from multiple BLE devices can be batched into one message, which effectively reduces the mesh load. If the Mesh Node receives packets from the same BLE device several times during one report interval, all RSSI measurements from that device will be averaged, which again reduces mesh traffic.
| Due to hardware limitations the number of BLE devices that can be buffered during one report interval is limited. Thus, setting the report interval to a very high value can result in a situation, where some BLE devices have to be dropped. In that case BLE devices received with a higher RSSI will be prioritized over those with a lower RSSI. |
Address Filter
If beacon scanning is only relevant for one specific BLE device (e.g. for beacon detection), one can also make use of the address filter. The (masked) address filter defines the BLE address of the device to be scanned, which is given as a byte sequence of length 6. Additionally one has to define a byte mask, which makes it possible to select only specific bytes that should match. Each byte inside the mask must have a value of either FF (considered) or 00 (unconsidered), depending on whether they should be considered or not.
Data Filter
If only one specific type of advertising packet (e.g. iBeacon or Eddystone) should be scanned, one can use the data filter. The data filter defines a (masked) byte sequence of 1-31 bytes, which are matched against the AdvData part of the BLE advertising packet. If the data filter has a byte length of less than 31 byte, the Mesh Node will scan through each packet and look for any occurance of this byte pattern in the PDU. As with the address filter, additionally a mask has to be defined, which makes it possible to consider only specific bytes in the byte sequence. The mask must have the same length as the data filter, whereas each byte inside the mask must have a value of either FF (considered) or 00 (unconsidered).
Example: iBeacon Filter
To define an iBeacon filter, one can set the data filter to 1A:FF:4C:00:02:15 with a mask of FF:FF:FF:FF:FF:FF. This is due to the fact that Apple’s company identifier is 0x004C and the beacon type for the iBeacon is 0x0215.
Example: iBeacon UUID Filter
If you want to filter one specific iBeacon UUID (e.g. 21322145-B56D-4AB5-9F42-0765AB5455BE), you can encode the UUID into the data filter by setting the byte sequence to 21:32:21:45:B5:6D:4A:B5:9F:42:07:65:AB:54:55:BE and the mask to FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF.
Assigning mesh nodes to the policy
After saving the filter configuration, you can assign the policy to one or multiple Mesh Nodes. Assigning the policy to only one or a subset of Mesh Nodes can be considered as another option of reducing the mesh load. For use cases like indoor tracking, in most cases all Mesh Nodes should have assigned the same policy.
Configuring the Gateway Policy
After setting up the Mesh Node policy, the next step is to enable the "Beacon Scanning and Reporting" feature on the policy of the Gateway. To do this, navigate to > Devices > Gateway > "Your Gateway" > Configuration and click on Edit in the section Features.
Enable the toggle for the feature Beacon Scanning and Reporting and select, whether you want to enable MQTT message batching or not. MQTT message batching can reduce the MQTT broker load considerably, as multiple beacon reports will be batched and compressed into one MQTT message without any information loss and additional delay. MQTT message batching should be used, if a huge message load is expected and your MQTT client does not subscribe to specific messages but is interested in all messasges that are published. In this case, there is no disadvantage of using MQTT message batching. If, however, your MQTT client needs more flexibility in the subscription of beacon reports (e.g. subscribing to messages of specific nodes or beacons), you can disable MQTT message batching. In this case the gateway will publish each beacon report as an individual MQTT message and it is possible to subscribe to a specific subset of MQTT messages (e.g a specific Mesh Node or BLE device).
After you have completed the gateway policy configuration, click Save and then Publish Changes.
After the policy has been published, the gateway will take responsibility for managing the filter configuration of all Mesh Nodes. Therefore, it will regularly check, whether the Mesh Nodes use the correct configuration, and if not, send the configuration to them. This process might take about a minute, after the policy has been applied the first time.
| If for any reason, a Mesh Node rejects the filter configuration, a compliance violation will be shown on that Mesh Node in the BlueRange Portal. In this case please check, if the Mesh Node is available and has the correct firmware version. If the issue still persists, please contact us for more support. |
After all filter configurations have been sent to the Mesh Nodes, the nodes will immediately start scanning and reporting measurements to the Gateway, where they are validated and published to the MQTT broker.
Receiving beacon reports
An MQTT client (e.g. MQTT.fx) can receive the published Beacon Reports, as long as it has authorized access to the MQTT broker. After establishing a connection to the broker, the client can subscribe to one of the MQTT topics, which can be found in the MQTT API Reference:
In case MQTT message batching is disabled, your MQTT client must subscribe to the topic
rltn-iot/{organizationUuid}/{siteUuid}/{deviceUuid}/beacon/{beaconBleAddress}/beaconData.
whereas in case of enabled MQTT message batching, you have to use the following topic:
rltn-iot/{organizationUuid}/{siteUuid}//beacon//beaconBatch
After subscription, your client should receive Beacon Report Messages, as can be seen in the screenshot below:
Disabling beacon scanning
Disabling beacon scanning for specific mesh nodes
To disable the beacon scanning and reporting feature for a specific node, just simply remove the Mesh Node from the Mesh Node policy. Therefore, navigate to > Devices > "Your Mesh Node" > Configuration and click the button "Remove the configuration from this device", which you can find right next to the button "Change configuration".
Disabling beacon scanning on all nodes
To disable the beacon scanning and reporting feature from all Mesh Nodes, you can either remove all Mesh Nodes from the policy or just simply disable the "Beacon Scanning and Reporting" feature toggle on the Gateway Policy. Therefore, navigate to > Devices > Gateway > "Your Gateway" > Configuration, click the Edit button in the section Features, disable the toggle "Beacon Scanning and Reporting", press Save and finally click Publish Changes. After no more than one minute the gateway will send the default filter configuration to all Mesh Nodes and, thus, stop beacon scanning and reporting.