This explains how to read bytes in a Bluetooth advertisement packet such as you would find with a Blue Maestro beacon product. All of Blue Maestro’s beacons come with an API document which sets out the beacon (referred to as an advertisement) data structure, and this post explains how you can easily interpret this.
First, let’s look at the terminology used. An “advertisement packet” is the regular transmission of a Bluetooth Low Energy device when it is not connected to a client. These advertisements are constantly being transmitted, hence the term beacon. Essentially the device is advertising that it is present, has information that may be of relevance and that it may be connectable. An advertisement packet is scanned by a “client”. The device doing the advertising is a “server”.
There is also a “scan response packet”, which is much like an advertisement packet, but it is only transmitted when a client asks for it in an “active scan” by sending a “scan response request” to the server. When a scan response request is received, the scan response packet is sent. This exchange process is shown in the diagram below.
Blue Maestro Bluetooth Sensor and Beacon API and Command Documentation
For each type of Blue Maestro sensor, beacon and/or data logger there is an API and Command Guide that sets out the data structure and commands for the device. For example, the API documentation for the Temperature and Humidity beacon and data logger can be found here. Under the heading “Advertisement Data Structure” you will find the data structure for both the advertisement packet and the scan response packet, as highlighted below.
How to Apply the API Documentation to the Transmissions from the Device
There are numerous tools and ways in which you can view the data from a Blue Maestro Bluetooth device, but here we will talk about one we use ourselves because it is quick and can be done on any available Android or iOS device. Essentially this relies on using one of the excellent apps from Nordic Semiconductor, called “nRF Connect for Mobile”. The Android version can be found here.
Using this app and selecting the Bluetooth device will allow you to reveal the raw data from an advertisement packet. This is a series of bytes which can look daunting at first, but is actually very easy to break down to its constituent parts.
The first thing to recognise is that the advertisement packet and scan response packet is preceded by the hex OxFF. In the image below the two OxFF for each is circled. The Nordic app handily breaks down the advertisement packet below the raw data which helps. The next thing to recognise is that each advertisement packet and scan response packet includes Blue Maestro’s Bluetooth SIG membership number Ox3301. This membership number identifies the device as a Blue Maestro device and confirms that Blue Maestro is a member of the Bluetooth SIG. In the image below you can see the Ox3301 after each OxFF. Now you have your starting point for the data structure and can apply the API document to each following byte accordingly. Let’s do the first couple together.
In the API Document you will see that the first byte after Blue Maestro’s SIG number for the advertisement packet is a uint8_t byte representing the device version number. Looking at the image below you will see this byte is Ox1B. Now using a hex/dec calculator (such as found on a Mac) we can convert this to a decimal number of 27. Viola, you have interpreted your first byte and this means the Blue Maestro device you are looking at is the Pebble Environment Monitor since this is device number 27.
Let’s do the next one. In the API document it says the next byte represents the battery level for the device and is in the form of a uint8_t. This means it comprises one byte and on conversion will represent an unsigned integer. Below this byte is Ox64. Using a hex/dec calculator this represents 100. Viola! The battery level on this device is 100%. Ok, let’s do one more, slightly harder this time.
If you look at the API Document, the next two bytes after the battery level represent the logging interval in seconds. The API document says that on conversion it will represent a uint_16t, that is a 16 bit unsigned integer. Looking at the advertisement packet we see the next two bytes are OxOOOA. Now it is important to understand that Blue Maestro adopts a big endian method of data transmission. This means the most significant byte (or MSB) comes first. If this is not familiar to you, we suggest you read a little more on what this means here. Armed with this knowledge, we can now interpret OxOOOA as 10 in decimal. This means the logging interval for this device is 10 seconds.
Hopefully this puts you on the right path to interpret the rest of the advertisement packet. Now one thing to watch out for is the difference by an “int16_t” and a “uint16_t”. An “int16_t” means the number can be negative, whereas an uint16_t means the number can never be negative. To understand this more we suggest you look here.
We hope you find this small introduction into interpreting advertisement packets from Blue Maestro devices useful. There is a lot to get your head around if you are new to this, but once you do you will be able to look at a series of bytes and interpret it on the fly, just like Neo in the Matrix.