1. Description

The Accessory scanner script is a universal script that can acquire data from multiple advertising beacons and set the filtered raw data to a user-defined sensor. This script does not perform the mathematical operations that would need to be applied on the server side.

1.1 Features

Support for the most popular BLE accessories using presets: Accessory Scanner supported integrations
Support for the usual scan filter types and an additional pattern filter. Refer to the table below for more information.
Up to 64-bit user-defined sensors are supported.
Selectable Bluetooth scanning parameters for advanced users.
Script debug message logging of errors, warnings and filtered values through a serial connection. More info on the troubleshooting page.

1.2 Operating principle

Bluetooth scanning is initialised with the scanning parameters and Bluetooth data type filters (Filter type, Filter fields).
Bluetooth messages that pass the HW filtering enter the script BT_FILTER_MATCH callback.
The payload is then analysed to determine if a filter can be applied.
The message is checked to see if the pattern from the filter settings is present.
The data is then extracted from the start byte to the end byte, and the endianness is reversed.
If present, the data mask is applied.
Finally, the filtered value is then set on the sensor.

2. Setting Up

Guide: Accessory Scanner guide

3. Filter Configuration Field Descriptions

3.1 Filter field

Field name	Value range	Description

Field name	Value range	Description
Filter type (required)	-	Selects which Bluetooth data filter type will be applied. Choose one of the following: `BT_SCAN_FILTER_TYPE_NAME` `BT_SCAN_FILTER_TYPE_SHORT_NAME` `BT_SCAN_FILTER_ADDR` `BT_SCAN_FILTER_TYPE_UUID` `BT_SCAN_FILTER_TYPE_APPEARANCE` `BT_SCAN_FILTER_TYPE_MANUFACTURER_DATA` `BT_SCAN_FILTER_TYPE_PATTERN` (This filter is only available from *_01_134 device firmware and 2.2.1** Bluetooth firmware)
Filter (required)	1-31 characters for name and short name filters. 4, 8, 32 characters for UUID filters. 17 characters for MAC address filters (with colon characters). 4 characters for appearance filter. 2-62 characters (31 bytes) for manufacturer data and pattern filters.	Write the filter data according to the selected filter type. A few considerations: Name and short name filter data is written as a string. Other filters are written as hexadecimal string. MAC address filter is written in XX:XX:XX:XX:XX:XX format. For more information, refer to `bt_scan_filter_add()` documentation.
Pattern match (optional)	0-62 characters	Filter searches for this data pattern in the Bluetooth payload. Only if the pattern matches, the filter will be applied and value written to the sensor. This field can be left blank if this operations is not needed, but it is recommended to use together with mismatch scan option. Maximum length is 31 bytes (62 hex string characters). Hex text must be written with no delimiters in the same order as in the raw data in the Bluetooth payload. Default is (empty).
Start byte (required)	1-31	First byte index of the data to be filtered. Must not be higher than the Bluetooth payload length and the end byte.
End byte (required)	1-31	Last byte index of the data to be filtered. Must not be higher than the Bluetooth payload length and not lower than the start byte.
Endianess (required)	-	Choose one of the following: `ENDIANESS_LITTLE` `ENDIANESS_BIG` This choice denotes if the data between the start byte and end byte is in `Little-endian` or `Big_endian` format. If little-endian is selected, the bytes will be swapped. For example, `12 34 56 78` will be changed to `78 56 34 12` and only then the mask will be applied. Default is `ENDIANESS_LITTLE`.
Data mask (optional)	0-62 characters	Data mask to be applied after the endianess operation. Data mask will perform a logical `&(and)` operation to the data. This field can be left blank if this operations is not needed. Default is (empty).
Sensor (required)	-	Select one user-defined sensor that best matches the value type and size. 8 to 64 bit user-defined sensors are supported. Use Sensor descriptions for reference.

3.2 Scan parameters field

Scan parameter name	Description

Scan parameter name	Description
Scan type	Passive scan: Device only receives advertisement indications. Active scan: After receiving advertisement data, device sends a scan requests and receives scan responses. Enabling passive scan is useful if the required data is always in the advertisement indication part and address filter is enabled - this reduces the amount of discardable messages received from the beacons. Default is `Active`.
Scan interval ms	Defines how often the device switches between the Bluetooth channels. It is between the range of 20ms to 10240ms (10.24s), with a step increase of 0.625ms. Default is `60`.
Scan window ms	Defines how long the device is scanning on one Bluetooth channel. It is between the range of 20ms to 10240ms (10.24s), with a step increase of 0.625ms. Default is `30`.
Scan timeout ms	Defines for how long the device is scanning. `0` disables the timeout functionality. Default is `0`.

Note: More information about the scan parameters can be found on the Nordic Dev Academy page about the Advertising process.

4. Other considerations

One MAC address filter takes two filter slots as public and static address filters are added.

BLE Accessory Scanner