User Tools


Beacons and Advertising

BLE Advertising Overview

A BLE peripheral device can advertise to allow detection and connection by BLE central devices.

Advertising is governed by the Bluetooth GAP (Generic Access Profile) specification. Peripheral devices advertise to a Central device. Typically Peripheral devices have limited resources and use low power, while Central devices are more powerful and provide an interface for human interaction.

For GAP documentation, see https://www.bluetooth.org:

  • Bluetooth Core Standard version 4, Vol 3, Part C, particularly sections 8 and 11
  • Core Specification Supplement, Part A

The Bluetooth GAP specification limits advertising data to two packets:

  • Advertising Data payload
  • Scan Response payload

For details of the format see Advertising Data Format below.

Advertising with TruConnect

The TruConnect device acts as the Peripheral.

TruConnect supports:

To start your TruConnect device advertising:

  • Set the type of beacon and the required fields in the beacon. See bl v d f
  • Set the content for the type of advertising configured. See:
  • Start advertising. See adv

By default, a TruConnect device advertises the TruConnect Service ID and the default module name. See UUID and Name for details.

Advertising Commands and Variables

Commands supporting BLE advertising are:

  • adv - advertise in high mode or low mode, or turn advertising off

Variables supporting BLE advertising are:

  • Advertising mode and settings
    • bl t a — advertising power
    • bl v h d — advertising high mode duration
    • bl v h i — advertising high mode interval
    • bl v l d — advertising low mode duration
    • bl v l i — advertising low mode interval
    • bl v m — advertising mode
  • Advertising data
  • Beacon settings:
    • bl v d b — advertising data, generic beacon content
    • bl v d f — advertising data format
    • bl v d g — advertising data, GPIO mask
    • bl v d i — advertising data, iBeacon content

Advertising Data Format

The peripheral device transmits an advertising packet 31 octets in length. The central device scans and receives the advertising packet. The central can then request additional information. In response the peripheral sends a scan response packet, 31 octets in length.

The advertising packet and the scan response packet have the same general format.

The BLE advertising packet and scan response packet both consist of one or more structures of the form:

Length Type Content
1 octet 1 octet Length - 1 octets

Length specifies the length of the data, not including the Length octet. The data consists of an octet specifying the data type, followed by the data content.

Length = Content_length + Type_length = Content_length + 1

Unused octets are set to 00.

The diagram below shows the general structure of the advertising packet and the scan response packet.

Source: Bluetooth Core standard v4, Vol 3, Part C - Generic Access Profile, Section 11, Advertising and Scan Response Data Format

Advertising Format Examples

In the example tables, the top row shows the octets in the advertising packet or scan response packet, with data in hexadecimal notation. The Least Significant Byte (LSB) is on the left. Unless otherwise noted, data is sent in little-endian order. Some proprietary formats package the data in big-endian order.

The bottom line shows the interpretation, with numbers in decimal notation. Configurable parts of the advertising packet are emphasised.

Generic Beacon

Set BLE advertising format bl v d f to b:

set bl v d f b

You can then supply data in any format for the 31 octets of the beacon. You can use the generic beacon to advertise in any format, including open formats such as:

Example Generic Beacon

A typical generic beacon starts with a flags structure, followed by a manufacturer specific data structure. The first three octets of the manufacturer data structure specify Manufacturer type and the manufacturer ID. This leaves 24 octets for the remaining free format data.

02 01 05 1B FF 4602 0011…EEFF0011…6677
Length:2 Type:FlagsFlags Length:27 octets Type:Mfr Mfr ID generic beacon data:24 octets max

The generic data, including the leading two octet Manufacturer ID, is delivered in the order specified in the bl v d b variable argument, with the leftmost byte of the argument representing the least significant byte. To send the example advertising data above, set bl v d b as follows:

set bl v d b 0201051bff460200112233445566778899aabbccddeeff0011223344556677

iBeacon

Set BLE advertising format bl v d f to i:

set bl v d f i
02 01 05 1A FF 4C00 02 15E2C56DB5…96AA 0001 0002 B9
Length:2Type:FlagsFlags Length:26 octets Type:Mfr Apple IDProximity beacon typeRemaining length:21 octetsUUID:16 octetsMajorMinorTx Power

The iBeacon format is essentially a generic data beacon with a proprietary internal format. It uses 30 octets of the possible 31.

The configurable part of the iBeacon content is UUID, Major, and Minor, specified in the bl v d i variable. The setting corresponding to the example above is:

