4.2.4 BLE HID over GATT Profile Service

Getting Started

Getting Started with Peripheral Building Blocks

Introduction

The HID over GATT profile defines the procedures and features to be used by Bluetooth Low Energy HID Devices using GATT and Bluetooth HID Hosts using GATT. This profile is an adaptation of the USB HID specification to operate over a Bluetooth low energy wireless link.

The HID Over GATT Profile (HOGP) is a Bluetooth SIG (Special Interest Group) standard that defines how HID information is exposed and exchanged over the Generic Attribute (GATT) protocol in BLE. HOGP extends the capabilities of BLE devices to support HID functionality.

HOGP is built on top of the BLE protocol stack and uses GATT for communication. It leverages the GATT Server-Client architecture to enable HID devices to send and receive HID reports.

Recommended Reading

  1. BLE Software Specification

  2. FreeRtos BLE App Initialize

  3. Low Power Notes

Hardware Requirement

Tool Qty
WBZ351 Curiosity Board 1
Micro USB cable 1

Current measured in Extreme Deep Sleep mode as per Wireless_ble v 1.1.0 and Wireless_pic32cxbz_wbz v1.2.0 in A2 version of WBZ351 module is around 131 nA.

SDK Setup

  1. Gettting Started with Software Development

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_pic32cxbz3_wbz35\apps\ble\advanced_applications\ble_hogps_app\hex" folder

  2. Follow the steps mentioned here

Caution: Users should choose the correct Device and Tool information

Programming the Application using MPLABX IDE

  1. Follow steps mentioned in of Running a Precompiled Example document

  2. Open and program the Application Example "lle_hogps_app.X\" located in "<Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\advanced_applications\ble_hogps_app\firmware\ble_hogps_app.X" using MPLABX IDE

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

Application building component

Below captured are the components used to create the HID Over GATT Profile Service application.

The MCC support the HID profile and services that helps to implement the HID feature. And also the other mandatory components listed earlier is also available as a drag and drop components in the mcc.

Role Descriptions

GATT Server Role

In the context of HOGP, the GATT Server role is typically assumed by the HID device. The GATT Server exposes HID services and characteristics, making the device accessible to GATT Clients. It supports
  • One or more instances of HID Service
  • One or more instances of battery services
  • Single instance of device information service
  • Optionally, one instance of Scan server role of Scan parameter profile.
GATT Client Role:

GATT Clients, such as smartphones or computers, interact with HID devices by discovering and accessing HID services and characteristics. They initiate actions based on user input or requirements. It supports Scan Client role of the Scan parameter profile

Pairing and Security

Security is crucial when dealing with HID devices, especially in scenarios where sensitive data may be transmitted.

The HID Host shall bond with the HID Device. The HID Host shall support LE Security Mode 1 and Security Level 2 and optionally Security Level 3.

Demo Description

The HID Over GATT Profile (HOGP) application on the Curiosity board simulates a keyboard and utilizes Device in a state machine. This guide will walk you through the application's key features, states, and interactions, allowing you to harness the power of HID technology on your Curiosity board.

This application implements the HID over GATT profile, Human Interface Device Service, Battery Service and Device information in a peripheral role.

Working Flow

