5.1.4 HCI Application

This section explains how to develop Human-Computer Interaction (HCI) applications utilizing the Bluetooth® Low Energy (BLE) UART transport interface.

In the context of HCI with BLE UART, communication is established using the BLE protocol along with a Universal Asynchronous Receiver-Transmitter (UART) interface. BLE is a wireless communication standard designed for short-range communication between devices, offering lower power consumption than classic Bluetooth. UART is a hardware communication protocol that enables serial communication by transmitting data as a sequence of individual bits.

Combining BLE with UART allows for seamless and efficient data transmission between devices like microcontrollers, computers, and mobile phones without requiring a lot of power. This setup is particularly beneficial for applications where small data packets are exchanged frequently over moderate distances, such as in wearable devices, home automation systems and other IoT applications.

Thus, using BLE UART in HCI applications enables developers to create interfaces that can communicate wirelessly with user input and output devices, enhancing the user experience by integrating physical computing devices smoothly into human activities.

Users can choose to either run the precompiled Application Example hex file provided on the PIC32-BZ6 Curiosity Board or follow the steps to develop the application from scratch.

It is recommended to follow the examples in sequence to understand the basic concepts before progressing to the advanced topics.

Recommended Readings

  1. FreeRTOS and BLE Stack Setup – See Peripheral - FreeRTOS BLE Stack and App Initialize from Related Links.

  2. BLE Software Specification – See MPLAB® Harmony Wireless BLE in Reference Documentation from Related Links.

Hardware Requirement

Table 5-32. Hardware Prerequisites
S. No.

Tool

Quantity

1

PIC32-BZ6 Curiosity Board

1

2

Micro USB cable

1

3FTDI Cable1

SDK Setup

Refer to Getting Started with Software Development from Related Links.

Software Requirement

To install Tera Term tool, refer to the Tera Term web page in Reference Documentation from Related Links.

Programming the Precompiled Hex File or Application Example

Using MPLAB® X IPE:

  1. Import and program the precompiled hex file: <Harmony Content Path>\wireless_apps_pic32_bz6\apps\building_blocks\hci_application\precompiled_hex
  2. For detailed steps, refer to Programming a Device in MPLAB® IPE in Reference Documentation from Related Links.
    Note: Ensure to choose the correct Device and Tool information.

Using MPLAB® X IDE:

  1. Perform the following the steps mentioned in Running a Precompiled Example. For more information, refer to Running a Precompiled Application Example from Related Links.
  2. Open and program the application: HCI_application.X.production.x located in <Harmony Content Path>\wireless_apps_pic32_bz6

    \apps\building_blocks\hci_application\ble_HCI_interface_app\firmware.

  3. For more details on how to find the Harmony Content Path, refer to Installing the MCC Plugin from Related Links.

Demo Description

This application example showcases the implementation of Human-Computer Interaction (HCI) capabilities. The testing phase of the application involves using a PIC32-BZ6 Curiosity Board as the host device, which is interfaced with a Linux desktop computer. Once the setup is correctly configured, communication with the BLE_UART is established through the transmission of HCI commands. This allows for the evaluation and demonstration of the application's HCI features in a controlled environment.

Developing the Application from Scratch Using the MPLAB Code Configurator

Follow the steps below to build the application manually:
Note: It is recommended for the new users of the MPLAB Code Configurator to refer MPLAB® Code Configurator (MCC) User’s Guide in Reference Documentation from Related Links.

  1. Create a new harmony project. For more details, see Creating a New MCC Harmony Project from Related Links.

  2. To setup the basic components and configuration required to develop this application, import component configuration:

    The imported file is of format .mc3 and is located in the path <Harmony Content Path>\wireless_apps_pic32_bz6\apps\building_blocks\hci_application\ble_HCI_interface_app\firmware\HCI_application.X.

    Note: Import and export functionality of the Harmony component configuration will help users to start from a known working setup of the MCC configuration.
  3. Accept dependencies or satisfiers when prompted.
  4. Verify if the project graph window has all the expected configuration.

Verifying Configurations

