4.1.2.5 BLE Connection

Introduction

This document will help users enable advertisements and connection on the WBZ351 Curiosity board using the MPLAB Code Configurator(MCC). The peripheral device will be the WBZ351 Curiosity board and the central device can either be a smartphone with a Light Blue app or another WBZ351 Curiosity board. BLE Advertising is broadcasting small packets to peer devices. In BLE, a peripheral device always starts with advertisements. Advertisement packets enable a central or observer to discover and connect to a peripheral.

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

It is recommended to follow the examples in order, by learning the basic concepts first and then progressing to the more advanced topics.

Hardware Requirement

Table 4-14. Hardware Requirement
Tool	Qty
WBZ351 Curiosity Board	1
Micro USB cable	1
Android/iOS Smartphone	1

SDK Setup

Getting started with Software Development

Software Requirement

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_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\peripheral_conn\hex\peripheral_conn.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 steps mentioned in the Running a Precompiled Example
Open and program the application: “<Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\peripheral_conn\firmware\peripheral_conn.X

For more details on how to find the Harmony Content Path, refer to Installing a MCC Plugin

Demo Description

This application enables users to transmit Connectable and Scannable Undirected BLE Advertisements. On reset, demo will print "Advertising" on a terminal emulator like Tera Term which denotes the start of advertisements. The central device scanning these advertisements can then issue a connection request unto the Curiosity board. Upon connection, "Connected" is printed on the terminal window.

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 Switch on the Curiosity board. "Advertising" should be displayed in Tera Term.
Launch the Light Blue mobile app to scan for Advertisements. The device name "Microchip" will appear then press Connect. After a successful connection, you can view the advertisement data and see “Connected” displayed in Tera Term.

Figure 4-80.

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

Developing the Application from Scratch using MCC

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_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\peripheral_conn\firmware\peripheral_conn.X\peripheral_conn.mc3
For more details on importing the component configuration , refer to Importing Existing App Example Configuration
Note: Import and export functionality of Harmony component configuration will help users to start from a known working setup of MCC 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:

Verifying Advertisement and Connection Configuration

Select BLE Stack component in project graph, to open component configuration and configure as illustrated in the following figure.

Figure 4-82. BLE Stack Configuration

Note: If users cannot see the Configuration Options panel in the right-hand side of the MPLAB X IDE, it might be minimized. Hover the cursor towards the Configuration Options side tab and click the “dot” on the top right-hand corner to pin it (see the following figure)
Figure 4-83. Configuration Panel
.

Generating a Code

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

Files and Routines Automatically Generated by the MCC

After generating the program source from MCC interface by clicking Generate Code, the BLE configuration source and header files can 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.

Here are also the autogenerated Advertisement Data (AD) structures and types as reference

Table 4-15. 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\app_ble.c`	Source Code for the BLE stack related component configurations, code related to function calls from `app.c`
`app_ble\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. 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 file.

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 it must be included in all 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);

Starting Advertisement in app.c

BLE_GAP_SetAdvEnable(0x01, 0x00);
Figure 4-89. app.c

Connected and Disconnected Events

All the possible GAP, GATT, SMP and L2CAP Event handlers are available in file app_ble_handler.c. Users can implement their own application code to denote Connection State here.
Figure 4-90. app_ble_handler.c