nrf51822教程系列 第二课 nrf51822 softdevice GAP Advertising

Bluetooth Smart and the Nordic's Softdevices - Part 1 GAP Advertising

This blog series was created as an attempt to fill in the gap between how Bluetooth Smart is defined in the spec and how you can use nrf51822 APIs and event from nrf51822 softdevice to do what defined in the spec.

It should be a good place to begin with if you know little about Bluetooth Smart and want to start with our stack (softdevice). It would also be useful for one who wants to gain deeper understanding of nrf51822  stack for application developing and debugging.

In this guide, we will try to provide the link between what we describe here and where in theBluetooth Core Spec v4.2 it's defined. The format is Section x.x Part x Vol x .

Bluetooth Smart defined 4 GAP roles: Broadcaster, Observer, Central, Peripheral (Section 6.2 Vol 1 Part A) and 5 Link layer states: Standby, Advertising, Scanning, Initiating, Connection (Section 1.1 Vol 6 Part B). One device may have one or multiple roles, working in one or multiple states at the same time.

In this episode we will focus on Advertising state that's used by the Broadcaster and Peripheral.

A. Theory about Advertising

I. What is advertising

Advertising is the act of broadcasting data. The purpose of this is for device discovery and data publishing. There are 2 types of data packets that can be transmitted, Advertising packet and Scan Response packet, each can have up to 31 bytes payload. The advertiser address is included in the broadcast data in addition to the payload.

The advertiser constantly broadcasts the advertising packets with an advertising interval. Advertising interval can be changed on the fly. There is a requirement for minimum and maximum advertising interval.

For normal, undirected advertising, the advertising intervals ranges from 20ms to 10.24s (Section 7.8.5 Part E Vol2). We will go into detail on different types of advertising in next section.

The scan response packet is transmitted by the advertiser when it receives a scan request from a scanner. The advertiser have to enter a RX period to wait for the scan request. This RX period can be used to receive Connect Request as well. But we will not discuss about connection in this Blog's part.

The following figure describe how the advertising packet and scan response packet is sent.

In some applications when we don't expect a connection and don't have extra data in scan response packet, we can advertise in non-connectable mode and can skip the RX period to save power. The beacon application is one of the use cases.

Note that all Advertising packet, Scan Request packet, Scan Response packet share the same on-air Access Address = 0x8E89BED6. This common address allows any device to scan and receive advertising/scan response data.

Bluetooth Smart uses 40 RF channels in the ISM band (2.4GHz). These RF channels have center frequencies 2402 + k*2MHz where k ranges from 0 to 39. Note that k is not the same as "Channel Index", or channel number (Section 1.4 Vol 6 Part B).

Three of them is dedicated for advertising which is channel 37 (2402MHz), 38 (2426MHz) and 39 (2480MHz). They were selected to avoid interference with the busy channels used by Wifi. This figure shows the 3 advertising channels, 37 data channels, and the curved shapes are wifi busy channels.

In the implementation of our stack, by default we transmit the advertising packet in all 3 channels on every advertising event, on channel 37, 38, 39 respectively. Next figure shows how we do that, and how the advertising packet on a channel is captured by the scanner, which scan on one of the three channel at a time.

II. Broadcast topology

When advertising, the network topology is Broadcast topology. There could be multiple advertisers and multiple scanner at the same time. It is a connection-less network:

Note that one device can do scanning and advertising simultaneously. And one can be in a connection with a central or peripheral and can do advertising at the same time.

The only packet the active scanner can send to the advertiser is the Scan Request packet, which contain only the scanner address. Passive scanner doesn't do Scan Request.

III. Advertising types and advertising with whitelist

There are 4 defined types of Advertising (Section 2.3.1 Vol 6 Part B):

• ADV_IND: connectable undirected advertising . This is the normal advertising type where any device can send scan response packet and connect request to the advertiser.

• ADV_DIRECT_IND: connectable directed advertising . You use this to direct your advertise packet to one specific central to ask for connection. The packet is still a broadcast packet but other scanners will ignore the packet if the peer address is not matched with them. And connect request or scan request from unmatched central will be ignored by the advertiser. Directed advertising usually comes with high duty cycle with interval fix at 3.75ms. For low duty cycle directed advertising, it's configurable and should be <10ms. (Section 4.4.2 Part B Vol 6).

• ADV_SCAN_IND: scannable undirected advertising . This advertising packet won't accept connect request but accept scan request.

• ADV_NONCONN_IND: non-connectable undirected advertising . This is non RX mode, which mean the advertiser will not accept any connect request or scan request. Staying in this mode the advertiser doesn't need to switch to receiver mode and can save power. The main application for this is beacon application, where maximize battery life time is most important and the beacon doesn't need to interact with the scanner.

