.. _hid_kb-application: 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 <:ref:`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: * 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: .. code-block:: console west build -p always -b //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: .. code-block:: console west build -p always -b @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: .. code-block:: console west flash --skip-rebuild --verify --device --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. .. code-block:: none 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. .. code-block:: none 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 :ref:`reference designs ` are default enabled. Four LED indications: * Caps Lock LED * Fn Lock LED * BLE Pairing LED * BLE Reconnecting LED The behaviors: .. list-table:: :width: 80% :header-rows: 1 * - 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. Debug Log --------- 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. Testing on Windows ^^^^^^^^^^^^^^^^^^ 1. Power on the EVK. 2. On the Windows, search for Bluetooth devices and find the device named "KBD-010". 3. Connect to "KBD-010" and see the state become connected. 4. Open a text editor. 5. Type the keys on the keyboards. 6. Idle a while to reach idle timeout then the device will do disconnect and enter hibernation mode. 7. 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 = ** and **rowX-ksi = ** * The setting of columnX is to set **colX-pin = ** and **colX-kso = ** The table below shows all pins' possible KSI and KSO setting for **ATMKBD-3330e-HSC** and **ATMKBD-3430e-HSC**: .. list-table:: ATMKBD-3330e-HSC/ ATMKBD-3430e-HSC Pin Configurations :width: 60% :header-rows: 1 * - 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** .. list-table:: Default Row Configuration (ATMKBD-3330e-HSC/3430e-HSC) :width: 40% :header-rows: 1 * - 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** .. list-table:: Default Column Configuration (ATMKBD-3330e-HSC/3430e-HSC) :width: 40% :header-rows: 1 * - 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