3.1.2.2 BLE Legacy Advertisements

Introduction

This document will help users enable BLE Advertisements on the WBZ451 Curiosity board using the MPLAB Code Configurator (MCC). In this basic application example, the advertisement interval will be set to 1 sec.

Users of this document can choose to just run the precompiled Application Example hex file on the WBZ451 Curiosity board and experience the demo or can go through the steps involved in developing this application from scratch.

These examples build on top of one another. We strongly recommend that you follow the examples in order, to learn the basic concepts first before progressing to the more advanced topics.

Hardware Required


Tool	Qty
WBZ451 Curiosity Board	1
Micro USB cable	1
Android/iOS Smartphone	1

Optional Power Debugger/Multimeter/Oscilloscope to measure power

SDK Setup

Getting Started with Software Development

Software

Tera Term

Smartphone App

Light Blue iOS/Android app available in stores

Programming the Precompiled Hex File or Application Example

Programming the .hex File using MPLAB X IPE

Import and program the Precompiled Hex file: <Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\building_blocks\peripheral\legacy_adv\hex\legacy_adv.X.production.signed.hex
For more details on the steps, go to Programming a Device

Note: Ensure to choose the correct Device and Tool information

Programming the Application using MPLAB X IDE

Follow the steps mentioned in Running a Precompiled Example
Open and program the Application: <Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\building_blocks\peripheral\legacy_adv\firmware\legacy_adv.X
For more details on how to find the Harmony Content Path, refer to Installing MCC Plugin

Demo Description

This application example enables transmitting non-connectable, undirected BLE Advertisements. On reset, "Advertising" will appear on a terminal emulator like TeraTerm, denoting the start of advertisements.

Testing

Using a micro USB cable, connect the Debug USB on the Curiosity board to a PC
Program the precompiled hex file or application example as mentioned
Open Tera Term and set the “Serial Port” to USB Serial Device and “Speed” to 115200
For more details on how to set the “Serial Port” and “Speed”, refer to COM Port Setup
Press the Reset Button on the Curiosity board and console should output this
Open the LightBlue app on your smartphone to scan for advertisements. A device with the name "Microchip" will appear.
Users using a wireshark sniffer can examine the complete Application Payload sent
Figure 3-70. Wireshark

Note: Users can use another WBZ451 Curiosity board configured as BLE Scanner (central) instead of using a mobile app

Current Consumption Measurement

Current measured in sleep mode as per the wireless_ble v1.1.0 and wireless_pic32cxbz_wbz v1.2.0 in the A2 version of the WBZ451 module is around 457 uA.

Developing this Application from scratch using MPLAB Code Configurator

This section explains the steps required by a user to develop this application example from scratch using the MPLAB Code Configurator

Note: It is recommended that new users of the MPLAB Code Configurator to go through this overview

Create a new MCC Harmony Project.
To setup the basic components and configuration required to develop this application, import component configuration: <Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\building_blocks\peripheral\legacy_adv\firmware\legacy_adv.X\legacy_adv.mc3.
For more details, refer to Import existing App Example Configuration
To accept dependencies or satisfiers, select "Yes"
Verify if the project graph window has all the expected configuration. as illustrated in the following figure

Verify Advertisement Configuration

Select the BLE Stack component in the Project Graph and configure the following in the Configuration Options panel

Figure 3-73. BLE Stack Configuration

Tip: The advertisement payload can be configured by the user here

Generate Code

For more details on code generation, refer to MPLAB Code Configurator (MCC) Code Generation

Files and Routines Automatically Generated by the MCC

After generating the program source from the MCC interface by clicking Generate Code, the BLE configuration source and header files can then be found in the following project directories

The OSAL, RF System and BLE System initialization routine executed during program initialization can be found in the project file. This initialization routine is automatically generated by the MCC.

The BLE stack initialization routine executed during Application Initialization can be found in project files. This initialization routine is automatically generated by the MCC. This call initializes and configures the GAP, GATT, SMP, L2CAP and BLE middleware layers.

Autogenerated, advertisement data format

Table 3-11. Source Files
Source Files	Usage
`app.c`	Application State machine, includes calls for Initialization of all BLE stack (GAP,GATT, SMP, L2CAP) related component configurations
`app_ble.c`	Source Code for the BLE stack related component configurations, code related to function calls from `app.c`
`app_ble_handler.c`	All GAP, GATT, SMP and L2CAP Event handlers

Note: app.c is autogenerated and has a state machine-based application code sample. Users can use this template to develop their own application.

Header Files

ble_gap.h contains BLE GAP functions and is automatically included in app.c

Function Calls

MCC generates and adds the code to initialize the BLE Stack GAP, GATT, SMP and L2CAP in APP_BleStackInit()
APP_BleStackInit() is the API that will be called inside the Applications Initial State APP_STATE_INIT in app.c

User Application Development

Include

User Action is required
definitions.h must be included in all the files where UART will be used to print debug information

Note: definitions.h is not specific to just UART but instead must be included in all the application source files where any peripheral functionality will be exercised

Set Public Device Address in app_ble.c

BLE_GAP_SetDeviceAddr(&devAddr);

    BLE_GAP_Addr_T devAddr;
    devAddr.addrType = BLE_GAP_ADDR_TYPE_PUBLIC;
    devAddr.addr[0] = 0xA1;
    devAddr.addr[1] = 0xA2;
    devAddr.addr[2] = 0xA3;
    devAddr.addr[3] = 0xA4;
    devAddr.addr[4] = 0xA5;
    devAddr.addr[5] = 0xA6;

    // Configure device address
    BLE_GAP_SetDeviceAddr(&devAddr);