ble_hids.h

/*
 * Copyright (c) 2012 - 2025 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef BLE_HIDS_H__
#define BLE_HIDS_H__
 
#include <stdint.h>
#include <stdbool.h>
#include <ble.h>
#include <ble_gap.h>
#include <ble_gatts.h>
#include <bm/bluetooth/ble_common.h>
#include <bm/softdevice_handler/nrf_sdh_ble.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define BLE_HIDS_DEF(_name)                                                                        \
        static struct ble_hids _name = {                                                           \
                .link_ctx_storage = {                                                              \
                        .max_links_cnt = CONFIG_BLE_HIDS_MAX_CLIENTS,                              \
                        .link_ctx_size = sizeof(uint32_t) * BYTES_TO_WORDS(BLE_HIDS_LINK_CTX_SIZE),\
                },                                                                                 \
        };                                                                                         \
        NRF_SDH_BLE_OBSERVER(_name##_obs, ble_hids_on_ble_evt, &_name, HIGH)
 
#define BLE_HIDS_CONFIG_SEC_MODE_DEFAULT_MOUSE                                                     \
        {                                                                                          \
                .hid_info_char.read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                           \
                .report_map_char.read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                         \
                .protocol_mode_char = {                                                            \
                        .read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                 \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                },                                                                                 \
                .ctrl_point_char = {                                                               \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                },                                                                                 \
                .boot_mouse_inp_rep_char = {                                                       \
                        .read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                 \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                        .cccd_write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                           \
                },                                                                                 \
        }
 
#define BLE_HIDS_CONFIG_SEC_MODE_DEFAULT_KEYBOARD                                                  \
        {                                                                                          \
                .hid_info_char.read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                           \
                .report_map_char.read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                         \
                .protocol_mode_char = {                                                            \
                        .read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                 \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                },                                                                                 \
                .ctrl_point_char = {                                                               \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                },                                                                                 \
                .boot_kb_inp_rep_char = {                                                          \
                        .read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                 \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                        .cccd_write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                           \
                },                                                                                 \
                .boot_kb_outp_rep_char = {                                                         \
                        .read = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                 \
                        .write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                                \
                        .cccd_write = BLE_GAP_CONN_SEC_MODE_ENC_NO_MITM,                           \
                },                                                                                 \
        }
 
#define BLE_HIDS_BOOT_KB_INPUT_REPORT_MAX_SIZE    8
#define BLE_HIDS_BOOT_KB_OUTPUT_REPORT_MAX_SIZE   1
#define BLE_HIDS_BOOT_MOUSE_INPUT_REPORT_MAX_SIZE 8
 
enum ble_hids_report_type {
        BLE_HIDS_REPORT_TYPE_RESERVED = 0x00,
        BLE_HIDS_REPORT_TYPE_INPUT = 0x01,
        BLE_HIDS_REPORT_TYPE_OUTPUT = 0x02,
        BLE_HIDS_REPORT_TYPE_FEATURE = 0x03
};
 
struct ble_hids_input_report {
        uint8_t report_index;
        uint8_t *data;
        uint16_t len;
};
 
struct ble_hids_boot_keyboard_input_report {
        uint16_t len;
        uint8_t *data;
};
 
struct ble_hids_boot_mouse_input_report {
        uint8_t buttons;
        int8_t delta_x;
        int8_t delta_y;
        uint16_t optional_data_len;
        uint8_t optional_data[5];
};
 
struct ble_hids_client_context {
        uint8_t protocol_mode;
        uint8_t ctrl_pt;
};
 
#define BLE_HIDS_LINK_CTX_SIZE                                                                     \
        (sizeof(struct ble_hids_client_context) + CONFIG_BLE_HIDS_INPUT_REPORT_MAX_LEN +           \
         CONFIG_BLE_HIDS_OUTPUT_REPORT_MAX_LEN + CONFIG_BLE_HIDS_FEATURE_REPORT_MAX_LEN +          \
         (BLE_HIDS_BOOT_KB_INPUT_REPORT_MAX_SIZE) + (BLE_HIDS_BOOT_KB_OUTPUT_REPORT_MAX_SIZE) +    \
         (BLE_HIDS_BOOT_MOUSE_INPUT_REPORT_MAX_SIZE))
 
#define CTX_DATA_POOL_SIZE ((CONFIG_BLE_HIDS_MAX_CLIENTS) * BYTES_TO_WORDS(BLE_HIDS_LINK_CTX_SIZE))
 
struct ble_hids_link_ctx_storage {
        uint32_t ctx_data_pool[CTX_DATA_POOL_SIZE];
        const uint8_t max_links_cnt;
        const uint16_t link_ctx_size;
};
 
/* Forward declaration of ble_hids structure. */
struct ble_hids;
 
struct ble_hids_char_id {
        uint16_t uuid;
        uint8_t report_type;
        uint8_t report_index;
};
 
enum ble_hids_evt_type {
        BLE_HIDS_EVT_HOST_SUSP,
        BLE_HIDS_EVT_HOST_EXIT_SUSP,
        BLE_HIDS_EVT_NOTIF_ENABLED,
        BLE_HIDS_EVT_NOTIF_DISABLED,
        BLE_HIDS_EVT_REP_CHAR_WRITE,
        BLE_HIDS_EVT_BOOT_MODE_ENTERED,
        BLE_HIDS_EVT_REPORT_MODE_ENTERED,
        BLE_HIDS_EVT_REPORT_READ,
        BLE_HIDS_EVT_ERROR,
};
 
