3.2.1 BLE Sensor App

WBZ451 Curiosity Board

Devices (Device): PIC32CX1012BZ25048(MCU) on WBZ451 Module

Devices (Used, On-Board): Analog Temperature Sensor, RGB LED, User Button, User LED, USB-UART converter

Figure 3-48. WBZ451 Curiosity Board
Hardware Block Diagram - Curiosity Board

Hardware Requirement

Tool

Qty

WBZ451 Curiosity Board

1

Micro usb cable

1

Andrioid/iOS Smartphone

1

Software Requirement

Teraterm

Smartphone App

Microchip Bluetooth Data (MBD) iOS/Android app available in stores.

Programming the Precompiled hex file or Application Example

Programming the hex file using MPLABX IPE

  1. Precompiled Hex file is located in "<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\advanced_applications\ble_sensor\precompiled_hex\ble_sensor.X.production.signed.unified_gpiobased.hex"folder

  2. 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 MPLABX IDE

  1. Follow steps mentioned inRunning a Precompiled Example.

  2. Open and program the Application Example "ble_sensor.x" located in "<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\advanced_applications\ble_sensor\firmware" using MPLABX IDE

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

Demo Description

This application demonstrates the capability of WBZ451 module to connect to a mobile phone through Bluetooth Low Energy(BLE). The RGB LED on the Curiosity board can be controlled by mobile app. The WBZ451 device will also report the temperature data periodically to mobile phone through Bluetooth low energy (BLE).

  1. The WBZ451 module will be a BLE peripheral device and will advertise on startup. The user can initiate the connection through mobile application. The advertisement payload holds the temperature information and the RGB ON/OFF status.

  2. Uses "BLE Sensor" sub app from the Microchip Bluetooth Data (MBD) mobile app for BLE demonstration.

    • Application is supported by iOS and Andrioid OS

    • Available in respective app stores/play stores

  3. When Connected(ING) to the application the BLUE color User LED turns on

    • Blinks the "User LED" with 500 ms blink interval when the device sending advertisement packets

    • Once connected, the "User LED" turns on solid

  4. From the Smartphone App the following actions can be performed

    • The RGB LED can be switched On/Off from MBD mobile app.

    • When LED is switched On, the RGB color can be changed from mobile app color wheel.

      • The RGB color value is received as HSV (Hue, Saturation, Value) from mobile app through TRPStransparent profile and service

      • The HSV value is converted to RGB equivalent value in the device. The corresponding PWM duty cycle for R,G,B will be calculated and the PWM pulse is provided on R,G,B LEDs.

  5. From the WBZ451 Module, perform the following actions:

    • The RGB LED can be switched on/off by pressing the On board "User Button"

      • When the User Button is pressed and released the RGB LED is switched ON with default color GREEN or the last stored color.

      • When the User Button is pressed and released again, then the RGB LED is toggled from the previous state.

    • Read the temperature sensor every 1 second once, and send the temperature value to mobile app when the temperature changes about 1 ℃

Testing

  1. Power Up: Connect the Curiosity board using Micro USB to PC. Power Supply Green LED will turn on when connected to PC.

  2. UART Console Behavior:

    1. The application activity is shown as "Console Log" through on board UART-USB converter
    2. Open Terminal (eg: Tera Term) to look for these logs - UART baud settings: 115200 8-N-1 without flow control

  3. BLE Not Connected Behavior

    1. The Blue "User LED" will be blinking
    2. Scanned from mobile app as "BLE_Sensor_XXXX", where 'XXXX' is a uniqu number associated with this board. Launch MBD mobile app and follow the below screenshots
  4. BLE Connected Behavior (Connected to "BLE Sensor" MBD Mobile Application). The Blue "User LED" will be solid On when connected.

  5. Firmware Version

    1. Bluetooth SIG defined "Device Info Service" is implemented in the device to share the device information like "firmware version", "manufacture name", etc.,
    2. Verify the firmware version shown on console with MBD app
  6. The BLE Sensor mobile app will show the temperature (deg C) and LED status received from device, as well as allow the user to vary the RGB color and brightness

  7. The RGB LED can also be switched On/Off by pressing the On board "User Button (SW2)". The On/Off LED status will also be reported to mobile app if connected. When the "User Button (SW2)" is pressed and released, RGB LED is switched ON. When pressed and released again, the state will be toggled from the previous state.

