BR/EDR HID

The purpose of this document is to provide an overview of the BR/EDR HID demo application. The BR/EDR HID demo project offers a simple example on how to use HID. This project implements HID mouse and keyboard device.

For this profile, two roles are discussed:

HID Host - This is a device using or requesting the services of a Bluetooth HID device. Examples would be a personal computer or gaming console.
HID Device - This is a device providing the service of human or other data input and output to and from a Bluetooth HID host. Examples of Bluetooth HID devices are keyboards, mice and joysticks.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name	Build Target
RTL87x3E HDK	RTL87x3E EVB	`bt_hid_demo_1M_bank0` `bt_hid_demo_4M_bank0` `bt_hid_demo_16M_bank0`
RTL87x3D HDK	RTL87x3D EVB	`bt_hid_demo_16M_bank0`

Note

To purchase EVB, please visit https://www.realmcu.com/en/Home/Shop.

This sample project can be found under board\evb\bt_hid_demo in SDK folder structure. Developers can choose the project according to the Board Name and choose the Build Target according to the flash map.

When built for an xxx_1M_xxx build target, the sample is configured to build and run with a 1M flash map.

When built for an xxx_4M_xxx build target, the sample is configured to build and run with an 4M flash map.

When built for an xxx_16M_xxx build target, the sample is configured to build and run with a 16M flash map.

To quickly set up the development environment, please refer to the detailed instructions provided in Quick Start.

Tip

You can directly reference Quick Start to avoid repetitive descriptions.

The TX and RX PINMUX of console is defined in app_bt_hid_demo_main.c. It is important to note that the pins need to be wired in reverse, which means that the TX of console should be connected to P3_0, and the RX should be connected to P3_1 in order to establish a connection with the serial port.

#define BT_HID_DEMO_UART_TX          P3_1
#define BT_HID_DEMO_UART_RX          P3_0

Configurations

APP configurable functions are defined in sdk\src\sample\bt_hid_demo\app_flags.h.

#define BT_HID_DEMO_ROLE  1

#define F_APP_HID_MOUSE_SUPPORT     0
#define F_APP_HID_KEYBOARD_SUPPORT  1

The user can easily change the value of the macro definition to switch the function.

Building and Downloading

Note

This section introduces sample compilation methods (such as Keil, GCC, etc.) and how to download them to EVB (J-Link, MPPG Tool, etc.).

Take the project rtl87x3e_bt_hid_demo.uvprojx and target bt_hid_demo_4M_bank0 as an example, to build and run the sample with Keil development environment, follow the steps listed below:

Open rtl87x3e_bt_hid_demo.uvprojx.
Choose the build target bt_hid_demo_4M_bank0.

Choose Build Target
Build the target.

Building
Download APP bin to EVB board.

Tip

Quick Start includes sections like Generating APP Image and Images Download. If they are consistent, please directly reference them.

Experimental Verification

Note

This section introduces the console commands and test procedure during the experimental process.

HID Host CMD

HID Host Connect

User can input hid_host connect [remote address] below to connect HID with remote device. The remote address in the command is the remote Bluetooth device.

The console will print HID Host Connected! informing user that HID is connected.

HID Host Connect Command
Information	Description
Command	`hid_host connect`
Parameters	Remote Bluetooth address
Usage	Connect HID with remote device.
Example	`hid_host connect 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_host_connect_req().

HID connect flow is shown as follows.

../../../_images/hid_host_connect.png — HID Host Connect

HID Host Disconnect

User can input hid_host disconnect [remote address] command to disconnect HID with remote device. The remote address in the command is the remote Bluetooth device.

The console will print HID Host Disconnected! informing user that HID is disconnected.

HID Host Disconnect Command
Information	Description
Command	`hid_host disconnect`
Parameters	Remote Bluetooth address
Usage	Disconnect HID with remote device.
Example	`hid_host disconnect 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_host_connect_req().

HID disconnect flow is shown as follows.

../../../_images/hid_host_disconnect.png — HID Host Disconnect

HID Device CMD

HID Disconnect

User can input hid disconnect [remote address] command to disconnect HID with remote device. The remote address in the command is the remote Bluetooth device.

The console will print HID Disconnected! informing user that HID is disconnected.

