Beacon Scanning & Reporting
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.
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.
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.
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.
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.
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.
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
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
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
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.
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
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
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.
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
whereas in case of enabled MQTT message batching, you have to use the following topic:
After subscription, your client should receive Beacon Report Messages, as can be seen in the screenshot below:
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".
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.