LE Observer

The LE observer sample demonstrates how to use the LE GAP Observer role to develop many different observer-role based applications.

LE Observer role features:

Can receive scannable 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_observer\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 OB_Config */

Building and Downloading

This sample can be found in the SDK folder:

Keil

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

GCC

Project file: samples\bluetooth\ble_observer\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 in Quick Start.
After a successful compilation, the APP bin app_MP_sdk_xxx.bin will be generated in the directory samples\bluetooth\ble_observer\proj\rtl87x2g\mdk\bin.
To download APP bin into the EVB, follow the steps listed in the MP Tool Download in 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 by using another kit that is running the LE broadcaster sample.

Testing with Another Kit

Prepare two development boards named DUT and Tester respectively, and use Debug Analyzer tool to Log Verification .

Preparation Phase

Use MP Tool set DUT address to [00:11:22:33:44:85], and then build the LE observer sample, and download images into DUT.
Use MP Tool set Tester address to [00:11:22:33:44:80], and then build the LE broadcaster sample, and download images into Tester. For more information, please refer to Building and Downloading in LE Broadcaster.

For details about how to change the Bluetooth Address, please refer to Generating System Config File in Quick Start.

Testing Phase

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

If the advertisement is successfully enabled, the following 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

Press reset button on DUT and DUT will start scanning.

In the DUT log, use the Tester address to find if the broadcast was scanned. If DUT receives advertising data and scan response data, the sample will receive event GAP_MSG_LE_SCAN_INFO.

Logs are shown below:
[APP]  GAP_MSG_LE_SCAN_INFO: bd_addr 00::11::22::33::44::80, bdtype 0, event 0x3, rssi -58, len 20

Code Overview

The main purpose of this chapter is to help APP developers become familiar with the development process related to the Observer 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.
The GAP callback handler of this sample will be introduced in chapter GAP Callback Handler.

Source Code Directory

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

Source files in the LE observer sample project are currently categorized into several groups as below.

└── Project: observer
    └── secure_only_app
        └── Device                   includes startup code
        ├── CMSE Library             Non-secure callable lib
        ├── Lib                      includes all binary symbol files that the 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_observer user application implementation
            ├── app_task.c
            ├── main.c
            └── observer_app.c

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

Bluetooth Host Overview

The sample uses default Bluetooth Host image in bt_host_0_0. Please refer to Bluetooth 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 scan parameters (please refer to the chapter Configure Scan Parameters of LE Host).

void app_le_gap_init(void)
{
    /* Scan parameters */
    uint8_t  scan_mode = GAP_SCAN_MODE_PASSIVE;
    uint16_t scan_interval = DEFAULT_SCAN_INTERVAL;
    uint16_t scan_window = DEFAULT_SCAN_WINDOW;
    uint8_t  scan_filter_policy = GAP_SCAN_FILTER_ANY;
    uint8_t  scan_filter_duplicate = GAP_SCAN_FILTER_DUPLICATE_ENABLE;

    /* Set Scan parameters */
    le_scan_set_param(GAP_PARAM_SCAN_MODE, sizeof(scan_mode), &scan_mode);
    le_scan_set_param(GAP_PARAM_SCAN_INTERVAL, sizeof(scan_interval), &scan_interval);
    le_scan_set_param(GAP_PARAM_SCAN_WINDOW, sizeof(scan_window), &scan_window);
    le_scan_set_param(GAP_PARAM_SCAN_FILTER_POLICY, sizeof(scan_filter_policy),
                      &scan_filter_policy);
    le_scan_set_param(GAP_PARAM_SCAN_FILTER_DUPLICATES, sizeof(scan_filter_duplicate),
                      &scan_filter_duplicate);

    /* register gap message callback */
    le_register_app_cb(app_gap_callback);
}

A device in observe mode shall only receive scannable advertising events and no scan request PDUs shall be sent. Therefore, the parameter scan_mode should be configured as the following type: GAP_SCAN_MODE_PASSIVE.

le_register_app_cb() registers the GAP message callback function app_gap_callback() and all GAP callback messages will be handled in this callback.

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;
    }
}

Observer sample will call le_scan_start() to start scanning when receiving GAP_INIT_STATE_STACK_READY. If le_scan_start() returns true, it means Bluetooth Host has already received this command and is ready to execute. When this command execution is complete, Bluetooth Host will send GAP_SCAN_STATE_SCANNING to app_handle_dev_state_evt(). When the LE observer sample runs on the EVB, the device will receive scannable advertising events and Bluetooth Host will send GAP_MSG_LE_SCAN_INFO to app_gap_callback(). Observer sample will call app_parse_scan_info() to parse advertising data and scan response data.

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, scan state %d, cause 0x%x",
                    new_state.gap_init_state,
                    new_state.gap_scan_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_scan_start();
        }
    }

    if (gap_dev_state.gap_scan_state != new_state.gap_scan_state)
    {
        if (new_state.gap_scan_state == GAP_SCAN_STATE_IDLE)
        {
            APP_PRINT_INFO0("GAP scan stop");
        }
        else if (new_state.gap_scan_state == GAP_SCAN_STATE_SCANNING)
        {
            APP_PRINT_INFO0("GAP scan start");
        }
    }
    gap_dev_state = new_state;
}

GAP Callback Handler

app_gap_callback() function is used to handle GAP callback messages. More information on GAP callback can be found in the chapter Bluetooth LE GAP Callback of LE Host.

When the device is in scanning mode, it may receive advertising data. GAP Layer will send GAP_MSG_LE_SCAN_INFO to the application when it receives advertising data or scan response data.

T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
   T_APP_RESULT result = APP_RESULT_SUCCESS;
   T_LE_CB_DATA *p_data = (T_LE_CB_DATA *)p_cb_data;

   switch (cb_type)
   {
   case GAP_MSG_LE_SCAN_INFO:
       APP_PRINT_TRACE5("GAP_MSG_LE_SCAN_INFO: bd_addr %s, bdtype %d, event 0x%x, rssi %d, len %d",
                       TRACE_BDADDR(p_data->p_le_scan_info->bd_addr),
                       p_data->p_le_scan_info->remote_addr_type,
                       p_data->p_le_scan_info->adv_type,
                       p_data->p_le_scan_info->rssi,
                       p_data->p_le_scan_info->data_len);
       /* User can split interested information by using the function as follow. */
       app_parse_scan_info(p_data->p_le_scan_info);
       break;

   default:
       break;
   }
   return result;
}

Note

app_parse_scan_info() function is a sample function to parse advertising data and scan response data.