Integrating Tags
Table of Contents
Can you integrate Custom Bluetooth® Tags?
If you require a tag to be integrated into Telematics Guru or require a complex device integration, then contact your local Digital Matter representative. However if you simply want to test a device on OEM, or want to integrate a device onto a platform other than Telematics Guru, then you can integrate the tag using the device's system parameters.
To do so, add the "Bluetooth® User Integrated Tags" parameter. You must also ensure that Bluetooth® has been enabled in the "BLE Global Settings" parameter, and that tag scanning with user integrated tags has been enabled in the tag scanning parameter.
User Tag Type 1:
This is a list of tags that have been integrated by other users using the "Custom Tag Type" field, who have then submitted the instructions to Digital Matter. If this is set to "Custom", then the "Custom Tag Type" is used. This instruction set is used when the "Other Tag Type 1" field in the Tag Scanning parameters is set to "User Integrated Tags"
User Tag Type 2:
This is a list of tags that have been integrated by other users using the "Custom Tag Type" field, who have then submitted the instructions to Digital Matter. If this is set to "Custom", then the "Custom Tag Type" is used. This instruction set is used when the "Other Tag Type 2" field in the Tag Scanning parameters is set to "User Integrated Tags"
User Tag Type 3:
This is a list of tags that have been integrated by other users using the "Custom Tag Type" field, who have then submitted the instructions to Digital Matter. If this is set to "Custom", then the "Custom Tag Type" is used. This instruction set is used when the "Other Tag Type 3" field in the Tag Scanning parameters is set to "User Integrated Tags"
Custom Tag Type:
This is an instruction set for the device to recognise and log data from previously unknown tags. A knowledge of the tag's advertising packet structure is required to use this feature.
Bluetooth® tags send data in a format that allow them to be uniquely identified amongst all other Bluetooth® devices. Each tag type typically sends a 2-4 byte unique code within an advertising element of fixed size, and that is leveraged in this parameter field. You must insert a string in the format:
<Identifier AD Type>,<Identifier AD Length>,<Identifier Index>,<Identifier>,<Log index>,<Log Length>
Where "Identifier AD Type" is the Advertising element type (eg 255 - Manufacturer's Data), "Identifier AD length" is the fixed length of that advertising element, "Identifier Index" is the index within the advertising element for the unique identifier (0 based from the byte after the AD Type), and "Identifier" is a sequence of bytes used for uniquely identifier the tag type. "Log Length" is the number of bytes to log, starting from the "Log Index" which is the index within the whole advertising packet.
Example Custom Tag
The following is an example integration for iBeacons (please note that iBeacons have already been integrated, this is just an example).
According to Apple's specification, this is the advertising packet structure all iBeacons must conform to:
Byte | Description | Value |
---|---|---|
0 | AD Length | 0x02 |
1 | AD Type (Flags) | 0x01 |
2 | Flag Data | 0x06 |
3 | AD Length | 0x1A |
4 | AD Type (Manufacturer Data) | 0xFF |
5 | Apple Company ID[0] | 0x4C |
6 | Apple Company ID[1] | 0x00 |
7 | Proximity Beacon Type[0] | 0x02 |
8 | Proximity Beacon Type[1] | 0x15 |
9-24 | Proximity UUID | 0xnnnn...nn |
25-26 | Proximity Major | 0xnnnn |
27-28 | Proximity Minor | 0xnnnn |
29 | Measured Power | 0xnn |
All iBeacons have a manufacturer data AD Type (0xFF) of fixed length (0x1A), containing the four bytes "4C000215" (Apple company ID and proximity beacon type). Thus this information can be used to uniquely identify iBeacons. The data of importance is the UUID, Major, Minor and Measured Power. The custom tag parameter field can then be broken down as follows:
Custom Tag Entry | Value | Description |
---|---|---|
Identifier AD Type | 255 | 0xFF - Manufacturer Specific Data |
Identifier AD Length | 26 | 0x1A - Manufacturer Specific Data Length |
Identifier Index | 0 | First byte of the manufacturer specific data |
Identifier | 4C000215 | Apple company ID and Proximity Beacon Type |
Log index | 9 | Byte offset of Proximity UUID |
Log Length | 21 | Length of UUID, Major, Minor and Measured Power |
Thus the parameter tab will look like:
You can confirm the device is able to pickup the device in the OEM data capture logs. You will see a log similar to this:
Tag[F] ??? [???] 0xFFFF885C2D3F23AC15E2C56DB5DFFB48D2B060D0F5A71096E000000000E8
The question marks are normal and indicate an unknown tag. The data can be broken down as follows:
Byte | Description | Value |
---|---|---|
0-1 | Generic Tag identifier | FFFF (Always FFFF for the custom tag field) |
2-7 | MAC Address | AC233F2D5C88 (reversed) |
8 | Data Length | 0x15 |
8-n | Data | E2C56DB5DFFB48D2B060D0F5A71096E000000000E8 Which in this case can be broken down as: UUID: E2C56DB5DFFB48D2B060D0F5A71096E0 Major: 0000 Minor: 0000 Power: 0xE8 |