5.5 BLE ZigBee Provisioning Low Power Application Demo: Zigbee Multi-Sensor and Zigbee Commissioning through BLE

This section helps users to create a low power enabled multiprotocol (BLE+ZIGBEE) example project using MCC. The step by step procedure helps users to generate a Zigbee Multi-Sensor application and commission the Multi-Sensor to a Zigbee network through BLE from scratch.

Hardware Requirement

Table 5-5. Hardware Requirement
Tool Qty
WBZ451 Curiosity Board1
Micro USB cable1
Android/iOS Mobile1

Software Requirement

SDK Setup

Smartphone App

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

Programming the Precompiled Hex File or Application Example

The demo needs two devices as described below:

  1. Combined Interface: One of the WBZ451 Curiosity boards is programmed with Combined Interface which can act as Zigbee Gateway/Coordinator. Program the CI pre-compiled hex image by following the steps mentioned in the “Programming the precompiled hex file or Application Example” section of the Zigbee Centralized Network Formation by Combined Interface application, on one curiosity board.
  2. ble_zigbee_multisensor: Another WBZ451 Curiosity board is programmed with ble_zigbee_multisensor application which can act as Zigbee end device. Follow the below step for programming ble_zigbee_multisensor application on another curiosity board.

Programming the .hex File using MPLAB X IPE

  1. Import and program the precompiled .hex file is located in "<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\multiprotocol\ble_zigbee_multisensor\Hex" folder
  2. For more details on the steps, go to Programming a Device
    Note: Users must choose the correct device and tool information

Programming the Application using MPLAB X IDE

  1. Follow steps mentioned in the Running a Precompiled Example section.
  2. Open and program the application example "ble_zigbee_multisensor.x" located in "<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\multiprotocol\ble_zigbee_multisensor\firmware" using MPLAB X IDE

    For more details on finding the Harmony content path, refer to Installing the MCC Plugin

Demo Description