HID Disconnect Command
Information	Description
Command	`hid disconnect`
Parameters	Remote Bluetooth address
Usage	Disconnect HID with remote device.
Example	`hid disconnect 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_connect_req().

HID disconnect flow is shown as follows.

../../../_images/hid_disconnect.png — HID Disconnect

HID Shift Left

User can input hid shift_left [remote address] command to move the mouse to left. The remote address in the command is the remote Bluetooth device.

HID Shift Left Command
Information	Description
Command	`hid shift_left`
Parameters	Remote Bluetooth address
Usage	Move the mouse to left.
Example	`hid shift_left 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_interrupt_data_send().

../../../_images/hid_shift_left.png — HID Shift Left

HID Shift Right

User can input hid shift_right [remote address] command to move the mouse to right. The remote address in the command is the remote Bluetooth device.

HID Shift Right Command
Information	Description
Command	`hid shift_right`
Parameters	Remote Bluetooth address
Usage	Move the mouse to right.
Example	`hid shift_right 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_interrupt_data_send().

../../../_images/hid_shift_right.png — HID Shift Right

HID Shift Up

User can input hid shift_up [remote address] command to move the mouse up. The remote address in the command is the remote Bluetooth device.

HID Shift Up Command
Information	Description
Command	`hid shift_up`
Parameters	Remote Bluetooth address
Usage	Move the mouse up.
Example	`hid shift_up 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_interrupt_data_send().

../../../_images/hid_shift_up.png — HID Shift Up

HID Shift Down

User can input hid shift_down [remote address] command to move the mouse down. The remote address in the command is the remote Bluetooth device.

HID Shift Down Command
Information	Description
Command	`hid shift_down`
Parameters	Remote Bluetooth address
Usage	Move the mouse down.
Example	`hid shift_down 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_interrupt_data_send().

../../../_images/hid_shift_down.png — HID Shift Down

HID Click

User can input hid click [remote address] command to click the mouse. The remote address in the command is the remote Bluetooth device.

HID Click Command
Information	Description
Command	`hid click`
Parameters	Remote Bluetooth address
Usage	Mouse click.
Example	`hid click 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_interrupt_data_send().

../../../_images/hid_click.png — HID Click

HID Click Keycode

User can input hid click_keycode [char] [remote address] command to input character. The char in the command is the character. The remote address in the command is the remote Bluetooth device.

HID Click Keycode Command
Information	Description
Command	`hid click_keycode`
Parameters	Character and remote bluetooth address
Usage	Keyboard input character.
Example	`hid click_keycode a 0x11 0x22 0x55 0x66 0x77 0x22`

The reference API can be found in bt_hid_device_interrupt_data_send().

../../../_images/hid_click_keycode.png — HID Click Keycode

Preparation Phase

Prepare two development boards named EVB-1 and EVB-2 respectively, and use DebugAnalyzer Tool to get the logs.
Set the macro BT_HID_DEMO_ROLE as 1, and then build the BR/EDR HID demo application, and download images into EVB-1, which acts as an HID Host. Users can also use a computer act as an HID host.
Set the macro BT_HID_DEMO_ROLE as 2, set the value of the macro F_APP_HID_MOUSE_SUPPORT or F_APP_HID_KEYBOARD_SUPPORT as 1 to implement mouse or keyboard, and then build the BR/EDR HID demo application, and download images into EVB-2, which acts as an HID device.

Testing Phase

HID Mouse Test

Proceed with the test procedure by following these steps:

Modify configuration in app_flags.h for the HID mouse device, then build and download the BR/EDR HID demo application to the EVB-2. According to the configuration below, EVB-2 acts as an HID mouse.
```
#define BT_HID_DEMO_ROLE  2

#define F_APP_HID_MOUSE_SUPPORT     1
#define F_APP_HID_KEYBOARD_SUPPORT  0
```
Press the Reset button on the EVB-2. Turn on Bluetooth from computer, and pair to hid device. The console will print HID Connected! informing user that HID is connected.
The user can input corresponding command referring to HID Device CMD. Remote address is the computer address.
- Input CMD hid shift_left to move the mouse cursor to left.
HID Shift Left

Uart Command to Input

Output of Uart Response

Description

hid shift_left [remote address]

HID mouse shift left!

Move the mouse cursor to the left.
- Input CMD hid shift_right to move the mouse cursor to right.
HID Shift Right

Uart Command to Input

Output of Uart Response

Description

hid shift_right [remote address]

HID mouse shift right!

Move the mouse cursor to the right.
- Input CMD hid shift_up to move the mouse cursor up.
HID Shift Up

