BLEAdvertising

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

'Advertising' is what makes your Bluetooth Low Energy devices visible to other devices in listening range. The radio sends out specially formatter advertising packets that contain information like the device name, whether you can connect to the device (or if it only advertises), etc.

You can also include custom data in the advertising packet, which is essential how beacons work.

The BLEAdvertisingData and BLEAdvertising classes exposes a number of helper functions to make it easier to create well-formatted advertising packets, as well as to use the Scan Response option, which is an optional secondary advertising packet that can be requested by a Central device. (This gives you another 27 bytes of advertising data, but isn't sent out automatically like the main advertising packet.).

This two advertising packets are accessible via the parent AdafruitBluefruit class, calling 'Bluefruit.Advertising.*' and 'Bluefruit.ScanResponse.*' from your user sketches.

For examples of using these helper classes, see any of the examples later on in this guide, since all devices will advertise as part of the startup process.

API

The BLEAdvertisingData class has the following public API:

Download: file
/*------------- Adv Data -------------*/
bool addData(uint8_t type, const void* data, uint8_t len);
bool addFlags(uint8_t flags);
bool addTxPower(void);
bool addName(void);
bool addAppearance(uint16_t appearance);
bool addManufacturerData(const void* data, uint8_t count);

/*------------- UUID -------------*/
bool addUuid(BLEUuid bleuuid);
bool addUuid(BLEUuid bleuuid1, BLEUuid bleuuid2);
bool addUuid(BLEUuid bleuuid1, BLEUuid bleuuid2, BLEUuid bleuuid3);
bool addUuid(BLEUuid bleuuid1, BLEUuid bleuuid2, BLEUuid bleuuid3, BLEUuid bleuuid4);

bool addUuid(BLEUuid bleuuid[], uint8_t count);

/*------------- Service -------------*/
bool addService(BLEService& service);
bool addService(BLEService& service1, BLEService& service2);
bool addService(BLEService& service1, BLEService& service2, BLEService& service3);
bool addService(BLEService& service1, BLEService& service2, BLEService& service3, BLEService& service4);

/*------------- Client Service -------------*/
bool addService(BLEClientService& service);

// Functions to work with the raw advertising packet
uint8_t  count(void);
uint8_t* getData(void);
bool     setData(const uint8_t* data, uint8_t count);
void     clearData(void);

bool     setData(Advertisable& adv_able) { return adv_able.setAdv(*this); }

In addition to API from BLEAdvertisingData, The BLEAdvertising class also has functions that dictate the behavior of advertising such as slow/fast timeout, adv intervals, and callbacks etc...   

Download: file
typedef void (*stop_callback_t) (void);
typedef void (*slow_callback_t) (void);

void setType(uint8_t adv_type);
void setFastTimeout(uint16_t sec);

void setSlowCallback(slow_callback_t fp);
void setStopCallback(stop_callback_t fp);

void setInterval  (uint16_t fast, uint16_t slow);
void setIntervalMS(uint16_t fast, uint16_t slow);

uint16_t getInterval(void);

bool setBeacon(BLEBeacon& beacon);
bool setBeacon(EddyStoneUrl& eddy_url);

bool isRunning(void);

void restartOnDisconnect(bool enable);
bool start(uint16_t timeout = 0);
bool stop (void);

Related Information

  • Generic Access Profile: This page contains the official list of assigned numbers for the 'Data' type field. Data is inserted into the advertising packet by supplying a valid 'data' type, optionally followed by a properly formatted payload corresponding to the selected value.

Example

For practical example code, see the Examples section later on in this guide. The snippet below is provided for illustration purposes, but advertising should be examined in the context of a real use case since it varies from one setup to the next!

Download: file
void setup(void)
{
  // Other startup code here 
  // ...
  
  // Set up Advertising Packet
  setupAdv();

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

void startAdv(void)
{
  // Advertising packet
  Bluefruit.Advertising.addFlags(BLE_GAP_ADV_FLAGS_LE_ONLY_GENERAL_DISC_MODE);
  Bluefruit.Advertising.addTxPower();

  // Include bleuart 128-bit uuid
  Bluefruit.Advertising.addService(bleuart);

  // Secondary Scan Response packet (optional)
  // Since there is no room for 'Name' in Advertising packet
  Bluefruit.ScanResponse.addName();
  
  /* Start Advertising
   * - Enable auto advertising if disconnected
   * - Interval:  fast mode = 20 ms, slow mode = 152.5 ms
   * - Timeout for fast mode is 30 seconds
   * - Start(timeout) with timeout = 0 will advertise forever (until connected)
   * 
   * For recommended advertising interval
   * https://developer.apple.com/library/content/qa/qa1931/_index.html   
   */
  Bluefruit.Advertising.restartOnDisconnect(true);
  Bluefruit.Advertising.setInterval(32, 244);    // in unit of 0.625 ms
  Bluefruit.Advertising.setFastTimeout(30);      // number of seconds in fast mode
  Bluefruit.Advertising.start(0);                // 0 = Don't stop advertising after n seconds  
}
This guide was first published on Mar 22, 2017. It was last updated on Mar 22, 2017. This page (BLEAdvertising) was last updated on May 22, 2019.