Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Digital Matter Site
  • Contact Us

Integrating Tags

Written by Matthew Clark-Massera

Updated at October 30th, 2024

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Contact Support
  • Home
  • Bluetooth® Tags, Sensors and Scanners
  • Supported Bluetooth Tags

Table of Contents

Can you integrate Custom Bluetooth® Tags?

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.

So the value of element 2 (manufacturer data) is as follows:
company_LO (0xFF)
company_HI (0x02)
event type (0x01)
event count (0x11000000) (4 bytes float)
(1 byte unknown, maybe peak_rms)
reserved (11 bytes)
 
Have a look at both the images above and check that this makes sense. Note that the event type and event count values are different.
 

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"

 
 

 

 
 
combining merging

Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

  • Bluetooth Supported Sensors
  • Fuel Level Monitoring - Reading Technoton DUT-E S7 and Escort Probes
  • Minew Tag Packet Structure
  • Sentrius Laird BT510 Multi-Sensor

Subscribe to Partner News

Subscribe to our mailing list to receive Digital Matter news, product and tehnical updates, and more.

Subscribe

Copyright © Digital Matter . All Rights Reserved.

Privacy Contact Support

Knowledge Base Software powered by Helpjuice

Expand