set bl v d i e2c56db5-dffb-48d2-b060-d0f5a71096aa,0001,0002

Note: iBeacon is a proprietary format and does not follow the general BLE specification requiring little-endian order. Within the iBeacon data, the UUID is displayed in big-endian order (Most Significant Byte (MSB) at the left).

The last byte of the iBeacon is a single-octet Tx Power. This is 2's complement format, representing RSSI measured at 1 metre from the device, calculated by TruConnect based on the TruConnect device's antenna and settings. The Tx power value B9 in the example translates to -71 dBm.

UUID and Name

This is the default advertising mode for a TruConnect device.

Set BLE advertising format bl v d f to s:

set bl v d f s
02 01 05 11 07 0011…EEFF 09 09 0011…6677
Length:2Type:FlagsFlagsLength:17Type:UUIDUUID: 16 octetsLength:9Type:NameName:8 octets

UUID and name are determined as follows:

Value Associated Variable Default Notes
UUID bl s u 175f8f23-a570-49bd-9627-815a6a27de2a TruConnect Service ID
- see TruConnect Service and Characteristics
name sy d n AMS-#### #### stands for the last 4 digits of the BD_ADDR
- see bl a. Example: AMS-0DC4

Note: according to the BLE specification, the Service UUID appears in the advertising response as a hex number in little-endian order, with LSB first. On the TruConnect terminal, and typically in other displays for human readers, the UUID is shown with the least significant byte at the right. For example, the TruConnect Service UUID appears as follows:

On the TruConnect terminal, LSB at right:

> get bl s u
175f8f23-a570-49bd-9627-815a6a27de2a

In the advertising packet, LSB at left:

2ADE276A5A812796BD4970A5238F5F17

The name is a string of ASCII character codes, and appears in the advertisement in the same order as the string. For example, the name AMS-ODC4 appears as 414d532d30444334.

The entire advertisement, using the TruConnect Service ID and example name above, with LSB at left, appears as:

02010511072ade276a5a812796bd4970a5238f5f170909414d532d30444334

UUID, Name and GPIOs

Set BLE advertising format bl v d f to s,g:

set bl v d f s,g

The 31-octet advertising packet, containing flags, UUID and Name is the same as for UUID and Name above.

The GPIO data structure follows in the scan response packet, in the format:

06 FF 4602 01 4002
Length:6 Type:MfrMfr IDSubtype: GPIO GPIO data

In the example, the Mfr (Manufacturer) type and ID are as described in Supplement to the Bluetooth Core Specification, Part A, Data Types Specification Section 1.4, Manufacturer Specific Data.

The Subtype:GPIO is a proprietary format determined by ACKme networks.

The GPIO data is shown in little-endian format, and GPIOs are numbered from GPIO 0 (bit 0) to GPIO 15 (bit 15).

The value 4002 in this example corresponds to the bits (shown with bit 0 at the right here): 0000 0010 0100 0000. That is, GPIO 6 and GPIO 9 are set to 1, and all others are 0.

To control which GPIOs appear in the GPIO data, use the bl v d g variable to set the GPIO mask. The default is FFFF, with no GPIOs masked.

For example, to mask all but GPIO 6 and GPIO 9 (Button 1 and Button 2 on the Wahoo), use the example above, which in hex, with LSB at right is 0240:

set bl v d g 0240

The result in the scan response GPIO data appears with LSB first, so when both GPIO 6 and GPIO 9 are high the GPIO data is 40 then 02.

Note: GPIOs must be set to STDIO function for their levels to appear in the GPIO scan response packet. See Peripherals for details on setting GPIO function.

Eddystone Beacons

Eddystone is an open beacon format from Google that works with Android and iOS. See https://github.com/google/eddystone

You can construct Eddystone beacons using the generic beacon type.

Set BLE advertising format bl v d f to b:

set bl v d f b

Eddystone Beacon Preamble

Eddystone beacons begin with a preamble containing two structures:

02 01 05 03 03 AAFE
Length:2Type:FlagsFlagsLength:3 octetsType:Complete list of 16 bit service UUIDs Eddystone UUID

Only the value of the flags can be modified.

The final service data structure depends on the frame type: URL, UID or TLM.

Eddystone URL Beacon

See https://github.com/google/eddystone/tree/master/eddystone-url

The Eddystone URL Beacon begins with the preamble above.

The final service data structure has the following layout:

0E 16 AAFE 10 EB 02 73656E736F7273 07 00…00
Service Data Length:14 octetsType: Service Data Eddystone UIDFrame type: Eddystone-URLTx PowerURL scheme: 'http://'' URL body: 'sensors' domain: '.com' code pad to 31 octets

