LE Broadcaster

The ble_observer sample demonstrates how to use the LE GAP Broadcaster role to develop many different broadcaster-role based applications.

LE Broadcaster role features:

Can send non-connectable advertising events.
Cannot create connections.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

To quickly set up the development environment, please refer to the detailed instructions provided in Quick Start.

Wiring

Please refer to RTL87x2G EVB Interfaces and Modules in Quick Start.

Configurations

Configurable Items

All contents that can be configured for the sample are in samples\bluetooth\ble_broadcaster\src\app_flags.h, developers can configure according to actual needs.

/** @brief  Config DLPS: 0-Disable DLPS, 1-Enable DLPS */
#define F_BT_DLPS_EN                        1

/** @} */ /* End of group BROADCASTER_Config */

Building and Downloading

This sample can be found in the SDK folder:

Keil

Project file: samples\bluetooth\ble_broadcaster\proj\rtl87x2g\mdk

GCC

Project file: samples\bluetooth\ble_broadcaster\proj\rtl87x2g\gcc

To build and run the sample, follow the steps listed below:

Open project file.
To build the target, follow the steps listed in the Generating App Image from the Quick Start.
After a successful compilation, the APP bin app_MP_sdk_xxx.bin will be generated in the directory samples\bluetooth\ble_broadcaster\proj\rtl87x2g\mdk\bin.
To download the APP bin into the EVB, follow the steps listed in the MP Tool Download from the Quick Start.
Press the reset button on the EVB and it will start running.

Experimental Verification

After downloading the sample bin to the EVB, developers can test it either by using another kit that is running the LE Observer sample, or by using a phone which already has installed LE APPs like LightBlue.

Testing with Another Kit

Please refer to Testing with Another Kit in LE Observer.

Testing with Phone

Press the reset button on DUT and DUT will start sending non-connectable undirected advertising events.

If the advertisement is successfully enabled, the following Debug Analyzer log will be printed. If developers do not see the following log, it means that the advertisement failed to start. Please check if the software and hardware environment is configured correctly.
```
[APP] !**GAP adv start
```
Run LightBlue on an iOS device to search for DUT, as shown below:

Test with iOS Device

Developers can only implement scanning action on the phone-end because the advertising events sent by DUT is non-connectable.

Code Overview

The main purpose of this chapter is to help sample developers familiarize themselves with the development process related to Broadcaster Role. This chapter will be introduced according to the following several parts:

The directories of the project and source code files will be introduced in chapter Source Code Directory.
The Bluetooth Host will be introduced in chapter Bluetooth Host Overview.
The main function and configurable GAP parameters of this sample will be introduced in chapter Initialization.
The GAP message handler of this sample will be introduced in chapter GAP Message Handler.

Source Code Directory

Project directory: samples\bluetooth\ble_broadcaster\proj.
Source code directory: samples\bluetooth\ble_broadcaster\src.

Source files in ble_observer sample project are currently categorized into several groups as below.

└── Project: broadcaster
    └── secure_only_app
        └── Device                   includes startup code
        ├── CMSE Library             Non-secure callable library
        ├── Lib                      includes all binary symbol files that user application is built on
            ├── ROM_NS.lib
            └── lowerstack.lib
            └── rtl87x2g_sdk.lib
            └── gap_utils.lib
        ├── Peripheral               includes all peripheral drivers and module code used by the application
        ├── Profile                  includes LE profiles or services used by the sample application
        └── APP                      includes the ble_broadcaster user application implementation
            ├── app_task.c
            ├── main.c
            └── broadcast_app.c

The sample uses default GAP LIB that matches with bt_host_0_0, please refer to Usage of GAP LIB in Host Image for more information.

Bluetooth Host Overview

The sample uses default Bluetooth Host image in bt_host_0_0, please refer to Host Image for more information.

For the details of Bluetooth technology features supported by the Bluetooth Host, please refer to the file bin\rtl87x2g\bt_host_image\bt_host_0_0\bt_host_config.h.

Initialization

main() function is invoked when the EVB is powered on and the chip is reset, and it performs the following initialization functions:

int main(void)
{
  board_init();
  le_gap_init(0);
  gap_lib_init();
  app_le_gap_init();
  pwr_mgr_init();
  task_init();
  os_sched_start();

  return 0;
}

le_gap_init() function is used to initialize GAP and configure link number.
app_le_gap_init() function is used to initialize the GAP parameters. Developers can configure Advertising parameters (please refer to the chapter Configure Advertising Parameters of LE Host).

