STM32WBA Bluetooth® Low Energy – Beacon

1. Beacon profile

Beacon profile is a proprietary generic attribute profile (GATT) based low-energy profile defined by the Bluetooth^® Special Interest Group.
The beacon profile family can be divided in two main families, the Eddystone (Google) beacon and the iBeacon (Apple).

• Eddystone is an open protocol specification that defines a Bluetooth^® low energy message format for proximity beacon messages. It describes several different frame types that may be used individually or in combination to create beacons that can be used for a variety of applications.
• iBeacon is a protocol developed by Apple and introduced at the Apple worldwide developers conference in 2013. iBeacon is based on Bluetooth^® low energy proximity sensing by transmitting a universally unique identifier (UUID) picked up by a compatible application or operating system.

Beacon is widely used for:

• Advertising:

Sending a packet of information that contains a universally unique identifier (UUID) and used to trigger events specific to that beacon.

• Notification and interaction:

Associated with the art pieces in a museum to encourage further interaction.

• Indoor navigation:

Indoor positioning with beacons falls into three categories that are implementations with many beacons per room, implementations with one beacon per room, and implementations with a few beacons per building.

• Healthcare:

With the device tracking capabilities of Bluetooth beacons, in-home patient monitoring is possible. Movements and activities of a person can be tracked while at home.

Bluetooth beacons are a good alternative to in house camera modules due to their increased level of privacy.

• Tracker:

Various animals, people, or objects finders.

Bluetooth® LE Beacon Profile & STM32WBA

2. Eddystone Protocol Specification

Every Eddystone frame type must contain the following PDU data types:

• The complete List of 16-bit Service UUIDs as defined in the Bluetooth^® Core specification supplement (CSS) v11, part A, § 1.1. The complete List of 16-bit Service UUIDs must contain the Eddystone Service UUID of 0xFEAA. This is included to allow background scanning on iOS devices.

• The Service Data data type, Ibid., § 1.11. The Service Data - 16 bit UUID data type must be the Eddystone Service UUID of 0xFEAA.

The specific type of Eddystone frame is encoded in the high-order 4 bits of the first octet in the Service Data associated with the Service UUID.
Permissible values are:

Eddystone frame type
Frame type High-order 4 bits Byte value UID 0000 0x00 URL 0001 0x10 TLM 0010 0x20 EID 0011 0x30 RESERVED 0100 0x40

The 4 low-order bits are reserved for future use and must be 0000.

Information

Note: Although the core Bluetooth data type are defined in the standard as little-endian, Eddystone's multi-value bytes defined in the Service Data are all big-endian

An example frame type may look like:

Eddystone frame example
Byte Offset Value Description Data Type 0 0x02 Length Flags. CSS v11, Part A, § 1.3 1 0x01 Flags Data Type value 2 0x06 Flag Data 3 0x03 Length 4 0x03 Complete list of 16-bit Service UUIDs data type value 5 0xAA 16-bit Eddystone UUID 6 0xFE ... 7 0x?? Length Service Data. Ibid. § 1.11 8 0x16 Service Data type value 9 0xAA 16-bit Eddystone UUID 10 0xFE ...

With subsequent bytes comprising the frame-specific Service Data.

The individual frame types are listed below.

2.1. Eddystone-UID

The Eddystone-UID frame broadcasts an opaque, unique 16-byte beacon ID composed of a 10-byte namespace and a 6-byte instance.
The beacon ID may be useful in mapping a device to a record in external storage.
The namespace portion of the ID may be used to group a particular set of beacons, while the instance ID identifies individual devices in the group.
The division of the ID into namespace and instance components may also be used to optimize Bluetooth® Low Energy scanning strategies. For example, it can filter only on the namespace.

2.1.1. Frame specification

The UID frame is encoded in the advertisement as a Service Data block associated with the Eddystone service UUID. The layout is:

Eddystone UID advertising packet
Length Type Description Value 2 0x01 Flags GeneralDiscoverable, BrEdrNotSupported 3 0x03 Eddystone UUID 0xAAFE 16 0x16 Service Data See table below

Eddystone UID Service advertising data
0 1 2 3-12 13-18 19 20 Length Frame type Ranging Data NID[0..9] BID[0..5] RFU RFU 0x15 Value = 0x00 Calibrated TX power at 0 m '10-byte namespace 6-byte instance Reserved for future use, must be 0x00 Reserved for future use, must be 0x00

2.1.2. Field notes

