HID Keyboard
Overview
This document details the Bluetooth Low Energy (BLE) Human Interface Device (HID) keyboard application. The application’s core functionality is driven by a predefined state machine, which helps in understanding its overall behavior.
Requirements
Atmosic EVK <board | serial>
This application supports the following Atmosic evaluation kits and reference designs:
Atmosic EVKs
Note
Currently, only the ATM33/e and ATM34/e series of Atmosic devices are supported.
Reference Design Boards
ATMKBD-3330e-HSC
ATMKBD-3430e-HSC
Behavior Summary
Upon power-on, the device continuously broadcasts advertising packets for a set duration. When a host detects the advertising and the keyboard receives the connection indication packet, the device transitions its state to initiate connection, pairing, and bonding procedures. During this phase, the host enables the Consumer Control Device (CCCD) bits of the Human Interface Device over GATT Profile (HOGP). Once these steps are complete, the application enters the MMI_S_HID_READY state, enabling the keyboard to send keycode packets to the host upon user input.
Building and Running
This application is built from atmosic-private/applications/hid_kb.
Build Without MCUboot
Build the Secure Processing Environment (SPE) and application:
west build -p always -b <BOARD>//ns atmosic-private/applications/hid_kb --sysbuild -T applications.hid_kb.atm
Build With OTA Support
Enable OTA via BLE and build the full image:
west build -p always -b <BOARD>@mcuboot//ns atmosic-private/applications/hid_kb --sysbuild -T applications.hid_kb.atm.mcuboot.ota
Note
The ota test item is built with -DDTS_EXTRA_CPPFLAGS="-DDFU_IN_FLASH", it requires to enable stack flash or external flash. If stack flash support, the flash is enabled by default.
Programming
To flash the built images:
west flash --skip-rebuild --verify --device <DEVICE_ID> --jlink --fast_load [--erase_flash]
Features
Special Combination Keys
This example demonstrates how to implement a handler for special combination keys. By default, it supports:
Fn + U: Removes the current bond and restarts advertising.
Fn + 0: Removes all bonds and restarts advertising.
Fn + 1: Switches to the first bonded/connected device.
Fn + 2: Switches to the second bonded/connected device.
Fn + 3: Switches to the third bonded/connected device.
Secure Connection Only Mode
This example supports secure connection only mode, the default is disabled, it can be enabled by setting prj.conf.
CONFIG_BT_SMP_SC_ONLY=y
CONFIG_BT_TINYCRYPT_ECC=y
The secure connection only mode is engineered with Bluetooth security mode 1, level 4. In others words, the secure level only supports Authenticated. So, the IO capability can not use NoInputNoOutput. And this keyboard example provides 2 types capability, at least one of the following two symbols must be selected.
CONFIG_HID_PASSKEY_DISPLAY=y
CONFIG_HID_PASSKEY_ENTRY=y
CONFIG_HID_PASSKEY_DISPLAY
When this configuration is enabled (CONFIG_HID_PASSKEY_DISPLAY=y), the device has the ability to display a passkey.
Behavior: The passkey is shown on the device via a debug log. The user must enter this passkey on the peer device to complete pairing.
CONFIG_HID_PASSKEY_ENTRY
When this configuration is enabled (CONFIG_HID_PASSKEY_ENTRY=y), the device has the ability to input a passkey.
Behavior: A passkey is displayed on the peer device (phone, PC), and the user must type this passkey using the keyboard to complete pairing.
LED Behavior
The LED feature is supported if CONFIG_KBD_LED=y, the reference designs are default enabled.
Four LED indications:
Caps Lock LED
Fn Lock LED
BLE Pairing LED
BLE Reconnecting LED
The behaviors:
Operation State |
LED Behavior |
|---|---|
Pairing |
Green LED1 blinking at 250ms interval |
Fn Lock |
Green LED1 on |
Caps Lock |
Green LED0 on |
Reconnecting |
Green LED1 blinking at 100ms interval |
Testing
After programming the firmware to the EVK, you can test it with a host which supports BLE keyboard device.
By default, the log feature was enabled by setting prj.conf file. P33 is the UART1_TX pin for output the log. 115200 is the default baud rate. Monitor the console output with a favorite terminal program.
Power on the EVK.
On the Windows, search for Bluetooth devices and find the device named “KBD-010”.
Connect to “KBD-010” and see the state become connected.
Open a text editor.
Type the keys on the keyboards.
Idle a while to reach idle timeout then the device will do disconnect and enter hibernation mode.
Press key to wake up and the keyboard will start advertising and then complete the reconnect procedure with the host.
Keyboard Matrices and Hardware Configuration
The keyboard scanner supports up to 8 rows by 20 columns or 20 rows by 8 columns. * The setting of rowX is to set rowX-pin = <pin-number> and rowX-ksi = <ksi-number> * The setting of columnX is to set colX-pin = <pin-number> and colX-kso = <kso-number>
The table below shows all pins’ possible KSI and KSO setting for ATMKBD-3330e-HSC and ATMKBD-3430e-HSC:
Pin |
alt0 |
alt1 |
alt2 |
alt3 |
|---|---|---|---|---|
P0 |
KSI_0 |
KSO_0 |
— |
— |
P1 |
KSI_1 |
KSO_1 |
— |
— |
P2 |
KSI_2 |
KSO_2 |
— |
— |
P3 |
KSI_3 |
KSO_3 |
— |
— |
P4 |
KSI_4 |
KSO_4 |
— |
— |
P5 |
KSI_5 |
KSO_5 |
— |
— |
P6 |
KSI_6 |
KSO_6 |
— |
— |
P7 |
KSI_7 |
KSO_7 |
— |
— |
P8 |
KSI_8 |
KSO_8 |
— |
— |
P9 |
KSI_9 |
KSO_9 |
— |
— |
P10 |
KSI_10 |
KSO_10 |
— |
— |
P11 |
KSI_11 |
KSO_11 |
— |
— |
P12 |
KSI_12 |
KSO_12 |
— |
— |
P13 |
KSI_0 |
KSO_0 |
— |
— |
P14 |
KSI_1 |
KSO_1 |
— |
— |
P15 |
KSI_13 |
KSI_2 |
KSO_2 |
— |
P16 |
KSI_14 |
KSI_3 |
KSO_3 |
— |
P17 |
KSI_15 |
KSI_4 |
KSO_4 |
— |
P18 |
KSI_16 |
KSI_5 |
KSO_5 |
— |
P19 |
KSI_17 |
KSI_6 |
KSO_6 |
— |
P20 |
KSI_7 |
KSO_7 |
— |
— |
P21 |
KSI_8 |
KSO_8 |
— |
— |
P22 |
KSI_9 |
KSO_9 |
— |
— |
P23 |
KSI_10 |
KSO_13 |
KSO_10 |
— |
P24 |
KSO_14 |
— |
— |
— |
P25 |
KSI_12 |
KSO_12 |
— |
— |
P26 |
KSI_19 |
KSI_0 |
KSO_19 |
KSO_0 |
P27 |
KSI_18 |
KSI_9 |
KSO_18 |
KSO_9 |
P28 |
KSI_10 |
KSO_15 |
KSO_10 |
— |
P29 |
KSI_11 |
KSO_16 |
KSO_11 |
— |
P30 |
KSI_11 |
KSO_17 |
KSO_11 |
— |
8 rows by 18 columns is the default setting and the table is shown below.
ROW Pin Assignments
ROW INDEX |
rowX-pin |
rowX-ksi |
|---|---|---|
ROW0 |
P2 |
2 |
ROW1 |
P3 |
3 |
ROW2 |
P1 |
1 |
ROW3 |
P5 |
5 |
ROW4 |
P6 |
6 |
ROW5 |
P7 |
7 |
ROW6 |
P4 |
4 |
ROW7 |
P9 |
9 |
COLUMN Pin Assignments
COL INDEX |
colX-pin |
colX-kso |
|---|---|---|
COL0 |
P13 |
0 |
COL1 |
P14 |
1 |
COL2 |
P15 |
2 |
COL3 |
P16 |
3 |
COL4 |
P17 |
4 |
COL5 |
P18 |
5 |
COL6 |
P19 |
6 |
COL7 |
P20 |
7 |
COL8 |
P21 |
8 |
COL9 |
P22 |
9 |
COL10 |
P10 |
10 |
COL11 |
P11 |
11 |
COL12 |
P12 |
12 |
COL13 |
P23 |
13 |
COL14 |
P24 |
14 |
COL15 |
P28 |
15 |
COL16 |
P29 |
16 |
COL17 |
P30 |
17 |