void app_le_gap_init(void)
{
    /* Advertising parameters */
    uint8_t  adv_evt_type = GAP_ADTYPE_ADV_NONCONN_IND;
    uint8_t  adv_direct_type = GAP_REMOTE_ADDR_LE_PUBLIC;
    uint8_t  adv_direct_addr[GAP_BD_ADDR_LEN] = {0};
    uint8_t  adv_chann_map = GAP_ADVCHAN_ALL;
    uint8_t  adv_filter_policy = GAP_ADV_FILTER_ANY;
    uint16_t adv_int_min = DEFAULT_ADVERTISING_INTERVAL_MIN;
    uint16_t adv_int_max = DEFAULT_ADVERTISING_INTERVAL_MIN;

    /* Set advertising parameters */
    le_adv_set_param(GAP_PARAM_ADV_EVENT_TYPE, sizeof(adv_evt_type), &adv_evt_type);
    le_adv_set_param(GAP_PARAM_ADV_DIRECT_ADDR_TYPE, sizeof(adv_direct_type), &adv_direct_type);
    le_adv_set_param(GAP_PARAM_ADV_DIRECT_ADDR, sizeof(adv_direct_addr), adv_direct_addr);
    le_adv_set_param(GAP_PARAM_ADV_CHANNEL_MAP, sizeof(adv_chann_map), &adv_chann_map);
    le_adv_set_param(GAP_PARAM_ADV_FILTER_POLICY, sizeof(adv_filter_policy), &adv_filter_policy);
    le_adv_set_param(GAP_PARAM_ADV_INTERVAL_MIN, sizeof(adv_int_min), &adv_int_min);
    le_adv_set_param(GAP_PARAM_ADV_INTERVAL_MAX, sizeof(adv_int_max), &adv_int_max);
    le_adv_set_param(GAP_PARAM_ADV_DATA, sizeof(adv_data), (void *)adv_data);
    le_adv_set_param(GAP_PARAM_SCAN_RSP_DATA, sizeof(scan_rsp_data), (void *)scan_rsp_data);
}

A device in the broadcast mode shall send data using non-connectable advertising events. Therefore the parameter adv_evt_type should be configured to the following type: GAP_ADTYPE_ADV_NONCONN_IND.

More information on LE GAP initialization and startup flow can be found in the chapter GAP Parameters Initialization of LE Host.

GAP Message Handler

app_handle_gap_msg() function is invoked whenever a GAP message is received from the Bluetooth Host. More information on GAP messages can be found in the chapter Bluetooth LE GAP Message of LE Host.

void app_handle_gap_msg(T_IO_MSG *p_gap_msg)
{
    T_LE_GAP_MSG gap_msg;
    memcpy(&gap_msg, &p_gap_msg->u.param, sizeof(p_gap_msg->u.param));

    APP_PRINT_TRACE1("app_handle_gap_msg: subtype %d", p_gap_msg->subtype);
    switch (p_gap_msg->subtype)
    {
    case GAP_MSG_LE_DEV_STATE_CHANGE:
        {
            app_handle_dev_state_evt(gap_msg.msg_data.gap_dev_state_change.new_state,
                                     gap_msg.msg_data.gap_dev_state_change.cause);
        }
        break;

    default:
        APP_PRINT_ERROR1("app_handle_gap_msg: unknown subtype %d", p_gap_msg->subtype);
        break;
    }
}

The ble_observer sample will call le_adv_start() to start advertising when receiving GAP_INIT_STATE_STACK_READY. If le_adv_start() returns true, it means the Bluetooth Host has already received this command and is ready to execute. When this command execution completes, the Bluetooth Host will send GAP_ADV_STATE_ADVERTISING to app_handle_dev_state_evt(). When the ble_observer sample runs on the EVB, the device will send non-connectable advertising events.

void app_handle_dev_state_evt(T_GAP_DEV_STATE new_state, uint16_t cause)
{
    APP_PRINT_INFO3("app_handle_dev_state_evt: init state %d, adv state %d, cause 0x%x",
                    new_state.gap_init_state, new_state.gap_adv_state, cause);
    if (gap_dev_state.gap_init_state != new_state.gap_init_state)
    {
        if (new_state.gap_init_state == GAP_INIT_STATE_STACK_READY)
        {
            APP_PRINT_INFO0("GAP stack ready");
            /*stack ready*/
            le_adv_start();
        }
    }

    if (gap_dev_state.gap_adv_state != new_state.gap_adv_state)
    {
        if (new_state.gap_adv_state == GAP_ADV_STATE_IDLE)
        {
            APP_PRINT_INFO0("GAP adv stoped");
        }
        else if (new_state.gap_adv_state == GAP_ADV_STATE_ADVERTISING)
        {
            APP_PRINT_INFO0("GAP adv start");
        }
    }

    gap_dev_state = new_state;
}

Troubleshooting

How to Modify the Parameters of Advertising Data?

The advertising data is defined in the following array adv_data, and developer can directly modify the content of the array to modify the advertising data.

static uint8_t adv_data[] =
{
  /* Flags */
  0x02,             /* length */
  GAP_ADTYPE_FLAGS, /* type="Flags" */
  GAP_ADTYPE_FLAGS_BREDR_NOT_SUPPORTED,

  /* Local name */
  0x10,
  GAP_ADTYPE_LOCAL_NAME_COMPLETE,
  'B', 'L', 'E', '_', 'B', 'R', 'O', 'A', 'D', 'C', 'A', 'S', 'T', 'E', 'R'
};