• The length of this frame is fixed and takes up the full 31 bytes of the ADV packet.
  The value of the Service Data length byte must be 0x17.
  Existing UID implementations that truncate the frame to omit the RFU bytes will use 0x15, but in future should include the RFU bytes and the full length.
• The ranging data is the TX power in dBm emitted by the beacon at 0 meters.
  Note that this is different from other beacon protocol specifications that require the TX power to be measured at 1 m.
  The value is an 8-bit integer as specified by the TX power Level Characteristic and ranges from -100 dBm to +20 dBm to a resolution of 1 dBm.
  See Transmit Power below for more details.
• The 10-byte namespace ID component is a unique self-assigned beacon ID namespace.
  See UID Construction below for recommendations on generating this unique namespace.
• The 6-byte instance ID component is unique within the namespace.
  See UID Construction below for recommendations on ensuring beacon ID uniqueness.

2.1.3. TX powers

TX power is the received power at 0 meters measured in dBm. The value may range from -100 dBm to +20 dBm at a resolution of 1 dBm.
The best way to determine the precise value to put into this field is to measure the actual output of your beacon from 1 meter away and then add 41 dBm to that. 41dBm is the signal loss that occurs over 1 meter.

2.1.4. UID construction

An Eddystone-UID beacon ID is 16 bytes long, consisting of a 10-byte namespace component and 6-byte instance component.
The namespace is intended to ensure ID uniqueness across multiple Eddystone implementers and may be used to filter on-device scanning for beacons.
Two methods for generating a unique 10-byte namespace are recommended:

• a truncated hash of your FQDN:
  Produce a SHA-1 hash of a fully qualified domain name that you own.
  If you desire additional obscurity and/or additional namespaces, you may wish to use a random subdomain under this FQDN.
  Select the first 10 bytes from that hash.
• an elided UUID:
  Generate a version 4 UUID then remove bytes 5 - 10 (inclusive).
  For example: from this UUID: 8b0ca750-e7a7-4e14-bd99-095477cb3e77 remove these bytes: e7a7-4e14-bd99.
  This produces the following namespace: 8b0ca750095477cb3e77.
  This option may be useful if you interleave Eddystone-UID with other UUID-based frame formats.
  It allows you to relate your Eddystone-UID namespace to the UUID in the other frames by deriving one from the other.

2.1.5. Instance ID

The 6-byte instance portion of the Eddystone-UID beacon ID may be assigned via any method suitable for your application.
They may be random, sequential, hierarchical, or any other scheme.

2.2. Eddystone-URL

The Eddystone-URL frame broadcasts a URL using a compressed encoding format in order to fit more within the limited advertisement packet.
Once decoded, the URL can be used by any client with access to the internet.
The Eddystone-URL frame forms the backbone of the physical web, an effort to enable frictionless discovery of web content relating to one’s surroundings. Eddystone-URL incorporates all of the learnings from the UriBeacon format from which it evolved.

2.2.1. Frame specification

The UID frame is encoded in the advertisement as a Service Data block associated with the Eddystone service UUID. The layout is:

Eddystone URL advertising packet
Length Type Description Value 2 0x01 Flags GeneralDiscoverable, BrEdrNotSupported 3 0x03 Eddystone UUID 0xAAFE 16 0x16 Service Data See table below

Eddystone URL Service advertising data
0 1 2 3 4-20 Length Frame type Ranging data URL scheme Encoded URL 0x04-0x15 Value = 0x10 Calibrated TX power at 0 m Encoded scheme prefix Length 1-17

2.2.2. TX powers

TX power is the received power at 0 meters measured in dBm. The value may range from -100 dBm to +20 dBm at a resolution of 1 dBm.
The best way to determine the precise value to put into this field is to measure the actual output of your beacon from 1 meter away and then add 41 dBm to that. 41dBm is the signal loss that occurs over 1 meter.
The value is a signed 8 bit integer as specified by TX power level bluetooth characteristic.
Examples

• The value 0x12 is interpreted as +18dBm
• The value 0xEE is interpreted as -18dBm

2.2.3. URL scheme prefix

The URL scheme prefix byte defines the identifier scheme, an optional prefix and how the remainder of the URL is encoded.

Eddystone URL scheme prefix
Decimal Hex Expansion 0 0x00 http://www. 1 0x01 https://www. 2 0x02 http:// 3 0x03 https://

2.2.4. Eddystone-URL HTTP URL encoding