/**@defgroup BLE_GAP_ADV_TYPES GAP Advertising types
 * @{ */
#define BLE_GAP_ADV_TYPE_ADV_IND          0x00   /**< Connectable undirected. */
#define BLE_GAP_ADV_TYPE_ADV_DIRECT_IND   0x01   /**< Connectable directed. */
#define BLE_GAP_ADV_TYPE_ADV_SCAN_IND     0x02   /**< Scannable undirected. */
#define BLE_GAP_ADV_TYPE_ADV_NONCONN_IND  0x03   /**< Non connectable undirected. */
/**@} */

Advertise with Whitelist

The advertiser can use a whitelist to limit the interaction to a number of scanner/central device. The whitelist contains an array of the peer device addresses or IRK numbers (when central use resolvable random address). It will reject packets from scanners/centrals whose addresses are not in the list. Whitelist can be configured to filter scan request packets, connect request packets or both.

B. Setting up and start advertising with our Softdevice

I. APIs provided by the softdevice:

• Setting up advertising data and the scan response data:

sd_ble_gap_adv_data_set(uint8_t const p_data, uint8_t dlen, uint8_t const p_sr_data, uint8_t srdlen)

• Start advertising with the parameters:

sd_ble_gap_adv_start(ble_gap_adv_params_t const *p_adv_params)

---

Here is how the 31 bytes Advertising data and Scan response data should look like(Chapter 11 Part C Vol 3).

It's up to the application to prepare the advertising data and set it in the softdevice usingsd_ble_gap_adv_data_set().

Note:

• The data in the input parameter is an array of uint8_t. You need to encode data to match with this.
• You should set the length of the advertising data (dlen) to match with the significant part length so that the non-significant part (zero padding) will not be transferred over the air.
• 31 bytes includes also the overhead so the actual payload for application is 27 bytes.

---

After you have set-up the advertising packet you can tell the softdevice to start advertising by calling sd_ble_gap_adv_start(). For this call, you need to configure:

• Advertising interval (the period between each advertising)

• Advertising timeout: how long you want to advertise. You will receive BLE_GAP_EVT_TIMEOUT event after this timeout.

• Advertising types (connectable, non-connectable, directed, etc),

• The peer address if you do directed advertising,

• The whitelist list if you have.

• Filter policy: Choose how to use the whitelist, filter scan request, connect request or both.

• Channel(s) you want to advertise, you can choose one of or two of or all 3 channels to advertise.

II. GAP events you may receive when advertising:

• BLE_GAP_EVT_TIMEOUT: Occurs when the advertising timeout is passed. The application can decide to continue advertising in different mode or to enter sleep mode. The application should check the src parameter to check if the timeout event is from advertising timeout or not. SeeBLE_GAP_TIMEOUT_SOURCES list.

• BLE_GAP_EVT_SCAN_REQ_REPORT: The application receives this event when there is a scan request received by the advertiser. The event comes with address of the peer device and RSSI value. Note: you only get this event if you enable it using the option API sd_ble_opt_set().

• BLE_GAP_EVT_CONNECTED: You receive this when there is a central device send connect request and the connection is established.

• /**@brief GAP advertising parameters.*/
  typedef struct
  {
    uint8_t               type;                 /**< See @ref BLE_GAP_ADV_TYPES. */
    ble_gap_addr_t       *p_peer_addr;          /**< For @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND mode only, known peer address. */
    uint8_t               fp;                   /**< Filter Policy, see @ref BLE_GAP_ADV_FILTER_POLICIES. */
    ble_gap_whitelist_t  *p_whitelist;          /**< Pointer to whitelist, NULL if none is given. */
    uint16_t              interval;             /**< Advertising interval between 0x0020 and 0x4000 in 0.625 ms units (20ms to 10.24s), see @ref BLE_GAP_ADV_INTERVALS.
                                                     - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for high duty cycle directed advertising.
                                                     - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, set @ref BLE_GAP_ADV_INTERVAL_MIN <= interval <= @ref BLE_GAP_ADV_INTERVAL_MAX for low duty cycle advertising.*/
    uint16_t              timeout;              /**< Advertising timeout between 0x0001 and 0x3FFF in seconds, 0x0000 disables timeout. See also @ref BLE_GAP_ADV_TIMEOUT_VALUES. If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for High duty cycle directed advertising. */
    ble_gap_adv_ch_mask_t channel_mask;         /**< Advertising channel mask. @see ble_gap_channel_mask_t for documentation. */
  } ble_gap_adv_params_t;
  

  
  
  