Protocol Exchange

For more details on the communication protocol exchange between BLE sensor mobile app (BLE central) and

WBZ451 Module (BLE peripheral), refer to Protocol Exchange

Application Flow Diagram

Expanding/Customising the Application

The BLE Sensor demo protocol based on TRPS profile is a transparent request, response based and not tied only to this BLE sensor application. It can be expanded and customized as per the users need.
  • The protocol parser is implemented in app_trps.c and app_trps.h
    • Request and Response: when the user wants to get and modify data on the device.
    • Notify: when there is a new data to be sent to mobile app.
  • The protocol commands are defined in app_ble_sensor.h and related sensor functionalities are implemented in app_ble_sensor.c
    • Request and Response: When a command request is received from mobile app, app_trps.c parse the data and forward to specific command callback handler in app_ble_sensor.c
    • Notify: When specific Sensor data to be sent to mobile app, app_ble_sensor.c places the data in data base and calls for notify handler in app_trps.c (/ref APP_TRPS_SendNotification())

Example: To add a command to get temperature in Fahrenheit.

Complete the SDK Setup and open the "ble_sensor.x" located in "<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\ble\advanced_applications\ble_sensor\firmware" using MPLABX IDE

  • Changes to - app_ble_sensor.h

    1. Define request, response, size of response payload (not including size of length byte and response ID)
    2. Define a new control command ID
    3. Define a new control command response
    4. Define the length for the new response command
    5. Inside the existing APP_TRPS_SensorData_T structure, add the new data structure which holds the response data
    6. Increase the list size BLE_SENSOR_CMD_RESP_LST_SIZE by one
    7. Add new command request/response set in BLE_SENSOR_DEFINE_CTRL_CMD_RESP() list

  • Changes to - app_ble_sensor.c

    1. Read the temperature periodically and store in above defined data structure. Add the below code in App_TRPS_Sensor_TimerHandler()
    2. After doing the above changes follow the instruction in select option Build Project in IDE to compile the application example

    3. Select option Run Project in IDE to program the target – the onboard debugger will program the example application

  • Testing with MBD mobile app

    The BLE Sensor sub app in MBD mobile app is designed only to work with specific functionality. So, if new command is added in BLE sensor application, BLE Sensor mobile app will not know about it. To test the above newly added code, "BLE Smart" sub app in MBD can be used. Follow the below screenshots after launching MBD mobile app.

Using the MPLAB Code Configurator

MPLABX Harmony provides the MPLAB® Code Configurator (MCC) tool, a set of modular device and middleware libraries, and numerous example applications, all of which are designed to help developers to quickly and easily develop powerful and efficient embedded software.
MPLAB® Code Configurator (MCC) is a free graphical programming environment that generates seamless, easy-to-understand C code to insert into your project. Using an intuitive interface, it enables and configures a rich set of peripherals and functions specific to your application. The following steps can be followed to open MCC tool and generate the code.
  1. Open the MCC tool from MPLABX
  2. Once the MCC tool is launched, the "Project Graph" shows the list of MCC components used in the specific project
  3. Clicking on the specific component block will allow to change the configuration of that component. eg:SERCOM0 is shown in the screenshot.
  4. New component can also be added by drag and drop from "Device Resources" to "Project Graph". Then configure the component as in step #3. eg: SERCOM1 can be added into "Project Graph"
  5. Once all the required components and configurations are done, generate a code . For more details on how to generate a code, refer to 14.2 MPLAB Code Configurator(MCC) Code Generation.