This application demonstrates the Zigbee Multi-Sensor end device joining to Zigbee Coordinator (Combined Interface, The third party Gateway's like Amazon Echo plus can also be used instead of CI.) by receiving the commissioning parameters from user using a mobile phone through BLE Link. The mobile application uses Microchip Proprietary Transparent Service to send and receive data PIC32CX-BZ2/WBZ451 device.

Figure 5-102. Demonstration

The BLE provisioner in the MBD App (available in Google Play Store and Apple Store) is utilized to demo the provisioning functionality.

Figure 5-103. BLE Provisioning

Demo Steps

The BLE Zigbee Multi-Sensor can be connected to any Zigbee network.
  • The steps explained in Joining Multi-Sensor with the WBZ451 Combined Interface (CI) Coordinator can be followed to connect with the WBZ451 based Combined Interface which acts as Zigbee Coordinator.

Joining Multi-Sensor with the WBZ451 Combined Interface (CI) Coordinator

Hardware and Software Setup

  1. Supply power to the WBZ451 Curiosity board consisting of Combined Interface application by connecting a USB cable. Power Supply (PS) Green LED will turn ON when connected to the PC.
    Figure 5-104. Curiosity Board Power Supply
  2. Open TeraTerm and configure as mentioned below:
    Terminal Settings
    • Baud Rate/Speed – 115200 (as configured in SERCOM configuration)
    • Parity – None
    • Data Bits – 8
    • Stop Bits – 1
    • Flow Control – None

    For more details on how to set the “Serial Port” and “Speed”, refer to COM Port Setup

    Additionally, local echo and sending line ends with line feeds shall be enabled in the PC serial terminal application.
    Figure 5-105. Terminal Setup

Network Formation (Coordinator - (Combined Interface))

Follow the steps explained in Network Formation (Coordinator - (Combined Interface)) to open up the network in CI.

Commissioning (End Device - Multi-Sensor)

  1. Supply power to the WBZ451 Curiosity board which is programmed with BLE Zigbee Multi-Sensor image by connecting a USB cable. Once commissioning is initiated via MDB, the BLE Zigbee Multi-Sensor will search for Zigbee coordinator device and will join to network and initiate Finding & Binding.
  2. Launch MBD Microchip Bluetooth Data app from mobile. Open BLE Provisioning feature and scan for the devices.
    1. Look for the device labeled as “Combo_Multisensor” in the scan results.
    2. Establish a connection with the device and refer to the subsequent screenshots provided for guidance on the commissioning process.
    Note:
    • The Combo Multisensor is configured with default primary channel mask (11,15,20,25) as per Zigbee specification. The channel configuration from mobile app is needed only when the Gateway channel is not in any of the default channels.
    • If commissioning procedure, does not find the nearby network (for example, Echo Plus), try to find the channel of the network, and configure the same channel while commissioning
    Figure 5-106. MBD App
    Figure 5-107. MBD App
  3. When the Combo Light is joined to an existing network/formed its own network, the device state can be seen as “Commissioned” as illustarted in the above figure.
  4. When the commissioning is started from the MBD app, the following will be printed to the Combined Interface terminal:
    Figure 5-108. Tera Term Logs
  5. Success log on Combo Light when commissioned with Combined Interface

    Figure 5-109. Tera Term Logs
  6. Once BLE Zigbee Multi-Sensor finishes Finding & Binding procedure, it will start attribute reporting. The Combined Interface terminal log prints the received attribute information as illustrated below.
    Figure 5-110. Tera Term Logs
  7. Status messages during commissioning: below status messages can be observed during the commissioning procedure based on the conditions.
    • Device Joined to an existing network

      Figure 5-111. Joined to Existing Network
    • Device formed its own network.

      Figure 5-112. Device Forming New Network
    • Fail Status: commissioning has failed (did not join/create own network)

      Figure 5-113. Commissioning Failed

Developing the Application from Scratch using MCC

The following steps will help to understand the PIC32CXBZ2 device ZIGBEE and BLE stack programming structure. Ensure that wireless_system_pic32cxbz2_wbz45 repo is available locally as documented in Getting Started with Software Development

Note: It is recommended that new users of MCC to go through the overview.

For developing Combined Interface from scratch, refer to the “Creating Application Device Types from Scratch using MCC” section of the Zigbee Centralized Network Formation by Combined Interface

This tutorial explains developing ble_zigbee_multisensor application from scratch

Pull-in H3 Components

  1. Create a new MCC Harmony Project. For more details, refer to Creating a New MCC Harmony Project.
  2. Import component configuration – This step helps users setup the basic components and configuration required to develop this application. The imported file is of format .mc3 and is located in the path "<Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\multiprotocol\ble_zigbee_multisensor\firmware\ble_zigbee_multisensor.X".

    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
  3. Verify the project graph and configuration options shown in the below steps.
  4. Another method is manually adding and configuring the components in project graph
    1. From “Device Resources” field, select + BLE ZIGBEE PROVISIONING component (Device Resources>Wireless>System Services), to add it in project graph.
      Figure 5-114. BLE ZIGBEE PROVISIONING
    2. Accept all dependencies by selecting Yes. Click on the Zigbee Device dependency on the “BLE ZIGBEE PROVISIONING”, and select MultiSensor. The project graph will appear as illustrated in the figure below
      Figure 5-115. Project Graph
    3. From “Device Resources” field, select + TCC2 component, to add it in project graph.
      Figure 5-116. TCC2
      Figure 5-117. Project Graph
    4. Select the Multi Sensor Zigbee device component by clicking on the component in the project graph. Now the “Configuration Options” tab lists the Configurations for the selected Zigbee device. Ensure that the Manual Configuration is enabled and Network Formation Commissioning is enabled and AUTOMATIC COMMISSIONING ON STARTUP is disabled as illustrated in the following figure.

      Figure 5-118. Multi Sensor
    5. Select the BLE Stack component by clicking on the component. In the “Configuration Options” tab, Expand Generic Access Profile (GAP)>Advertising>Advertising Data and Scan Response Data.

    6. In “Advertising Data” menu, ensure that Local Name is disabled and enabled in Scan Response Data>Local Name. In “Advertising Data” menu, ensure that Service Data is enabled, Service UUID is set as 0xFEDA and Service Data is set as 0xFF03 as illustrated in the following figure.

      Figure 5-119. BLE Stack Configuration
      Note:
      1. 0xDAFE is a 16-bit Service UUID which is purchased by Microchip from Bluetooth SIG.
      2. In order to list the device while scanning in Microchip Bluetooth Data (MBD) mobile application, the device must advertise with Service UUID as 0xDAFE and Service Data as 0xFF03.

Low Power Configuration

  1. Enable Sleep Mode in BLE stack H3 component configuration, after enabling this dependent component like RTC (Timer source during sleep) will be requested to be enabled

    Figure 5-120. Low Power Configuration
    For Zigbee applications the System Sleep mode is only enabled when using the following device types - Multisensor, Intruder Alarm System and Color Scene controller as per the Zigbee End Device Spec.
  2. Upon enabling Sleep mode, FreeRTOS related settings will be set automatically.
    • Tick Mode will be set to Tickless_Idle

    • Expected idle time before sleep will be set to 5 (ms)

    • Tick Hook will be enabled (For user to add any custom code needed to be executed within each tick interrupt)

    • RTC peripheral library will be added and configured

    Note: RTC counter must not be reset (RTC_Timer32CounterSet()) arbitrarily when the system is running
    Figure 5-121. FreeRTOS
  3. RTC clock source must be set manually, there are four options to choose from:

    • FRC (±1% offset)

    • LPRC ( with larger offset, < ±5%)

    • POSC <- Candidate of the clock source (better clock accuracy)

    • SOSC <- Candidate of the clock source (better clock accuracy)

    Users can select POSC or SOSC as the RTC clock source. Choosing FRC and LPRC as clock sources for RTC will impact BLE connection stability. In this example SOSC is configured as RTC clock source.

  4. In MCC, Click Plugins>Clock Configuration from drop down menu
    Figure 5-122. Clock Configurations
  5. In Clock Diagram,
    • Enable Secondary Oscillator (SOSC) by setting SOSCEN to ON

    • Select SOSC as clock source for VBKP_32KCSEL and set LPCLK_MOD to DIV_1_024 as illustrated in the following figure

      Figure 5-123. Clock Configuration
      Figure 5-124. Clock Configuration
  6. All Unused pins in the application needs to be set in input mode and the pulldown must be enabled for these pins. This can be configured inside ports available in system component configuration options.
    Figure 5-125. System Configurations
  7. The Pin PB5 functionality must be changed to GPIO to disable the JTAG functionality for reduced power consumption.
    Figure 5-126. Pin Configuration
    Figure 5-127. Pin Configuration Tab
  8. The PMU mode can be set to BUCK_PWM mode to attain less power consumption and the settings are available as part of Device Support as illustrated in the following figure.
    Figure 5-128. Device Support

Files and Routines Automatically Generated by the MCC

After generating the code from MCC interface by clicking Generate Code, below is the project folder structure.
Figure 5-129. Project Files

BLE, Zigbee Stack Initialization and Application Callback Registration:

The RF System, BLE System, ZIGBEE, PERIPHERAL initialization routine executed during program initialization can be found in SYS_Initialize() of initialization.c file.

Zigbee stack provides various APIs for application, and those APIs belong to the specific module within dedicated group. The sequence of initialization is already taken care in the stack when Zigbee_Init() from initialization.c is called.
Figure 5-130. initialization.c

The BLE stack initialization routine executed during application initialization can be found in APP_BleStackInit() in app.c. This call initializes and configures different BLE layers like GAP, GATT, SMP, L2CAP and BLE middleware layers and registers the application layer callbacks. The event callbacks from BLE stack, BLE middleware and profile/service layer are registered.

Also, the MCC configured advertisement data payload can be seen in APP_BleConfigBasic()
Figure 5-131. APP_BleConfigBasic()
Similar to BLE, Zigbee stack also generate events to inform application if there is any status changed or activity. Application may need to get the relevant information from Zigbee Stack and do the corresponding procedure.
Figure 5-132. app.c
BLE, Zigbee stack application events handling: app.c file is autogenerated and has a state machine for application callback handling from BLE, Zigbee stacks
Figure 5-133. app.c

BLE Zigbee Provisioning Manual Code Configuration

  • zigbeeAppDeviceSelect.h

    • Default Generated: “#define CS_UID 0 //Unique Identifier (UID) determining the device extended address”
    • Change to a unique value: “#define CS_UID 0x123bee //Unique Identifier (UID) determining the device extended address”
      Figure 5-134. zigbeeAppDeviceSelect.h
      Note: By default, the coordinator also has the same value. In a network the UID value must be unique
  • Open app.c file and include the header file app_prov.h as illustrated in the following figure.
    #include "app_prov/app_prov.h"
    Figure 5-135. app.c
  • In app.c, add the following code after APP_BleStackInit() in APP_Tasks function.
    APP_Prov_TRPS_Init();
    Figure 5-136. app.c
  • Open app_ble_handler.c file located in app_ble project folder. In APP_BleGapEvtHandler() function, add the following code as illustrated in the following figure.
    extern void APP_BleGapConnEvtHandler(BLE_GAP_Event_T *p_event);
    APP_BleGapConnEvtHandler(p_event);
    Figure 5-137. app_ble_handler.c
  • Open app_trsps_handler.c file. In APP_TrspsEvtHandler() function, add the below code as illustrated in the following figure.
    extern void APP_TRPS_EventHandler(BLE_TRSPS_Event_T *p_event);
    APP_TRPS_EventHandler(p_event);
    Figure 5-138. app_trsps_handler.c
  • Open app_zigbee_handler.c file, located in app_zigbee project folder. In Zigbee_Event_Handler() function, add the below code as illustrated in the following figure.
    extern void BZ_Prov_Zigbee_Event_Handler(APP_Zigbee_Event_t event);
    BZ_Prov_Zigbee_Event_Handler(event);
    Figure 5-139. app_zigbee_handler.c
  • Build Project, upon building project user action is required as mentioned User Action.
    • Open app_user_edits.c file. Comment out or remove the #error line. Update the freertos_hooks.c as mentioned in app_user_edits.c file
  • Compile and Run the project in the WBZ451 Curiosity board.

Protocol Exchange

  1. The communication protocol exchange between BLE Provisioner mobile app and the WBZ451 Module (BLE peripheral) is explained in the Zigbee Commissioning through BLE - Protocol Exchange section.