• /**@brief Function for starting advertising.
   */
  static void advertising_start(void)
  {
      uint32_t             err_code;
      ble_gap_adv_params_t adv_params;
  
      // Always initialize all fields in structs to zero or you might get unexpected behaviour
      memset(&adv_params, 0, sizeof(adv_params));
  
      adv_params.type        = BLE_GAP_ADV_TYPE_ADV_IND;
      adv_params.p_peer_addr = NULL;
      adv_params.fp          = BLE_GAP_ADV_FP_ANY;
      adv_params.interval    = APP_ADV_INTERVAL;
      adv_params.timeout     = APP_ADV_TIMEOUT_IN_SECONDS;
  
      err_code = sd_ble_gap_adv_start(&adv_params);
      APP_ERROR_CHECK(err_code);// Check for errors
  }
  

  
  
  

III. Example code

The following code (for S110v8.0/S130v1.0) will setup the advertising packet with device name, flag, Battery service UUID, and advertise with interval = 40ms (0.625 ms unit) and advertising timeout = 180 seconds. It advertises with whitelist applied for connect request. And the only peer address in the whitelist is 0xE05FDAECA271. _

uint32_t             err_code;
ble_gap_adv_params_t adv_params;
ble_gap_whitelist_t  whitelist;
ble_gap_addr_t   * p_whitelist_addr[1];
ble_gap_addr_t        whitelist_addr={BLE_GAP_ADDR_TYPE_RANDOM_STATIC,{0x71,0xA2,0xEC,0xDA,0x5F,0xE0}} ;
uint8_t addr[6] = {0x71,0xA2,0xEC,0xDA,0x5F,0xE0};  
uint8_t adv_data[15] = {0x07,0x09,0x4E,0x6F,0x72,0x64,0x69,0x63,0x02,0x01,0x04,0x03,0x03,0x0F,0x18};
uint8_t adv_data_length = 15;

//Setting up the advertising data with scan response data = Null
err_code = sd_ble_gap_adv_data_set(adv_data, adv_data_length, NULL, NULL);    

//Configure the advertising parameter and whitelist
memset(&adv_params, 0, sizeof(adv_params));
adv_params.type        = BLE_GAP_ADV_TYPE_ADV_IND;
adv_params.p_peer_addr = NULL;
adv_params.interval    = 64;
adv_params.timeout     = 180;
p_whitelist_addr[0] = &whitelist_addr;
whitelist.addr_count = 1;
whitelist.pp_addrs   =  p_whitelist_addr;
whitelist.pp_irks = NULL;
whitelist.irk_count =0;
adv_params.fp          = BLE_GAP_ADV_FP_FILTER_CONNREQ;
adv_params.p_whitelist = &whitelist;
err_code = sd_ble_gap_adv_start(&adv_params);

Here is what the scanner sees when receiving the advertising packet:

Breaking down the raw advertising data:{0x07,0x09,0x4E,0x6F,0x72,0x64,0x69,0x63,0x02,0x01,0x04,0x03,0x03,0x0F,0x18}

0x07 = length 7 octets    
0x09 = AD type Complete Local Name    
0x4E,0x6F,0x72,0x64,0x69,0x63 = "Nordic" in ASCII

0x02 = length 2 octects    
0x01 = AD type flags     
0x04 = Flag BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED

0x03 =length 3 octects    
0x03 = AD type Complete List of 16-bit Service Class UUIDs    
0x0F,0x18 = Battery Service

List of AD types can be found here.

To make the code short and simple, the check of the return code (err_code) of the API call is not added here. When you implement your code, make sure the return code of each API is checked and it should return NRF_SUCCESS (0x00).

The examples in our SDK provide an Advertising module (ble_advertising.c) with abstraction layers and predefined modes. Documentation can be found here.

In addition we provide the advertising data encoding module (ble_advdata.c) that you can use to generate the advertising/scan response packet.

C. FAQ

1. Why am I seeing the advertising period is not the same between each packet ?
Bluetooth spec defined a random delay (0-10ms) on each advertising period to perturb interval and avoid interference (Section 4.4.2.2 part B Vol 6).

2. If I want to advertise my custom data how should I put it in the advertising packet ? You should use Manufacturer Specific Data ADtype (0xFF) as defined here. Note that with that type, the 2 first bytes are for Company ID.

References:

Bluetooth Core Spec v4.2

Getting Started with Bluetooth Low Energy

Useful links:

BLE Advertising, a beginner's tutorial: A tutorial on how to set up advertising packet using our ble_advdata.c in the nRF51 SDK.