Components Present in the Project Graph

  1. Select BLE_Stack component in project graph.
    1. Enable BLE Controller Only option by clicking the tick on the checkbox.
  2. Select System component in project graph.
    1. Choose DIRECT in SERCOM0 Direct Pin Enable option.
  3. Select SERCOM0 component in project graph.
    1. Ensure that the following configuration has done.

Verifying the DMA Configuration

  1. Select the drop-down symbol for the Plug-ins option and select DMA Configuration.
  2. Select the Channel Number DMAC Channel 0 from the Active Channels List .
    1. Once you select DMAC Channel 0, the respective channel’s settings will populate the right side of the Active Channel List.
    2. Ensure that the settings match those shown in the following figure.
  3. Select the Channel Number DMAC Channel 1 from the Active Channels List .
    1. Once you select DMAC Channel 1, the respective channel’s settings will populate the right side of the Active Channel List.
    2. Ensure that the settings match those shown in the following figure.
  4. Enable Run Channel in Standby Mode for DMAC Channel 0 and 1 in the System Component Configuration.

NVIC Configuration

  1. Click the drop-down symbol for the Plugins option and select NVIC Configuration.
  2. Set DMA priority as 3 for DMAC_0_3 (DMA Channel 0..3).
    1. Tick the enable check box.
    2. Set the Priority to 3.
    3. Set the handler name to DMAC_0_3_InterruptHandler.

PIN Configurations

  1. Click the drop-down symbol for the Plug-ins option and select PIN Configuration.
  2. Configure RA5 and RA6 as GPIO pins and set these UART Rx/Tx pins to pull high.

Generating a Code

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

Files and Routines Automatically Generated by the MCC

After generating the program source from MCC interface by clicking Generate Code, the BLE configuration can be found in the following project directories.

User Application Development

  1. Include
    • Include the user action. For more information, refer to User Action from Related Links.
    • definitions.h in all the files where UART will be used to print debug information
      Note: The definitions.h is not specific to just UART peripheral, instead it should be included in all application source files where peripheral functionality will be exercised.
  2. In the App.h file, reduce the msgData array size in the APP_Msg_T structure.
    Modify the size of msgData to 32 bytes from the default size of 256 bytes. This change is recommended because when the App task sends a message, it disables all interrupts. A smaller message size can reduce the duration of the critical section.
  3. How to process received HCI commands and ACL packets:
    • Define the UART packet type – The HCI MCC configuration is transport independent and requires the creation of the packet type definition when deciding to use UART transport.
      HCI Packet TypeHCI Packet Indicator
      HCI Command Packet0x01
      HCI ACL Data Packet0x02
      HCI Synchronous Data Packet0x03
      HCI Event Packet0x04
      HCI ISO Data Packet0x05
    Example:
  4. Parse incoming UART data to identify the packet type and the corresponding format to determine the packet length. This is crucial to ensure the receipt of the complete packet (refer to the Reference section for the HCI packet format).
    Example of receiving a packet:
    1. Invoke DMAC_ChannelTransfer() with a block size of 4 bytes to capture the first 4 bytes, which include the packet type and header.
    2. Verify the packet type and extract the length (note that the buffer size is currently 251 bytes; the upper byte is always 0x00, so extracting the first byte of length from the ACL packet is sufficient).
    3. Use DMAC_ChannelTransfer() again to collect the remaining data based on the length specified in the packet header.
    4. Once a complete HCI packet is received via the UART DMA RX callback, send a message containing the command or ACL packet to the App layer.
    5. Depending on the packet type, invoke HCI_Cmd() or HCI_AclTx() API to pass the received packet to the controller.
  5. How to process and output HCI events and ACL packets:
    1. Implement the code to output packets via UART in the APP_BleStackEvtHandler() section of app_ble_hci.c File
  6. Handle HCI vendor commands by parsing and processing them in the APP_BleStackEvtHandler() section of app_ble_hci.c file.

Use the HCI_AppCmdComplEvt() or HCI_AppCmdStatusEvt() APIs to respond to vendor commands.