Initial Power Off and On:
  • Power Off: The device is initially powered off.
  • Power On:
    • Upon powering on, the device checks for the existence of pairing data.
    • If pairing data doesn't exist, the device enters the APP_HOGPS_STATE_ADV state with a timeout of timeout_adv seconds.
    • If a connection is established within the timeout period, the following actions occur on the computer's side:
      • The device stores new pairing data.
      • The device removes any previous pairing data if it exists.
    • After successful pairing, the device enters the APP_HOGPS_STATE_CONN state.
    • If the connection fails to establish within the timeout, the device enters the APP_HOGPS_STATE_IDLE (Extreme Deep Sleep) state.
  • Connected State (APP_HOGPS_STATE_CONN):
    • Idle Timeout: While in the connected state, if Button 1 is not pressed for 3 minutes, the device enters the APP_HOGPS_STATE_IDLE (Extreme Deep Sleep) state to conserve power.
    • Long Press Button 1: In the connected state, if Button 1 is long-pressed:
      • The device starts a new pairing process.
      • The device enters the APP_HOGPS_STATE_ADV state.
    • Button 1 Press (Device): In the connected state, pressing Button 1 on the device results in showing "abcde" as output.
    • Button 1 Press (Computer): On the computer side, pressing Caps Lock while in the connected state shows either "capon" or "capof."
    • Connection Termination: In the connected state, the following events can lead to disconnection and state transitions:
      • If the computer removes the device from its device list or turns off Bluetooth.
      • If the device goes out of range.
      • In either case, the device enters the APP_HOGPS_STATE_ADV_DIR state with a timeout of timeout_adv_dir seconds.
  • Reconnection State (APP_HOGPS_STATE_ADV_DIR):
    • Long Press Button 1: While in the APP_HOGPS_STATE_ADV_DIR, a long press of Button 1 by the device starts a new pairing process.
    • Connection Attempt Result: Depending on the result of the connection attempt:
      • If the connection is successful, the device transitions back to the APP_HOGPS_STATE_CONN state.
      • If the connection attempt fails (e.g., due to a timeout or unsuccessful pairing), the device enters the APP_HOGPS_STATE_IDLE (Extreme Deep Sleep) state.
  • Direct Transition with Existing Pairing Data:
    • Initial Power On (With Existing Pairing Data):
If pairing data already exists during the initial power on, the device directly enters the APP_HOGPS_STATE_ADV_DIR state without going through the APP_HOGPS_STATE_ADV state

States and their Descriptions

  1. APP_HOGPS_STATE_IDLE: In this state, the application enters Extreme Deep Sleep mode to minimize power consumption. It remains in this state when not actively engaged.
  2. APP_HOGPS_STATE_ADV: When in this state, the application is waiting for pairing to occur, and it does so for a duration specified by timeout_adv (60 seconds by default).
  3. APP_HOGPS_STATE_ADV_DIR: In this state, the application is waiting for reconnection and awaits the pairing process to start. The duration for this state is determined by timeout_adv_dir (30 seconds by default).
  4. APP_HOGPS_STATE_CONN: The application enters this state when it is ready to send keys or receive events. It responds to Button 1 presses in this state.

Button 1 Interactions

  • Press Button 1 (Short Press) in APP_HOGPS_STATE_CONN: This action results in the display of "abcde" on the connected computer. It is a basic input action.
  • Long Press Button 1 in APP_HOGPS_STATE_CONN: A long press of Button 1 in the connected state leads to the disconnection of the device from the computer and initiates a new pairing process.
  • Long Press Button 1 in APP_HOGPS_STATE_ADV_DIR: A long press of Button 1 in the ADV_DIR state starts a new pairing process.
  • Press Button 1 in APP_HOGPS_STATE_IDLE: Pressing Button 1 in the Idle state wakes the device up from Extreme Deep Sleep mode.

LED indications

The LEDs on the Curiosity Board indicate the current state of the application:
  • APP_HOGPS_STATE_IDLE: In this state, all LEDs are turned off to conserve power.
  • APP_HOGPS_STATE_ADV: A blue LED flashes once every 3 seconds, with an on-time of 50 ms and an off-time of 2950 ms.
  • APP_HOGPS_STATE_ADV_DIR: A blue LED flashes twice every 3 seconds, with an on-time of 50 ms and an off-time of 50 ms.
  • APP_HOGPS_STATE_CONN: A blue LED flashes twice every 1.5 seconds, with an on-time of 50 ms and an off-time of 150 ms.

Connection Timeout

