3.20 Bluetooth® Low Energy ANCS Application

This section helps users to enable BLE ANCS (Apple Notification Center Service) profile on the Curiosity Board using MCC. In this application example ANCS client is implemented.

Users can either choose to run the precompiled application example .hex file on the Curiosity Board and experience the demo or can go through the steps involved in developing this application from scratch.

These examples are incrementally structured upon one another. Recommendation is to follow the examples in order, by learning the basic concepts first and then progressing to the more advanced topics.

Recommended Reading

  1. BLE Software Specification
  2. Getting Started with WME Bluetooth Low Energy Applications
Note: Refer to the Getting Started with WME Bluetooth Low Energy Applications from Related Links

Hardware Required

Table 3-52.  Hardware Required
ToolQty
Curiosity Board1
Micro USB cable1
iPhone1

Software Requirement

  • MPLAB X IPE: For programming the precompiled hex file.
  • MPLAB X IDE: For programming the application example.
  • Teraterm: Terminal Emulator for displaying UART output.

Programming the Precompiled Hex File or Application Example

Programming the .hex File using MPLAB X IPE

  1. Precompiled .hex files are located in “<Harmony Content Path>wireless_apps_ble\apps\ble_ancs_app\hex\ “ folder.
  2. For more information on the programming steps, refer to the Programming a Device in MPLAB IPE.
    Note: Users must choose the correct device and tool information.

Programming the Application using MPLAB X IDE

  1. Follow the steps mentioned in Running a Precompiled Example
  2. Open and program the application example “ble_ancs_app_xxxx.X” where xxxx refer to device (for example: WBZ451, project file: ble_ancs_app_wbz451.X) located in “<Harmony Content Path>\wireless_apps_ble\apps\ble_ancs_app\firmware” using MPLAB X IDE.

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

Demo Description

Developing the Application from scratch using MCC

This section explains the steps required by a user to develop this application example from scratch using MCC.
Note: It is recommended that new users of MCC to go through the MPLAB® Code Configurator (MCC) User's Guide.
  1. Create a new MCC Harmony Project by selecting the device. For more details, refer to Creating a New MCC Harmony Project.
  2. Launch the MPLAB Code Configurator from the toolbar as illustrated below. The project graph will open with the default components.
    Figure 3-268. MCC
  3. In the Device Resources window, expand Libraries > Harmony > Wireless > Application Services. Then, click the Plus Symbol to add the Apple Notification App Service Component to the project graph
    Figure 3-269. ANCS application service
  4. All BLE ANCS related components will be added into the project graph. Accept dependencies or satisfiers by selecting Yes
  5. To enable digital and communication interfaces, refer to Enabling Digital Input/Output and Communication Interfaces Through System Hardware Definition (SHD) component in Getting Started with WME Bluetooth Low Energy Applications from Related Links.
  6. Change the CONSOLE Component settings as illustrated in the following figure.
    Figure 3-270. Console Configuration
  7. Change the SERCOM0 Component settings as illustrated in the following figure.
    Figure 3-271. Sercom0 Configuration
  8. Change FreeRTOS component settings as illustrated in the following figure. For more details, refer to the Configuring FreeRTOS in Getting Started with WME Bluetooth Low Energy Applications from Related Links.
    Figure 3-272. FreeRTOS Configuration
  9. For WBZ451
    1. Add TRNG Component from Device Resource>Libraries>Harmony>Peripherals>TRNG.
      Figure 3-273. TRNG Component
    2. Verify if the project graph window has all the expected components, as illustrated in the following figure:
      Figure 3-274. Project Graph
    3. Disable Support Random Number Generation option in wolfCrypt Library component if it is in enabled state.
      Figure 3-275. Wolfcrypt Configuration
    4. Configure WBZ451-CURIOSITY for LED and switch, as illustrated in the following figure
      Figure 3-276. WBZ451-CURIOSITY Configuration
  10. For WBZ351
    1. Verify if the project graph window has all the expected components, as illustrated in the following figure:
      Figure 3-277. Project Graph
    2. Configure WBZ351-CURIOSITY for LED and switch, as illustrated in the following figure
      Figure 3-278. WBZ351-CURIOSITY Configuration
  11. Select the Apple Notification App Service component. In the Configuration Options, the Enable Client Role option will be enabled by default. If it is not enabled, ensure to enable the option. Additionally, ensure that the Enable App Code Generation option is enabled.
    Figure 3-279. Apple Notification App Service Component
    Figure 3-280. Apple Notification App service Configuration
  12. Enabling the client role option in Apple Notification App Service component will configure BLE Stack component . Additionally, selecting the Enable App Code Generation option will generate the necessary application files related to the service during the code generation process. Verify the BLE Stack configuration as illustrated in the following figure.
    Figure 3-281. BLE STACK Configuration
    Figure 3-282. BLE STACK Configuration

