This document will help users create a peripheral device with custom profile and control.
The RGB LEDs and user button on the WBZ451 Curiosity board shall be used to enable or disable the LED status. The
peripheral device will be the WBZ451 Curiosity board and the
central device can either be a smartphone with a Light Blue app or another WBZ451 Curiosity board. The instructions mentioned below are
applicable for a BLE peripheral device.
Users 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.
It is recommended to follow the examples in order, by learning the basic concepts first
and then progressing to the more advanced topics.
Programming the Precompiled Hex
File or Application Example
Programming the .hex file using MPLAB X IPE
1. Import and program the
Precompiled Hex file: <Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\building_blocks\peripheral\profiles_services\custom_service\hex\custom_service.X.production.signed.hex
Open and program the Application:
<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\building_blocks\peripheral\profiles_services\custom_service\firmware\custom_service.X
This application enables users to control a RGB LEDs on
the WBZ451 Curiosity board and read its status using a
central device. On reset, demo will print "[BLE] Device Initialized. Ready for
connection" which denotes the start of advertisements and then "[BLE] Connected to
Peer Device:” when connection is established. Application data to be sent to the
connected central device (smartphone or another WBZ451
Curiosity board) is entered in a terminal emulator like Tera Term.
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. This must be displayed in Tera TermFigure 3-134. Tera Term
Launch the Light Blue mobile app
and search for the device name “pic32cx-bz” and press ConnectFigure 3-135. LightBlue® App
Figure 3-136. Tera Term
Once connected, basic information like Advertisement Data and Device
Information will be available
Figure 3-137 3-138. LightBlue® App
Find the custom service with the
UUID: 4d434850-5255-42d0-aef8-881facf4ceea. Two characteristics will be
available with the custom service. The button characteristics with the
Readable/Notify property and GREEN LED characteristics with Readable/Writable
property.Figure 3-137 3-138. LightBlue® App
Click on the button
characteristics and press subscribe. Press the User button on the curiosity
board. The Read Value in the app will give its current status. Pressing the
button will also toggle the GREEN LED.Figure 3-139.
Figure 3-140.
Go back and click on the RGB LEDs characteristics which has a read/write
option. The write option changes the RGB LEDs On/Off
status by writing a hex value in the form of XXXXXX. A value of 000000 will turn
OFF the LED and value of FFFFFF turns it ON. The read option will give the
current value stored for the RGB LEDs.Figure 3-141.
Figure 3-142.
Figure 3-143.
Press back two times to disconnect the BLE connection. A disconnected device
will advertise again.Figure 3-144. Tera Term
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.
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\profiles_services\custom_service\firmware\custom_service.X\custom_service.mc3
Note: Import and Export functionality of the Harmony
component configuration will help users to start from a known working setup
of the 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:Figure 3-145. Project
Graph
Verify Custom Service Configuration
Select BLE Stack component the Project Graph and configure the
following in the Configuration Options panel
Figure 3-146. 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 3-147. Configuration
Panel
.
Select the FreeRTOS component in the Project Graph and configure the followingFigure 3-148. FreeRTOS
Configuration
Select the SERCOM0 component in the Project Graph and configure the followingFigure 3-149. SERCOM0
Configuration
Select the System component in the Project Graph and configure the followingFigure 3-150. System
Configuration
Select the EIC component in the Project Graph and configure the followingFigure 3-151. EIC
Configuration
Select the Customized Service component in the Project Graph and configure the
followingFigure 3-152. Customized
Service ConfigurationFigure 3-153. Customized
Service ConfigurationFigure 3-154. Customized
Service Configuration
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.Figure 3-155. Project
Files
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.
Figure 3-156. initialization.c
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.
Figure 3-157.
Here are also the autogenerated Advertisement Data (AD) structures and types as
referenceFigure 3-158. AD Structures and
Types
Table 3-19. 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
ble_button_led_svc.c
All Custom Service button RGB LEDs configurations and functions
Note:app.c is autogenerated and has a state
machine-based application code. Users can use this template to develop their own
application.
User Application Development
Add the code to enable advertisement, call the button external interrupt callback
functions and initialize custom service in APP_STATE_INIT of the
function APP_Tasks() in app.c
Add the custom service source and header files “<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\building_blocks\peripheral\profiles_services\custom_service\firmware\src\app_ble_custom_service.c
and app_ble_custom_service.h and
app_ble_custom_service.h which has the supporting
functions for the button LED custom service file
Figure 3-162. Project FilesAdd the required variables, functions and callback handlers for the GATT
read/write response in app_ble_handler.c along with the connect and
disconnect message information