The HTTP URL scheme is defined by RFC 1738 and is used to designate internet resources accessible using HTTP (HyperText Transfer Protocol).
The encoding consists of a sequence of characters. Character codes excluded from the URL encoding are used as text expansion codes. When a user agent receives the Eddystone-URL the byte codes in the URL identifier are replaced by the expansion text according to the table below.

Eddystone-URL HTTP URL encoding
Decimal Hex Expansion 0 0x00 .com/ 1 0x01 .org/ 2 0x02 .edu/ 3 0x03 .net/ 4 0x04 .info/ 5 0x05 .biz/ 6 0x06 .gov/ 7 0x07 .com 8 0x08 .org 9 0x09 .edu 10 0x0a .edu 11 0x0b .net 12 0x0c .info 13 0x0d .gov 14..32 0x0e..0x20 Reserved For Futur Use 127..255 0x7f..0xff Reserved For Futur Use

Information

Note: URLs are written only with the graphic printable characters of the US-ASCII coded character set. The octets 00-20 and 7F-FF hexadecimal are not used. See “Excluded US-ASCII characters” in RFC 2936. Range 07-13 define the same top level domains as 00-06 without a "/".

2.3. Eddystone-TLM

The Eddystone-TLM frame broadcasts telemetry information about the beacon itself such as battery voltage, device temperature, and counts of broadcast packets.
Eddystone beacons may transmit data about their own operation to clients.
This data is called telemetry and is useful for monitoring the health and operation of a fleet of beacons.
Since the Eddystone-TLM frame does not contain a beacon ID, it must be paired with an identifying frame that provides the ID, either of type Eddystone-UID or Eddystone-URL.
See Interleaving Telemetry for details. TLM frames may be broadcast either in the clear, like UID and URL frames, or, when a beacon has been configured as Eddystone-EID, encrypted with the identity key set during the EID configuration.
When broadcast in the clear there is no message integrity validation and you should design your applications to be tolerant of the open nature of such a broadcast.

2.3.1. Unencrypted TLM frame specification

See Unencrypted TLM frame
The TLM frame is encoded in the advertisement as a Service Data block associated with the Eddystone service UUID. The layout is:

Eddystone TLM advertising packet
Length Type Description Value 2 0x01 Flags GeneralDiscoverable, BrEdrNotSupported 3 0x03 Eddystone UUID 0xAAFE 16 0x16 Service Data See table below

Eddystone Unencrypted TLM Service advertising data
0 1 2 3-4 5-6 7-10 11-14 Length Frame type Version VBATT[0..1] TEMP[0..1] ADV_CNT[0..3] SEC_CNT[0..3] 0x0F Value = 0x20 TLM version, value = 0x00 Battery voltage, 1 mV/bit Beacon temperature Advertising PDU count Time since power-on or reboot

2.3.2. Field notes

• The length of this frame is fixed and must be truncated after the "time since power-on" bytes.
  The value of the Service Data Length byte must be 0x11.
• TLM version allows for future development of this frame type.
  At present the value must be 0x00.
• Battery voltage is the current battery charge in millivolts, expressed as 1 mV per bit.
  If not supported (for example in a USB-powered beacon) the value should be zeroed.
• Beacon temperature is the temperature in degrees Celsius sensed by the beacon and expressed in a signed 8.8 fixed-point notation.
  If not supported the value should be set to 0x8000, -128 °C.
• ADV_CNT is the running count of advertisement frames of all types emitted by the beacon since power-up or reboot, useful for monitoring performance metrics that scale per broadcast frame.
  If this value is reset (for example, on reboot), the current time field must also be reset.
• SEC_CNT is a 0.1 second resolution counter that represents the time since beacon power-up or reboot.
  If this value is reset (for example, on a reboot), the ADV count field must also be reset.

2.3.3. Interleaving Telemetry

Telemetry frames should be interleaved with an identifying frame type (for example, Eddystone-UID or Eddystone-URL).
The TLM frame depends on the client to associate it with the identifying frames via the device address (since no beacon ID exists in the TLM frame).
Thus it is important that a beacon that rotates or randomizes its device address uses the same device address for some period that allows for multiple ID frames and multiple TLM frames to be broadcast from the same device address.
The user may decide to interleave one TLM frame for each ID frame, or use some lower ratio depending on how critical the TLM data is for your application.<fr> For example, if your application is using the TLM for fleet management, it may be satisfied receiving one TLM frame per day, so your beacons deployed in a high traffic area may broadcast TLM only once per minute or longer, giving a high probability that a client receives the TLM frame and transmits it to your service once per day.
In a low-traffic environment such an application may require a higher TLM rate.
Finally, if your application uses TLM to (for example) supply up-to-the-minute runtime status information to an end user, you may wish to interleave TLM with ID frames 1 to 1.