Generating a Code

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

Files Containing User Application Code

Source code for the application will be generated from the MCC interface by clicking Generate Code. User can add or edit the code in the highlighted files as shown below.
Figure 3-283. Source files
Details on files that user can modify
Table 3-53. Source Files
Source FilesUsage
app.cApplication State machine, includes calls for Initialization of all BLE stack (GAP,GATT, SMP, L2CAP) related component configurations
app_ble_callbacks.cAll the event functions related to GAP, GATT, SMP and L2CAP events that user can use or modify .
app_ancs_callbacks.cAll the event functions related to ANCS event handles that user can use or modify.
app_utility.cContains generic utility functions that serve the purpose of providing reusable, common functionalities that can be applied across various parts of a program.
Note: app.c is auto generated and has a state machine based application code sample. Users can use this template to develop their application. Main application logic is implemented in void APP_Tasks() function.
Figure 3-284. app.c
Figure 3-285. app.c

Firmware FSM(Finite State Machine)

This application firmware implements an ANCS client on the curiosity board.

  • APP_ANCS_STATE_IDLE:The application stays in the Idle mode.
  • APP_ANCS_STATE_ADV: The application is waiting for pairing for timeout_adv seconds.
  • APP_ANCS_STATE_ADV_DIR: The application is waiting for reconnection for timeout_adv_dir seconds.
  • APP_ANCS_STATE_CONN: The application is ready for sending commands/receiving notifications.
    Figure 3-286. Finite State Machine
    Table 3-54. Time Out Parameters
    VariableValueDescription
    timeout_adv60sThe timeout of advertising
    timeout_adv_dir30sThe timeout of directed advertising
    Table 3-55. LED vs. State
    Firmware StateLED behavior
    APP_ANCS_STATE_IDLEAll LEDs are OFF
    APP_ANCS_STATE_ADVBlue LED flashes one time every 3 seconds. (ON: 50 ms, OFF: 2950 ms)
    APP_ANCS_STATE_ADV_DIRBlue LED flashes two time every 3 seconds. (ON: 50 ms, OFF: 50 ms)
    APP_ANCS_STATE_CONNBlue LED flashes two times every 1.5 seconds. (ON: 50 ms, OFF: 150 ms)

    FSM of the Connection State

    State machine when connected:

    • APP_ANCS_IND_INIT: The application enters this state when connected.
    • APP_ANCS_IND_NTFY_ADDED: The application received the event “Notification Added” and is waiting for a button-pressing to send the command “Get Notification Attributes”.
    • APP_ANCS_IND_NTFY_ATTR: The application received the data related to “Notification Attributes” and is waiting for a button-pressing to send the command “Get App Attributes”.
    • APP_ANCS_IND_APP_ATTR: The application received the data related to “App Attributes” and is waiting for a button action to send the command “Perform Notification Action-Positive”/”Perform Notification Action-Negative”.
    • APP_ANCS_IND_NTFY_REMOVED: The application received the event “Notification Removed” and is waiting for another event “Notification Added”.
      Figure 3-287. Connection State FSM

References