Uart Command to Input

Output of Uart Response

Description

hid shift_up [remote address]

HID mouse shift up!

Move the mouse cursor up.
- Input CMD hid shift_down to move the mouse cursor down.
HID Shift Down

Uart Command to Input

Output of Uart Response

Description

hid shift_down [remote address]

HID mouse shift down!

Move the mouse cursor down.
- Input CMD hid click to click the mouse cursor.
HID Click

Uart Command to Input

Output of Uart Response

Description

hid click [remote address]

HID mouse click!

Click the mouse cursor.
- Input CMD hid disconnect to disconnect HID with remote device.
HID Disconnect

Uart Command to Input

Output of Uart Response

Description

hid disconnect [remote address]

HID Disconnected!

Disconnect HID with the remote device.

HID Keyboard Test

Proceed with the test procedure by following these steps:

Modify configuration in app_flags.h for the HID host, then build and download the BR/EDR HID demo application to the EVB-1. According to the configuration below, EVB-1 acts as an HID host.
```
#define BT_HID_DEMO_ROLE  1

#define F_APP_HID_MOUSE_SUPPORT     0
#define F_APP_HID_KEYBOARD_SUPPORT  1
```
Modify configuration in app_flags.h for HID keyboard device, then build and download the BR/EDR HID demo application to EVB-2. According to the configuration below, EVB-2 acts as an HID Keyboard.
```
#define BT_HID_DEMO_ROLE  2

#define F_APP_HID_MOUSE_SUPPORT     0
#define F_APP_HID_KEYBOARD_SUPPORT  1
```
User can also use a computer as HID host, then the remote address in HID Device CMD should be replaced with the computer address.
Press the Reset button on the EVB-1 and EVB-2.

Input CMD hid_host connect on EVB-1 to connect with EVB-2.

HID Host Connect
Uart Command to Input	Output of Uart Response	Description
`hid_host connect 0x11 0x22 0x55 0x66 0x77 0x22`	`HID Host Connected!` `HID Connected!`	HID host connects with HID device.

Input CMD hid click_keycode on EVB-2.

HID Click Keyboard
Uart Command to Input	Output of Uart Response	Description
`hid click_keycode [char] 0x11 0x22 0x33 0x66 0x77 0x00`	`[char]` `HID keyboard click keycode!`	Keyboard input character.

Code Overview

Note

This chapter provides a brief analysis of important code.

The BR/EDR HID demo application overview will be introduced according to the following parts:

The directories of the project and source code files will be introduced in chapter Source Code Directory.
The main function will be introduced in chapter Source Code Overview.

Source Code Directory

Project directory: sdk\board\evb\bt_hid_demo.
Source code directory: sdk\src\sample\bt_hid_demo.

Source files in the sample project are currently categorized into several groups as below.

└── Project: bt_hid_demo
    ├── include                       ROM UUID header files. Users do not need to modify it.
         └── cmsis                          The cmsis source code. Users do not need to modify it.
                  ├── startup_rtl87x3e.c
                  └── system_rtl87x3.c
         ├── Lib                                    Includes all binary symbol files that user application is built on.
         └── APP                                    The application source code.
                  ├── console_uart.c
                  ├── app_console_msg.c
                  ├── app_dlps.c
                  ├── app_io_msg.c
                  ├── app_bt_hid_demo_console.c
                  ├── app_bt_hid_demo.c
                  ├── app_bt_hid_demo_gap.c
                  ├── app_bt_hid_demo_link.c
                  └── app_bt_hid_demo_main.c

Source Code Overview

The main purpose of this chapter is to help APP developers familiarize with the development process related to BR/EDR HID demo.

Initialization

Main function is invoked when the EVB board is powered on and the chip boots up, and it performs the following initialization functions:

int main(void)
{
   board_init();
   driver_init();
   task_init();
   framework_init();
   app_bt_gap_init();
   app_bt_profile_init();
   app_bt_hid_demo_gap_init();
   app_bt_hid_demo_cmd_register();

   os_sched_start();

   return 0;
}

Please refer to HID demo source code for initialization function declaration.

More information on profiles initialization can be found in HID Host Init and HID Device Init.

HID Callback Message

APP can register HID callback function to handle different HID callback messages.

void app_bt_hid_demo_init(void)
{
   ...

   bt_mgr_cback_register(app_bt_hid_demo_device_cback);
}