1 Feature Overview

1.1 BLE Config App Service Component

When regenerating an existing Bluetooth Low Energy (BLE) sample application from scratch, numerous code snippets must be manually inserted into various files before testing the application's functionality. The following steps are followed:

  1. Configure various components using MCC.
  2. Generate code by clicking the "Generate" button.
  3. Manually add code snippets to various files.
  4. Build the application.

The step of manually adding code snippets to various files is both cumbersome and time-consuming. Additionally, it increases the risk of errors if the code is not copied correctly.

By leveraging the “BLE Config App Service” component, all required code is automatically generated into app_ble_callbacks.c, app_ble_callbacks.h, app.c, app.h, app_utility.c, and app_utility.h files based on the Bluetooth Low Energy Stack settings. This enables seamless integration of the code.

Figure 1-1. BLE Config App Service

Features

  • Auto Generation of Code Based on BLE_STACK Settings.
  • Selection of MCHP or Custom Board.
  • Automatic Generation of Bluetooth Low Energy callback and utility files which enables users to utilize, add, or modify application code without needing to delve into the source files.

For more details on activating and using the “BLE Config App Service” component refer to the Getting Started with WME Bluetooth Low Energy Applications from Related Links.

1.2 WME Application Service Component

WME Application Service components are designed to improve existing profile components by replicating their GUI and incorporating several advanced features. For more details, see WME Application Service Components from Related Links.

1.3 Custom Protocol Service Component with GUI

Custom Protocol Application Service component help users to quickly design custom protocols over Bluetooth Low Energy custom service to their specific requirements. The ability to set custom protocols for characteristics over customized service would significantly enhance user flexibility and comfort. For more details, See Bluetooth Low Energy Custom Protocol Application Service from Related Links.

1.4 Enable App Code Generation

This feature includes an Enable/Disable switch that permits users to manage the generation of application code for a specific profile, as well as based on the configuration of the BLE stack component. When users enable application code generation, the necessary application code functions for the corresponding BLE stack settings and any existing profiles in the project will be generated. These generated application-specific functions will be included in both the generic callback file and the profile-specific callback file.

To illustrate the usage of the Enable App Code, we will use the “ble_ancs_application” as an example.

Files generated by Enable App Code Generation in Enabled state.

Figure 1-2. BLE Config App Service
Figure 1-3. Apple Notification App Service
Figure 1-4. Code Generated for ANCS
Figure 1-5. Code Generated for ANCS
Figure 1-6. Code Generated for ANCS
Files generated by Enable App Code Generation in Disabled state.
Figure 1-7. BLE Config App Service
Figure 1-8. Apple Notification App Service
Figure 1-9. No Code Generated for ANCS
Figure 1-10. No Code Generated for ANCS
Figure 1-11. No Code Generated for ANCS

1.5 Functions to Handle Event Handlers

During project development, users may need to incorporate business logic into applications for specific Bluetooth Low Energy or Bluetooth Low Energy profile/service events. This requires them to access handler files and add their logic to the relevant events, necessitating knowledge of both handler files and event triggering locations. By offering functions/APIs that follow a callback approach for these events, users can implement their logic directly within the callback functions, eliminating the need to manage handler files.

To illustrate, ‘ble_ancs_application’ is used as an example

Figure 1-12. app_ble_handler.c
Figure 1-13. app_ble_callbacks.c
Figure 1-14. app_ancs_handler.c
Figure 1-15. app_ancs_callbacks.c

1.6 Reduced Dependencies and Satisfiers Pop-up Messages

In the current project interface, when users drag and drop components such as the Bluetooth Low Energy Stack or any Profile components, dialogue boxes appear prompting them to confirm the addition or removal of dependent components. Users must add these dependent components, but the dialogue boxes may inadvertently allow them to skip this step. Furthermore, these mandatory dialogue pop-ups could negatively impact the user experience. Implementing WME and utilizing its components will result in fewer pop-up messages, thereby reducing the likelihood of users accidentally disabling or skipping components.

1.7 Auto Detect Existing BLE MCC Components and Generation of Application Code

Using the WME framework, the BLE App Config component and profile can detect existing Bluetooth Low Energy components and their settings, and subsequently generating application code based on those settings. For more information, refer to the following chapters from Related Links.

  1. BLE Config App Service Component
  2. WME Application Service Component
  3. Auto Configuration of BLE Stack
  4. Enable App Code Generation

1.8 Auto Configuration of BLE Stack

Upon activating the Profile App Service, the component stack will be automatically configured to meet the application's specific requirements based on the selected service configuration. To illustrate this feature, consider the Apple Notification App Service component. The image below shows the automatic configuration performed by the Apple Notification App Service. Users can view the auto-configured items highlighted in blue within the GUI.

