Integrating Tags
Written by Matthew Clark-Massera
Updated at October 30th, 2024
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. It is important to use the correct “Log Length” and “Log Index” as there is a 26-byte limit on data transmission.
Example Custom Tag - iBeacon
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 |
Example Custom Tag - Real World Example
Above is the raw data from a custom tag, found in via a mobile scanning app.
This is made up of 3 elements. In each element, the first byte is the length of the rest of the element, the second byte is the data type, and the rest is the value.
The “Details” tab in the image above makes this easy to see. Note that the the raw payload is in hex, so a length of 20 for element 2 is 14 in the payload.
Element Types
The first element type will always be type 0x01. The value (in this case 6) tells you information about the beaconing.
The second element has type 0xFF, or 255. his is the custom manufacturer data type. The value can be anything. We often use some ID value in here to identify the tag. This also usually contains the data of interest. Just from the raw data from the image above, we don't know what these values mean.
The third element in this case is type 0x09 which is the “name”. The value 0x546167 says "Tag" if you use a hex to ascii convertor. You will see this name if you scan using your phone.
Manufacturing Data
In this case we are told what the manufacturer data is, because of some additional information provided by the tag provider.
Digital Matter Custom String
This string defines the identifier of the tag we want using the 'Identifier' fields. And also defines the data of the tag using the last 2 'Log' fields.
The Identifier could be from any of the advertising data (AD) elements.
In this case, using the (0xFF, 0x02) company_LO/HI bytes as the identifier might make the most sense. Assuming that this isn't likely to change between the tags of interest.
Another option for the ID could be the name 'Tag' in AD element 3. But that is quite generic and might catch unwanted tags.
Identifier AD Type = 255 (this identifier is part of element 2). Basically says the ID is in the manufacturing data.
Identifier AD Length = 20 (length of element 2)
Identifier Index = 0 (index of the identifier within the value of element 2. The Identifier is at the start of the manufacturing data)
Identifier = FF02 (in hex)
Log Index = 7 (index starts from the start of all the data. Not just the manufacturer element). Essentially this is all of the “data” that you will see logged in the tag list.
Log Length = 17 (length of data that we want to record
Overall, the Custom String that you would want to enter above would be: "255,20,0,FF02,7,17"
Quiz! What would the custom string be if we wanted to use the name ‘tag’ as the identifier?
Answer: "9,4,0,546167,7,17"