The application is designed to terminate the connection and enter Extreme Deep Sleep mode if Button 1 is not pressed for 3 minutes during an active connection, likely to save power

Testing

Environment Setup

  • A Microsoft Window 10 computer, “the computer” is used instead in the following section.
  • A WBZ351 Curiosity Board , "the curiosity board" is used instead in the following section

Test 1: Establishing Connection and Simulating Keyboard Behavior

Objective: Demonstrate connection establishment, keyboard simulation, and reconnection with the curiosity board.

Steps:
  • On the computer:
    • Remove the existing "Microchip Keyboard" pairing over BLE if it exists.
  • For the curiosity board:
    • Compile and program the application.
    • The curiosity board will enter APP_HOGPS_STATE_ADV and wait for pairing for timeout_adv seconds.
  • On the computer:
    • Open "Settings -> Bluetooth & other devices -> Add a device -> Bluetooth."
    • Click "Microchip Keyboard" to connect and pair with the curiosity board.
  • For the curiosity board:
    • It will enter APP_HOGPS_STATE_CONN when the connection is established.
  • On the computer:
    • Open a text editor (e.g., Notepad) and click the left mouse button to focus on it.
  • On the curiosity board:
    • Press Button 1.
  • On the computer:
    • The text editor will display "abcde."
  • On the computer:
    • Turn on Caps Lock, and the text editor will display "CAPON."
  • On the curiosity board:
    • Press Button 1.
  • On the computer:
    • The text editor will display "ABCDE."
  • On the computer:
    • Turn off Caps Lock, and the text editor will display "capof."
  • On the curiosity board:
    • Unplug the USB cable to power off.
  • On the computer:
    • The status of "Microchip Keyboard" should show as "Paired" (disconnected).
  • On the curiosity board:
    • Plug the USB cable to power on.
    • The curiosity board will enter APP_HOGPS_STATE_ADV_DIR and wait for reconnection for timeout_adv_dir seconds.
  • On the computer:
    • The status of "Microchip Keyboard" should show as "Connected."
  • For the curiosity board:
    • It will enter APP_HOGPS_STATE_CONN when the reconnection is successful.

Test 2: Reconnecting to Curiosity Board

Objective: Demonstrate how to reconnect to the curiosity board after it has disconnected.

Steps:
  • For the curiosity board:
    • Move it far away from the computer to disconnect.
    • The curiosity board will enter APP_HOGPS_STATE_ADV_DIR and wait for reconnection for timeout_adv_dir seconds.
  • On the computer:
    • The status of "Microchip Keyboard" should show as "Paired."
  • For the curiosity board:
    • Move it close back to the computer and press Button 1 to wake it up.
  • For the curiosity board:
    • It will automatically reconnect to the computer after successful disconnection.
    • The curiosity board will enter APP_HOGPS_STATE_CONN when the reconnection is successful.
  • On the computer:
    • The status of "Microchip Keyboard" should show as "Connected."

Test 3: Removing and Redoing Pairing

Objective: Demonstrate the removal of existing pairing data and redoing the pairing with the curiosity board.

Steps:
  • On the computer:
    • Remove the existing "Microchip Keyboard."
  • For the curiosity board:
    • Unplug the USB cable to power off.
  • For the curiosity board:
    • Plug the USB cable to power on.
    • The curiosity board will enter APP_HOGPS_STATE_ADV_DIR and wait for reconnection for timeout_adv_dir seconds.
  • On the curiosity board:
    • Long-press Button 1.
  • On the computer:
    • Open "Settings -> Bluetooth & other devices -> Add a device -> Bluetooth."
    • Click "Microchip Keyboard" to connect and pair with the curiosity board.
  • For the curiosity board:
    • It will enter APP_HOGPS_STATE_CONN when the connection is established.
    These testing procedures provide a step-by-step guide for validating the behavior of the curiosity board in different scenarios, including initial pairing, disconnection, reconnection, and pairing data removal.