Figure 1-16. Apple Notification App Service Component
Figure 1-17. BLE Stack Auto Configuration
Figure 1-18. BLE Stack Auto Configuration

1.9 Segregation of all MCC Configuration Items into configuration.h File

In the current implementation of all the Bluetooth® Low Energy MCC components, the values set by the user in the configuration option are directly used within the functions as hard-coded values. Similarly, Bluetooth Low Energy stack macros are defined in their respective header files such as ble_gap.h, ble_l2cap.h, ble_smp.h, gatt.h, and so on., and are assigned directly to the variable in application files. Implementing the WME framework and utilizing its components will result in the segregation of MCC configuration items into a single file (configuration.h), thereby eliminating all hard-coded numbers. The images below illustrate the file changes before and after the implementation of the WME framework for Bluetooth Low Energy stack configuration.

Figure 1-19. BLE Stack Configuration
Figure 1-20. Before WME Implementation (app_ble.c File)
Figure 1-21. After WME implementation (app_ble.c File)
Figure 1-22. configuration.h File

1.10 Reduced Number of Application Files

In the current implementation of the applications, several additional files related to Bluetooth Low Energy functionality, Bluetooth Low Energy profile-specific functionality, and non-Bluetooth Low Energy functionality are distributed throughout the src folder. The WME framework consolidates all code in these files into app_ble_callbacks.c, app_<profile>_callbacks.c, where <profile> may refer to ANCS, ANPS, so on., and app_utility.c. This reorganization simplifies the process for users, as they no longer need to search through multiple files to determine where to add or modify their code.

For example, in the ble_throughput_app, the highlighted files have been removed, and their code has been transferred to the corresponding callbacks file.

Figure 1-23. File Comparison

1.11 No User Code Inside app_ble.c and Reduced Merge Conflicts

In the existing implementation, the values set by the user in the Bluetooth Low Energy Stack component configuration options are directly used within the functions as hard-coded values. Similarly, Bluetooth Low Energy Stack macros are defined in their respective header files, such as ble_gap.h, ble_l2cap.h, ble_smp.h, gatt.h and so on., and are directly assigned to variables in the application files. All these actions occur in app_ble.c. When the user modifies the app_ble.c file and changes the Bluetooth Low Energy Stack configurations, there is a high likelihood of merge conflicts, which can lead to user confusion and the potential omission of code pieces while resolving these conflicts. With the WME framework, users are not permitted to make any changes to app_ble.c, and all Bluetooth Low Energy-related macros are generated in configuration.h. This approach significantly reduces the risk of merge conflicts.

  • Without WME

    • In the current implementation, the user edits the app_ble.c file.

      Figure 1-24. User Code in app_ble.c
    • The user changes BLE Stack settings.
      Figure 1-25. BLE Stack Settings
    • After generation, merge conflicts appear.
      Figure 1-26. Merge Conflict
  • With WME
    • In WME framework, instead of modifying app_ble.c, user modifies configuration.h.
    • After modifying the BLE Stack settings and generating the necessary files, a merge suggestion appears for configuration.h, making it easy for the user to proceed with the merges.
      Figure 1-27. Merge Suggestions

1.12 System Hardware Definitions support

System Hardware Definitions (SHD) offers a user-friendly interface through MCC, allowing users to automatically configure hardware settings and dependencies with a simple click in the board settings. Utilizing the WME framework, users can select the SHD component based on the device from the BLE Config App Service component and configure pins or enable peripherals according to the Development/Evaluation Boards in Microchip. For more information on how to activate SHD from the BLE Config App Service component, see Getting Started with WME Bluetooth Low Energy Applications from Related Links.

1.13 Debug Prints Instead of Console Prints

While the Console service component is useful for basic input/output operations and simple debugging tasks, the Debug service component offers a more comprehensive and powerful set of tools for in-depth debugging and diagnostics. Developers working on complex or performance-critical applications will likely benefit more from the advanced features provided by the Debug service component. The Debug service supports different system-defined Debug Levels (SYS_ERROR_FATAL, SYS_ERROR_ERROR, SYS_ERROR_WARNING, SYS_ERROR_INFO, SYS_ERROR_DEBUG), allowing messages to be filtered based on their severity. This feature helps in controlling the verbosity of the debug output.

1.14 Utility Functions for Advertising/Scan Response Data

Utility functions for Advertising and Scan Response data dynamically update the service data and user data of those packets through the application code, rather than through the stack configuration GUI, which employs macro configuration on the generated code. The system will generate these utility functions in all cases; however, users need to employ these functions when Legacy Advertisement is used.

Utility APIs

