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:

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

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

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

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

To quickly set up the development environment, you can refer to Hardware Development Environment.

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

The detailed information about Building and Downloading can be found in Building and Downloading.

This sample can be found under sdk\board\evb\bt_hid_demo in SDK folder structure. 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.
Building the target.

After a successful compilation, the APP bin file bt_hid_demo_bank0_MP-v0.0.0.0-xxx.bin will be generated in the directory bin\rtl87x3e\flash_4M_dualbank\bank0.
Download APP bin into EVB board.

Experimental Verification

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

HID Host CMD

HID Host Connect

The flow of the hid_host connect command is to connect HID with remote device.

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

hid_host connect [remote address]

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

Information	Description
Command	Input command: hid_host connect [remote address]
Usage	Connect HID with remote device.

The reference API can be found in bt_hid_host_connect_req. HID connect flow is shown as follows.

HID Host Disconnect

The flow of the hid_host disconnect command is to disconnect HID with remote device.

User can input command below to disconnect HID. The remote address in the command is the remote Bluetooth device.

hid_host disconnect [remote address]

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

Information	Description
Command	Input command: hid_host disconnect [remote address]
Usage	Disconnect HID with remote device.

The reference API can be found in bt_hid_host_disconnect_req. HID disconnect flow is shown as follows.

HID Device CMD

HID Disconnect

The flow of the hid disconnect command is to disconnect HID with remote device.

User can input command below to disconnect HID. The remote address in the command is the remote Bluetooth device.

hid disconnect [remote address]

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

Information	Description
Command	Input command: hid disconnect [remote address]
Usage	Disconnect HID with remote device.

The reference API can be found in bt_hid_device_disconnect_req. HID disconnect flow is shown as follows.

HID Shift Left

The flow of the hid shift_left command is to move the mouse to left.

User can input command below to move the mouse to left. The remote address in the command is the remote Bluetooth device.

hid shift_left [remote address]

Information	Description
Command	Input command: hid shift_left [remote address]
Usage	Move the mouse to left.

The reference API can be found in bt_hid_device_interrupt_data_send. HID shift left flow is shown as follows.

HID Shift Right

The flow of the hid shift_right command is to move the mouse to right.

User can input command below to move the mouse to right. The remote address in the command is the remote Bluetooth device.

hid shift_right [remote address]

Information	Description
Command	Input command: hid shift_right [remote address]
Usage	Move the mouse to right.

The reference API can be found in bt_hid_device_interrupt_data_send. HID shift right flow is shown as follows.

HID Shift Up

The flow of the hid shift_up command is to move the mouse up.

User can input command below to move the mouse up. The remote address in the command is the remote Bluetooth device.

hid shift_up [remote address]

Information	Description
Command	Input command: hid shift_up [remote address]
Usage	Move the mouse up.

The reference API can be found in bt_hid_device_interrupt_data_send. HID shift up flow is shown as follows.

HID Shift Down

The flow of the hid shift_down command is to move the mouse down.

User can input command below to move the mouse down. The remote address in the command is the remote Bluetooth device.

hid shift_down [remote address]

Information	Description
Command	Input command: hid shift_down [remote address]
Usage	Move the mouse down.

The reference API can be found in bt_hid_device_interrupt_data_send. HID shift down flow is shown as follows.

HID Click

The flow of the hid click command is to click the mouse.

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

hid click [remote address]

Information	Description
Command	Input command: hid click [remote address]
Usage	Mouse click.

The reference API can be found in bt_hid_device_interrupt_data_send. HID click flow is shown as follows.

HID Click Keycode

The flow of the hid click_keycode command is to input character.

User can input command below 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 [char] [remote address]

Information	Description
Command	Input command: hid click_keycode [char] [remote address]
Usage	Keyboard input character.

The reference API can be found in bt_hid_device_interrupt_data_send. HID click keycode flow is shown as follows.

Test Procedure

This section describes the testing process and expected test results of BR/EDR HID demo.

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. According to the configuration below, EVB 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
```
Power on EVB, 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.
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.
Uart Command to Input

Output of Uart Response

Description

hid shift_right [remote address]

HID mouse shift right!

Move the mouse cursor to right.
- Input CMD hid shift_up to move the mouse cursor 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.
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.
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.
Uart Command to Input

Output of Uart Response

Description

hid disconnect [remote address]

HID Disconnected!

Disconnect HID with 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.
The user can input corresponding command referring to HID Host CMD and HID Device CMD.
- Input CMD hid_host connect on HID host to connect with HID device.
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 HID device to implement keyboard input.
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

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             
   └── cmsis                      		includes startup code
	   ├── startup_rtl87x3e.c
	   └── system_rtl87x3.c
   ├── Lib                      		includes all binary symbol files that user application is built on
   └── APP                      		includes the find my user application implementation
	   ├── 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

Initialization

main() is invoked when the application is powered on or the chip is reset, 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 different callback functions to handle different profiles.

void app_bt_hid_demo_init(void)
{
    ...

    bt_mgr_cback_register(app_bt_hid_demo_cback);
}