2.4. Eddystone-EID

The Eddystone-EID frame broadcasts an encrypted ephemeral identifier that changes periodically at a rate determined during the initial registration with a web service.
The broadcast ephemeral ID can be resolved remotely by the service with which it was registered, but to other observers appears to be changing randomly.
This frame type is intended for use in security and privacy-enhanced devices.

3. iBeacon protocol specification

See iBeacon

iBeacon advertising data

iBeacon protocol broadcasts a serial ID number that is then used by the corresponding app in the user’s smartphone to return results.
iBeacon features a standardized format for Bluetooth® Low Energy advertising in which, every data packet contains 4 pieces of information:

• unique universal identifier (UUID): It is a beacon’s general information.
  For example, the name of the person/business that the beacon belongs to.
• Major: the beacon’s spatial information.
  For example, this beacon is employed in the aisles of store #9.
• Minor: a more detailed or minute information.
  For example, this beacon is located in aisle 2.
• TX power: TX power refers to the strength of the signal that is exactly 1 meter from the device.
  TX is used to determine the proximity of devices from the beacon.

The UID frame is encoded in the advertisement as a Service Data block associated with the iBeacon service UUID. The layout is:

iBeacon advertising packet
Length Type Description Value 2 0x01 Flags GeneralDiscoverable, BrEdrNotSupported 26 0xFF Manufacturer data See table below

iBeacon manufacturer advertising data
0 1 2-3 4 5 6-21 22-23 24-25 26 Length Manufacturer ID Company Sub-Type Sub-Type length UUID 'Major value Minor value TX power 0x1A 0xFF 0x004C Apple, Inc 0x02 0x15 General information Spatial information Detailed or minute information Calibrated TX power at 1 m

4. Requirements

4.1. Software and Hardware requirements

For software and hardware requirements refer to STM32WBA Build BLE Project wiki page.

4.2. Collector applications compatible

The STM32CubeWBA Beacon project is compatible with the following scanner:

• STBLEToolbox

5. STM32WBA Beacon example description

5.1. Project directory

The "BLE_Beacon" application is available by downloading STM32CubeWBA MCU package.

Refer to How to Build a Bluetooth® Low Energy project wiki page for project directory information.

5.2. Project description

5.2.1. Structure

Software project structure with the most important parts:

Beacon project structure
Main applicative part files Services management Bluetooth® Low Energy libraries Link Layer System integration files WARNING: Do not modify the files in the middleware folder

5.2.2. Application initialization

As the beacon application does not have any GATT Service or GATT characteristics, the beacon application just advertises the corresponding beacon data (Eddystone UID, Eddystone URL, Eddystone TLM or iBeacon).
The advertised beacon data can be chosen in the configuration file app_conf.h in the following part:

/* USER CODE BEGIN Specific_Parameters */

/**
 * Beacon selection
 * Beacons are all exclusive
 */
#define CFG_EDDYSTONE_UID_BEACON_TYPE   (1<<0)
#define CFG_EDDYSTONE_URL_BEACON_TYPE   (1<<1)
#define CFG_EDDYSTONE_TLM_BEACON_TYPE   (1<<2)
#define CFG_IBEACON                     (1<<3)

#define CFG_BEACON_TYPE                 (CFG_EDDYSTONE_URL_BEACON_TYPE)

For Eddystone UID:

#define CFG_BEACON_TYPE                 (CFG_EDDYSTONE_UID_BEACON_TYPE)

For Eddystone URL:

#define CFG_BEACON_TYPE                 (CFG_EDDYSTONE_URL_BEACON_TYPE)

For Eddystone UID with Eddystone TLM:

#define CFG_BEACON_TYPE                 (CFG_EDDYSTONE_TLM_BEACON_TYPE)

For iBeacon:

#define CFG_BEACON_TYPE                 (CFG_IBEACON)

6. Beacon collector - smartphone application

6.1. STBLEToolbox application

Once the Bluetooth® Low Energy Beacon application is installed on the STM32WBA platform, launch the STBLEToolbox smartphone application. The application starts scanning and enables displaying advertisement data.

Bluetooth® Low Energy Beacon application on STBLEToolbox