struct ble_hids_evt {
        enum ble_hids_evt_type evt_type;
        uint16_t conn_handle;
        const ble_evt_t *ble_evt;
        union {
                struct {
                        struct ble_hids_char_id char_id;
                } notification;
                struct {
                        struct ble_hids_char_id char_id;
                        uint16_t offset;
                        uint16_t len;
                        const uint8_t *data;
                } char_write;
                struct {
                        struct ble_hids_char_id char_id;
                } char_auth_read;
                struct {
                        uint32_t reason;
                } error;
        };
};
 
typedef void (*ble_hids_evt_handler_t)(struct ble_hids *hids, const struct ble_hids_evt *evt);
 
struct ble_hids_report_config {
        uint16_t len;
        uint8_t report_id;
        uint8_t report_type;
        struct {
                ble_gap_conn_sec_mode_t read;
                ble_gap_conn_sec_mode_t write;
                ble_gap_conn_sec_mode_t cccd_write;
        } sec_mode;
};
 
struct ble_hids_rep_map_config {
        uint8_t *data;
        uint16_t len;
        uint8_t ext_rep_ref_num;
        const ble_uuid_t *ext_rep_ref;
};
 
struct ble_hids_rep_char {
        ble_gatts_char_handles_t char_handles;
        uint16_t ref_handle;
};
 
struct ble_hids_config {
        ble_hids_evt_handler_t evt_handler;
        uint8_t input_report_count;
        const struct ble_hids_report_config *input_report;
        uint8_t output_report_count;
        const struct ble_hids_report_config *output_report;
        uint8_t feature_report_count;
        const struct ble_hids_report_config *feature_report;
        struct ble_hids_rep_map_config report_map;
        struct {
                uint16_t bcd_hid;
                uint8_t b_country_code;
                struct {
                        uint8_t normally_connectable: 1;
                        uint8_t remote_wake: 1;
                        uint8_t reserved: 6;
                } flags;
        } hid_information;
        uint8_t included_services_count;
        uint16_t *included_services_array;
        struct {
                struct {
                        ble_gap_conn_sec_mode_t read;
                } hid_info_char;
                struct {
                        ble_gap_conn_sec_mode_t read;
                        ble_gap_conn_sec_mode_t write;
                } protocol_mode_char;
                struct {
                        ble_gap_conn_sec_mode_t write;
                } ctrl_point_char;
                struct {
                        ble_gap_conn_sec_mode_t read;
                } report_map_char;
                struct {
                        ble_gap_conn_sec_mode_t read;
                        ble_gap_conn_sec_mode_t write;
                        ble_gap_conn_sec_mode_t cccd_write;
                } boot_mouse_inp_rep_char;
                struct {
                        ble_gap_conn_sec_mode_t read;
                        ble_gap_conn_sec_mode_t write;
                        ble_gap_conn_sec_mode_t cccd_write;
                } boot_kb_inp_rep_char;
                struct {
                        ble_gap_conn_sec_mode_t read;
                        ble_gap_conn_sec_mode_t write;
                        ble_gap_conn_sec_mode_t cccd_write;
                } boot_kb_outp_rep_char;
        } sec_mode;
};
 
struct ble_hids {
        ble_hids_evt_handler_t evt_handler;
        uint16_t service_handle;
        ble_gatts_char_handles_t protocol_mode_handles;
        uint8_t input_report_count;
        struct ble_hids_rep_char inp_rep_array[CONFIG_BLE_HIDS_INPUT_REPORT_MAX_NUM];
        uint8_t output_report_count;
        struct ble_hids_rep_char outp_rep_array[CONFIG_BLE_HIDS_OUTPUT_REPORT_MAX_NUM];
        uint8_t feature_report_count;
        struct ble_hids_rep_char feature_rep_array[CONFIG_BLE_HIDS_FEATURE_REPORT_MAX_NUM];
        ble_gatts_char_handles_t rep_map_handles;
        uint16_t rep_map_ext_rep_ref_handle;
        ble_gatts_char_handles_t boot_kb_inp_rep_handles;
        ble_gatts_char_handles_t boot_kb_outp_rep_handles;
        ble_gatts_char_handles_t boot_mouse_inp_rep_handles;
        ble_gatts_char_handles_t hid_information_handles;
        ble_gatts_char_handles_t hid_control_point_handles;
        struct ble_hids_link_ctx_storage link_ctx_storage;
        const struct ble_hids_report_config *inp_rep_init_array;
        const struct ble_hids_report_config *outp_rep_init_array;
        const struct ble_hids_report_config *feature_rep_init_array;
};
 
void ble_hids_on_ble_evt(const ble_evt_t *ble_evt, void *ble_hids);
 
uint32_t ble_hids_init(struct ble_hids *hids, const struct ble_hids_config *hids_cfg);
 
uint32_t ble_hids_inp_rep_send(struct ble_hids *hids, uint16_t conn_handle,
                               struct ble_hids_input_report *report);
 
uint32_t ble_hids_boot_kb_inp_rep_send(struct ble_hids *hids, uint16_t conn_handle,
                                       struct ble_hids_boot_keyboard_input_report *report);
 
uint32_t ble_hids_boot_mouse_inp_rep_send(struct ble_hids *hids, uint16_t conn_handle,
                                          struct ble_hids_boot_mouse_input_report *report);
 
uint32_t ble_hids_outp_rep_get(struct ble_hids *hids, uint8_t report_index, uint16_t len,
                               uint8_t offset, uint16_t conn_handle, uint8_t *outp_rep);
 
#ifdef __cplusplus
}
#endif
 
#endif /* BLE_HIDS_H__ */