The APIs are detailed in the section below and can be found in the app_utility file. These APIs append or insert user input data into the appropriate locations within the advertisement or scan response packets, which are generated from the GUI.

  • APP_UTILITY_UpdateBleAdvServiceData()
    • Description: Append data on Bluetooth Low Energy service data of the advertising packet, which comes from the GUI configuration.
      Table 1-1. Parameters
      ParamDescription
      p_svcDataPointer to the uint8_t buffer, this buffer data will be appended on Bluetooth Low Energy service data of advertising packet
      svcDataLenLength of the buffer
      Table 1-2. Return Value
      Return ValDescription
      APP_UTILITY_SUCCESSSuccessfully appended to service data.
      APP_UTILITY_INVALID_LENAppend operation not allowed due to invalid length.
      APP_UTILITY_FAILAppend failure due to stack API call returned a failure.
  • APP_UTILITY_UpdateBleAdvUserData()
    • Description: Append data on Bluetooth Low Energy user data of the advertising packet, which comes from the GUI configuration.
      Table 1-3. Parameters
      ParamDescription
      p_userDataPointer to the uint8_t buffer, this buffer data will be appended on Bluetooth Low Energy user data of advertising packet.
      userDataLenLength of the buffer
      Table 1-4. Return Value
      Return ValDescription
      APP_UTILITY_SUCCESSSuccessfully appended to service data.
      APP_UTILITY_INVALID_LENAppend operation not allowed due to invalid length.
      APP_UTILITY_FAILAppend failure due to stack API call returned a failure.
  • APP_UTILITY_UpdateBleScanRspServiceData()
    • Description: Append data on Bluetooth Low Energy user data of the scan response packet, which comes from the GUI configuration.
      Table 1-5. Parameters
      ParamDescription
      p_svcDataPointer to the uint8_t buffer, this buffer data will be appended on Bluetooth Low Energy service data of the scan response packet.
      svcDataLenLength of the buffer
      Table 1-6. Return Value
      Return ValDescription
      APP_UTILITY_SUCCESSSuccessfully appended to service data.
      APP_UTILITY_INVALID_LENAppend operation not allowed due to invalid length.
      APP_UTILITY_FAILAppend failure due to stack API call returned a failure.
  • APP_UTILITY_UpdateBleScanRspUserData
    • Description: Append data on Bluetooth Low Energy user data of the scan response packet,which comes from the GUI configuration.
      Table 1-7. Parameters
      ParamDescription
      p_userDataPointer to the uint8_t buffer, this buffer data will be appended on Bluetooth Low Energy user data of the scan response packet.
      userDataLenLength of the buffer
      Table 1-8. Return Value
      Return ValDescription
      APP_UTILITY_SUCCESSSuccessfully appended to service data.
      APP_UTILITY_INVALID_LENAppend operation not allowed due to invalid length.
      APP_UTILITY_FAILAppend failure due to stack API call returned a failure.

Example Usage for Appending Service Data

All static data for advertising and scan response must be provided through the GUI by enabling the respective fields if they are being used. For instance, the user is configuring service data in the advertising data as illustrated in the following figure.

Figure 1-28. Service Data Append

In the above image, the service UUID is DAFE and the service data is FF01, which are static values. If the user wishes to append dynamic values to the service data at the end of FF01, they can use the update service data API after the Bluetooth Low Energy stack initialization. After calling the API, the user needs to re-enable the advertisement to restart it with the updated packet. For example, if the user wants to append "020304" to the service data along with FF01, they can use the following code:

uint8_t appendServiceData[]={0x02,0x03,0x04};
APP_UTILITY_UpdateBleAdvServiceData(appendServiceData,3);
BLE_GAP_SetAdvEnable(0x01, 0x00);
This code will append 020304 to the FF01 service data, updating it to FF01020304. If the user wants to dynamically update the entire service data, they must leave the service data field blank instead of using FF01 or any default value (the default value is 00, which must be removed to leave the field blank). Similarly, users can append service data in the scan response by using the respective API.
Note: Enabling service data and providing the service UUID is mandatory for users who wish to utilize the service data update APIs.

Example Usage for Appending User Data

As mentioned in the above section, first user need to configure all static data. For instance, the user wants to configure entire user defined data dynamically. For this user defined data must not be enabled or user defined data field must be blank as in the below image.

Figure 1-29. User Data Append

To add user-defined hex data "03031118," the user can utilize the following code:

uint8_t appendUserData[]={0x03,0x03,0x11,0x18};
APP_UTILITY_UpdateBleAdvUserData(appendServiceData,4);
BLE_GAP_SetAdvEnable(0x01, 0x00);

Similarly, users can append user data in the scan response by using the respective API.

Note: User-defined data must adhere to the appropriate Bluetooth Low Energy advertisement packet protocol.