BLEBeacon

The Bluefruit nRF52 BSP codebase is undergoing active development based on customer feedback and testing. As such, the class documentation here is incomplete, and you should consult the Github repo for the latest code and API developments: https://goo.gl/LdEx62

The BLEBeacon helper class allows you to easily configure the nRF52 as a 'Beacon', which uses the advertising packet to send out a specifically format chunk of data to any devices in listening range.

The following values must be set in order to generate a valid 'Beacon' packet:

  • Manufacturer ID: A 16-bit value (registered with the Bluetooth SIG!) that identifies the manufacturer.
  • Major: A 16-bit 'Major' number, used to differentiate beacon nodes.
  • Minor: A 16-bit 'Minor' number, used to differentiate beacon nodes.
  • RSSI @ 1M: A signed 8-bit value (int8_t) indicating the RSSI measurement at 1m distance from the node, used to estimate distance to the beacon itself.

These values can either be set in the constructor, or via the individual functions exposed as part of this helper class.

API

BLEBeacon has the following public API:

Download: file
// Constructors
BLEBeacon(void);
BLEBeacon(uint8_t const uuid128[16]);
BLEBeacon(uint8_t const uuid128[16], uint16_t major, uint16_t minor, int8_t rssi);

// Set the beacon payload values
void setManufacturer(uint16_t manfacturer);
void setUuid(uint8_t const uuid128[16]);
void setMajorMinor(uint16_t major, uint16_t minor);
void setRssiAt1m(int8_t rssi);

// Start advertising
bool start(void);
bool start(BLEAdvertising& adv);

In addition to these functions, the BLEAdvertising class (accessible via `Bluefruit.Advertising.*`) exposes the following function to assign Beacon payload to the advertising payload:

Download: file
bool setBeacon(BLEBeacon& beacon);

See the example below for a concrete usage example.

Example

The following example will configure the nRF52 to advertise a 'Beacon' payload:

Download: file
#include <bluefruit.h>

// Beacon uses the Manufacturer Specific Data field in the advertising
// packet, which means you must provide a valid Manufacturer ID. Update
// the field below to an appropriate value. For a list of valid IDs see:
// https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers
// 0x004C is Apple (for example)
#define MANUFACTURER_ID   0x004C 

// AirLocate UUID: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
uint8_t beaconUuid[16] = 
{ 
  0xE2, 0xC5, 0x6D, 0xB5, 0xDF, 0xFB, 0x48, 0xD2, 
  0xB0, 0x60, 0xD0, 0xF5, 0xA7, 0x10, 0x96, 0xE0, 
};

// A valid Beacon packet consists of the following information:
// UUID, Major, Minor, RSSI @ 1M
BLEBeacon beacon(beaconUuid, 0x0001, 0x0000, -54);

void setup() 
{
  Serial.begin(115200);

  Serial.println("Bluefruit52 Beacon Example");

  Bluefruit.begin();
  Bluefruit.setName("Bluefruit52");

  // Manufacturer ID is required for Manufacturer Specific Data
  beacon.setManufacturer(MANUFACTURER_ID);

  // Setup the advertising packet
  setupAdv();

  // Start advertising
  Bluefruit.Advertising.start();
}

void setupAdv(void)
{  
  // Set the beacon payload using the BLEBeacon class populated
  // earlier in this example
  Bluefruit.Advertising.setBeacon(beacon);

  // char* adv = Bluefruit.Advertising.getData();

  // There is no room left for 'Name' in the advertising packet
  // Use the optinal secondary Scan Response packet for 'Name' instead
  Bluefruit.ScanResponse.addName();
}

void loop() 
{
  // Toggle both LEDs every second
  digitalToggle(LED_BUILTIN);
  delay(1000);
}

Testing

If you test with the nRF Beacons application (iOS or Android) you can configure the app to look for the UUID, Manufacturer ID, Major and Minor values you provided, and you should be able to see the beacon, as shown in the two screenshots below:

Make sure that the UUID, Major and Minor values match or the application won't detect your beacon node!
This guide was first published on Mar 22, 2017. It was last updated on Mar 22, 2017. This page (BLEBeacon) was last updated on Sep 17, 2019.