Different BLE Stack Memory Configuration

There are three build option examples on how to reduce memory size if it is a concern; otherwise, use the default setting to maintain full functionality.

Feature

Define

Default Setting

Common Memory Size

Note

Baud Rate

Central role high throughput

APP_CEN_SINGLE_HIG_THROUGH

Disable

16KB

ACL Tx buffer number = 12

921600

Central role low throughput

APP_CEN_SINGLE_LOW_THROUGH

Disable

14KB

ACL Tx buffer number = 4

115200

Peripheral role low throughput

APP_PER_SINGLE_LOW_THROUGH

Disable

14KB

ACL Tx buffer number = 4

115200

Full function

Enable

28KB

ACL Tx buffer number = 12

115200

  • The values for common memory size mentioned above are obtained from the BLE Memory Usage, refer to BLE Memory Usage in Reference Documentation from Related Links. If additional features are added, refer to this section and increase the common memory size (Data memory) in initialization.c.
  • When using high throughput for the Central, set the UART baud rate to 921600; otherwise, set it to 115200 in the plib_sercom0_usart.c file.

Rework HCI Interface for PIC32-BZ6 Curiosity Board

The PIC32-BZ6 must be reworked to disconnect the chip from the MCP2200.

Reworks Steps:

1.Remove R600 and R601.

Note:
  • When we need to input the UART data in TP9(RXD) and TP10(TXD), we need to remove R1 and R2 jumper to disconnect MCP2200.
  • If we use TP9 and TP10 to input UART data and do not removing the R1 and R2 jumpers, the UART data will be affected by the MCP2200, and the data may be incorrect.
  • When we need to update HEX file, we need to connect the R1 and R2 jumper.
Table 5-33. Pin to Pin connection

FTDI

PIC32-BZ6

VCCIO

X

TXD

RX

RXD

TX

RTS

CTS

GND

GND

CTS

RTS

References

HCI Command Packet Format:
Figure 5-160. HCI Command Packet Format

Op_Code: Size: 2 octets

ValueParameter Description
0xXXXX

OGF Range (6 bits): 0x00-0x3F (0x3F reserved for vendor-specific debug commands)

OCF Range (10 bits): 0x0000-0x03FF

Parameter_Total_Length: Size: 1 octet

ValueParameter Description
0xXX

Lengths of all of the parameters contained in this packet measured in octets. (N.B.: total length of parameters, not number of parameters)

HCI ACL Packet Format:
Figure 5-161. HCI ACL Packet Format

Handle: Size: 12 bits

ValueParameter Description
0xXXX

Connection_Handle to be used for transmitting a data packet or segment over a Primary Controller.

Logical_Link_Handle to be used for transmitting a data packet over an AMP Controller.

On the receiving side (AMP Controller to Host), the least significant 8 bits of the Handle is the Physical_Link_Handle and the most significant 4 bits are reserved. (This is because certain AMP Controllers might not be able to provide the logical link context on the receiving side, and the Host does not require it.)

Range: 0x000-0xEFF (0xF00 - 0xFFF Reserved for future use)

Packet_Boundary_Flag: Size: 2 Bits
ValueParameter DescriptionACL-UAMP-ULE-U
0x00

First non-automatically flushable packet of Higher Layer Message (start of a non- automatically flushable L2CAPPOU) from Host to Controller. Shall not be used on a BR/EOR Controller from Controller to Host.

Host to Controller

Allowed

Not allowed

Allowed

Controller to Host

Not allowed (except during loop- back)

Not allowedNot allowed
01

Continuing fragment of Higher Layer Message

Host to ControllerAllowedNot allowedAllowed
Controller to HostAllowedNot allowedAllowed
10First automatically flushable packet of Higher Layer Message (start of an automatically flushable L2CAP PDU)Host to ControllerAllowedNot allowedNot allowed
Controller to HostAllowedNot allowedAllowed
11A complete L2CAP PDU. Automatically flushableHost to ControllerAllowedAllowedNot allowed
Controller to HostNot allowedAllowedNot allowed