To set the value of bl v d b to the values in the above example URL beacon:

set bl v d b 0201050303aafe0e16aafe10eb0273656E736F727307000000000000000000

With an app that can decode Eddystone beacons, the URL reported for the above example is http://sensors.com

The codes for URL scheme and domain are decoded into the expanded text when encountered. You can refer to domains not included in the encoded list by spelling them out in full. Ensure the Service Data Length is adjusted to truncate at the end of your URL. For example:

0C 16 AAFE 10 EB 02 61636B2E6D65 00…00
Service Data Length:12 octetsType: Service Data Eddystone UIDFrame type: Eddystone-URLTx PowerURL scheme: 'http://'' URL body: 'ack.me' pad to 31 octets

corresponding to the TruConnect command:

set bl v d b 0201050303aafe0c16aafe10eb0261636b2e6d650000000000000000000000

The URL reported for the above example is http://ack.me

Eddystone UID Beacon

See https://github.com/google/eddystone/tree/master/eddystone-uid

The Eddystone UID Beacon begins with the preamble above.

The final service data structure has the following layout:

17 16 AAFE 00 EB 00112233445566778899 000000000001 0000
Service Data Length:23 octetsType: Service Data Eddystone UUIDFrame type: Eddystone-UIDTx Power UID namespace UID instance Reserved octets must be zero

The UID namespace and UID instance are in big-endian order.

To set the value of bl v d b to the values in the above example URL beacon:

set bl v d b 0201050303aafe1716aafe00eb001122334455667788990000000000010000

With an app that can decode Eddystone beacons, the reported UID namespace for the above example is 00112233445566778899, and the reported UUID instance is 000000000001.

Eddystone TLM Beacon

See https://github.com/google/eddystone/tree/master/eddystone-tlm

The Eddystone TLM Beacon begins with the preamble above.

The final service data structure has the following layout:

11 16 AAFE 20 00 04b0 0c4D 00004e20 00035a0c00…
Service Data Length:17 octetsType: Service Data Eddystone UUIDFrame type: Eddystone-TLMTLM VersionVBATT:1.2V TEMP:12.3 deg C ADV_CNT:20,000 SEC_CNT: 6 hrs, 6 mins, 6 secs6 zero octets

Data types and formats:

Data Type Description Format Example
VBATT Battery voltage 1mV per bit
if not supported: 0x0000
1.2V = hex(1200) = 0x04b0
TEMP Beacon temperature 8.8 fixed point notation
if not supported: 0x8000
12.3 degrees:
MSB:hex(12)=0x0c
LSB:hex(0.3 * 256)=0x4D
ADV_CNT Advertising PDU (Protocol Data Unit) count. Integer hex(20000) = 0x4e20
SEC_CNT Time since power-on or reboot 0.1 seconds per bit. 6 hrs, 6 mins, 6 secs = hex(21966 * 10) = 0x035a0c

Note: All data types are in big-endian order.

The Eddystone TLM beacon should be sent directly after an Eddystone UID or Eddystone URL beacon, so the telemetry data can be associated with an identifier. In the Google Eddystone TLM documentation this is called interleaving.

For example, set bl v d b to the Eddystone URL beacon above, then after a few seconds set bl v d b to the values in the above example Eddystone TLM as follows:

set bl v d b 0201050303aafe1116aafe200004b00c4d00004e2000035a0c000000000000

Note: To be of value, Eddystone TLM beacons must be created dynamically. This requires an MCU or other controller device to assemble the beacon from data read instantaneously from the TruConnect module, and program the TruConnect device to send the beacon using the set bl v d b command.

AltBeacon

AltBeacon is an open protocol for proximity beacon advertisements.

See http://altbeacon.org/

You can construct AltBeacon advertisements using the generic beacon type.

Set BLE advertising format bl v d f to b:

set bl v d f b

The full AltBeacon PDU (Protocol Data Unit) starts with the standard 3-octet flags structure, and has the following layout

02 01 05 1B FF 4602 BEAC 001122…EEFF 0001 0002 EB 23
Length:2Type:FlagsFlagsLength:27Type:MfrMfr IDAltBeacon codeUUID: 16 octets MajorMinorRSSIManufacturer Special

To send the above AltBeacon advertisement, set bl v d b as follows:

set bl v d b 0201051bff4602beac00112233445566778899aabbccddeeff00010002eb23