bluetooth: hids: Add support for HID SCI

This commit adds support for HID Shorter Connection Intervals,
both on the HID Device and HID Host sides.

Signed-off-by: Artur Hadasz <artur.hadasz@nordicsemi.no>

Author: ahasztag

include/bluetooth/services/hids.h

@@ -44,6 +44,26 @@ extern "C" {
 /** Length of encoded HID Information. */
 #define BT_HIDS_INFORMATION_LEN	4
 
+#if defined(CONFIG_BT_HIDS_SCI) || defined(CONFIG_BT_HOGP_SCI)
+/** Maximum number of connection interval groups in HID SCI Information. */
+#if defined(CONFIG_BT_HIDS_SCI_INFORMATION_MAX_GROUPS_COUNT_CUSTOM)
+#define BT_HIDS_SCI_INFORMATION_MAX_GROUPS CONFIG_BT_HIDS_SCI_INFORMATION_MAX_GROUPS_COUNT
+#else
+#define BT_HIDS_SCI_INFORMATION_MAX_GROUPS BT_CONN_LE_MAX_CONN_INTERVAL_GROUPS
+#endif
+
+/** Max length of encoded HID SCI Information based on the HIDS specification:
+ *  Minimum supported conn interval (1B) + Num groups (1B) +
+ *  Num groups * (Group Min (2B) + Group Max (2B) + Group Stride (2B)).
+ */
+#define BT_HIDS_SCI_INFORMATION_MAX_LEN (1 + 1 + BT_HIDS_SCI_INFORMATION_MAX_GROUPS * (2 + 2 + 2))
+#define BT_HIDS_SCI_INFORMATION_MIN_LEN  2
+
+/** The transport interval which the device must support to be compliant
+ *  with the HID specification (chapter 7.4). */
+#define BT_HIDS_MAX_MINIMAL_TRANSPORT_INTERVAL_US 1250
+#endif
+
 /**
  * @brief Declare a HIDS instance.
  *
@@ -116,6 +136,10 @@ enum bt_hids_flags {
 	BT_HIDS_REMOTE_WAKE = BIT(0),
 	/** Device advertises when bonded but not connected. */
 	BT_HIDS_NORMALLY_CONNECTABLE = BIT(1),
+	/** Device is capable of supporting the HID SCI feature */
+	BT_HIDS_SCI_CAPABLE = BIT(2),
+	/** Device is capable of supporting the HID SCI Low Power mode feature */
+	BT_HIDS_SCI_LOW_POWER_MODE_CAPABLE = BIT(3),
 };
 
 /** @brief HID Control Point settings. */
@@ -124,7 +148,32 @@ enum bt_hids_control_point {
 	BT_HIDS_CONTROL_POINT_SUSPEND = 0x00,
 
 	/** Exit suspend value for Control Point.*/
-	BT_HIDS_CONTROL_POINT_EXIT_SUSPEND = 0x01
+	BT_HIDS_CONTROL_POINT_EXIT_SUSPEND = 0x01,
+	/** Request SCI default mode value for Control Point.  */
+	BT_HIDS_CONTROL_POINT_SCI_DEFAULT_REQ = 0x02,
+
+	/** Request SCI fast mode value for Control Point.  */
+	BT_HIDS_CONTROL_POINT_SCI_FAST_REQ = 0x03,
+
+	/** Request SCI low power mode value for Control Point.  */
+	BT_HIDS_CONTROL_POINT_SCI_LOW_POWER_REQ = 0x04,
+
+	/** Request SCI Full Range mode value for Control Point. */
+	BT_HIDS_CONTROL_POINT_SCI_FULL_RANGE_REQ = 0x05,
+};
+
+/** @brief HID SCI Mode values */
+enum bt_hids_sci_mode_value {
+	/** SCI None mode. */
+	BT_HIDS_SCI_MODE_NONE = 0x00,
+	/** SCI Default mode. */
+	BT_HIDS_SCI_MODE_DEFAULT = 0x02,
+	/** SCI Fast mode. */
+	BT_HIDS_SCI_MODE_FAST = 0x03,
+	/** SCI Low Power mode. */
+	BT_HIDS_SCI_MODE_LOW_POWER = 0x04,
+	/** SCI Full Range mode. */
+	BT_HIDS_SCI_MODE_FULL_RANGE = 0x05,
 };
 
 /** HID Service Protocol Mode events. */
@@ -141,6 +190,14 @@ enum bt_hids_cp_evt {
 	BT_HIDS_CP_EVT_HOST_SUSP,
 	/** Exit suspend command received. */
 	BT_HIDS_CP_EVT_HOST_EXIT_SUSP,
+	/** SCI Default mode request received. */
+	BT_HIDS_CP_EVT_HOST_SCI_DEFAULT_REQ,
+	/** SCI Fast mode request received. */
+	BT_HIDS_CP_EVT_HOST_SCI_FAST_REQ,
+	/** SCI Low Power mode request received. */
+	BT_HIDS_CP_EVT_HOST_SCI_LOW_POWER_REQ,
+	/** SCI Full Range mode request received. */
+	BT_HIDS_CP_EVT_HOST_SCI_FULL_RANGE_REQ,
 };
 
 /** HID notification events. */
@@ -393,6 +450,34 @@ struct bt_hids_cp {
 	bt_hids_cp_evt_handler_t evt_handler;
 };
 
+#if defined(CONFIG_BT_HIDS_SCI)
+/** @brief Function to be called when the SCI mode is updated. */
+typedef void (*bt_hids_sci_mode_update_handler_t) (struct bt_conn *conn,
+						   enum bt_hids_sci_mode_value mode);
+
+/** @brief SCI mode.
+ */
+struct bt_hids_sci_mode_data {
+	/** CCC descriptor. */
+	struct bt_gatt_ccc_managed_user_data ccc;
+
+	/** Index in the service attribute array. */
+	uint8_t att_ind;
+
+	/** Callback with new SCI mode. */
+	bt_hids_sci_mode_update_handler_t update_handler;
+};
+
+/** @brief SCI Information data. */
+struct bt_hids_sci_info_data {
+	/** Pointer to the SCI information. */
+	uint8_t sci_info[BT_HIDS_SCI_INFORMATION_MAX_LEN];
+
+	/** Size of the SCI information. */
+	ssize_t sci_info_len;
+};
+#endif
+
 /** @brief HID initialization.
  */
 struct bt_hids_init_param {
@@ -414,7 +499,9 @@ struct bt_hids_init_param {
 	/** Callback for Protocol Mode characteristic. */
 	bt_hids_pm_evt_handler_t pm_evt_handler;
 
-	/** Callback for Control Point characteristic. */
+	/** Callback for Control Point (suspend and exit-suspend only;
+	 *  mode requests are handled internally).
+	 */
 	bt_hids_cp_evt_handler_t cp_evt_handler;
 
 	/** Callback for Boot Mouse Input Report. */
@@ -426,6 +513,11 @@ struct bt_hids_init_param {
 	/** Callback for Boot Keyboard Output Report. */
 	bt_hids_rep_handler_t boot_kb_outp_rep_handler;
 
+#if defined(CONFIG_BT_HIDS_SCI)
+	/** Callback for SCI mode update. */
+	bt_hids_sci_mode_update_handler_t sci_mode_update_handler;
+#endif
+
 	/** Flag indicating that the device has mouse capabilities. */
 	bool is_mouse;
 
@@ -466,6 +558,13 @@ struct bt_hids {
 	/** Control Point. */
 	struct bt_hids_cp cp;
 
+#if defined(CONFIG_BT_HIDS_SCI)
+	/** SCI mode data. */
+	struct bt_hids_sci_mode_data sci_mode_data;
+
+	/** HID SCI Information data. */
+	struct bt_hids_sci_info_data sci_info_data;
+#endif
 	/** Buffer with encoded HID Information. */
 	uint8_t info[BT_HIDS_INFORMATION_LEN];
 
@@ -502,6 +601,14 @@ struct bt_hids_conn_data {
 
 	/** Pointer to Feature Reports Context data. */
 	uint8_t *feat_rep_ctx;
+
+#if defined(CONFIG_BT_HIDS_SCI)
+	/** Pending SCI mode value. */
+	uint8_t pending_sci_mode;
+
+	/** SCI mode value. */
+	uint8_t sci_mode;
+#endif
 };
 
 

include/bluetooth/services/hogp.h

@@ -142,6 +142,57 @@ struct bt_hogp_init_params {
  */
 struct bt_hogp_rep_info;
 
+#if defined(CONFIG_BT_HOGP_SCI)
+/** @brief Callback function that is called when the HID SCI mode is changed.
+ *
+ * @param conn HOGP object.
+ * @param mode New SCI mode value.
+ */
+typedef void (*bt_hogp_sci_mode_changed_cb)(struct bt_conn *conn, const uint8_t mode);
+
+/**
+ * @brief Callback function that is called when a HID SCI mode is read.
+ *
+ * @param hogp HOGP object.
+ * @param err  ATT error code.
+ * @param mode SCI mode value.
+ */
+typedef void (*bt_hogp_sci_mode_read_cb)(struct bt_hogp *hogp, uint8_t err,
+			       enum bt_hids_sci_mode_value mode);
+
+/** @brief SCI mode data.
+ *
+ * This structure is defined here as it is needed in the bt_hogp structure definition.
+ * Do not use any of the fields here directly.
+ */
+struct bt_hogp_sci_mode_data {
+	/** Function to call when the SCI mode is changed. */
+	bt_hogp_sci_mode_changed_cb notify_cb;
+
+	/** Notify params. */
+	struct bt_gatt_subscribe_params notify_params;
+
+	/** Function to call when the SCI mode is read. */
+	bt_hogp_sci_mode_read_cb read_cb;
+
+	/** Read params. */
+	struct bt_gatt_read_params read_params;
+};
+
+/** @brief SCI Information.
+ */
+struct bt_hogp_sci_info {
+	/** Minimum supported connection interval in units of 125us. */
+	uint8_t min_supported_conn_interval_125us;
+
+	/** Number of connection interval groups. */
+	uint8_t num_groups;
+
+	/** Connection interval groups. */
+	struct bt_conn_le_min_conn_interval_group groups[BT_HIDS_SCI_INFORMATION_MAX_GROUPS];
+};
+#endif
+
 /**
  * @brief HOGP object.
  *
@@ -156,6 +207,15 @@ struct bt_hogp {
 	struct bt_conn *conn;
 	/** HIDS client information. */
 	struct bt_hids_info info_val;
+
+#if defined(CONFIG_BT_HOGP_SCI)
+	/** HID SCI Mode data. */
+	struct bt_hogp_sci_mode_data sci_mode_data;
+
+	/** Cached HID SCI Information. */
+	struct bt_hogp_sci_info sci_info;
+#endif
+
 	/** Handlers for descriptors */
 	struct bt_hogp_handlers {
 		/** Protocol Mode Characteristic value handle. */
@@ -166,6 +226,14 @@ struct bt_hogp {
 		uint16_t info;
 		/** HID Control Point Characteristic handle. */
 		uint16_t cp;
+#if defined(CONFIG_BT_HOGP_SCI)
+		/** HID SCI Information Characteristic handle. */
+		uint16_t sci_info;
+		/** HID SCI Mode Characteristic handle. */
+		uint16_t sci_mode;
+		/** HID SCI Mode CCC handle. */
+		uint16_t sci_mode_ccc;
+#endif
 	} handlers;
 	/**
 	 * @brief Callback for HIDS client ready
@@ -192,6 +260,10 @@ struct bt_hogp {
 	 * @sa bt_hogp::read_params_sem
 	 */
 	struct bt_gatt_read_params read_params;
+
+#if defined(CONFIG_BT_HOGP_SCI)
+	struct bt_gatt_read_params sci_info_read_params;
+#endif
 	/**
 	 * @brief The semaphore for common read parameters protection.
 	 *
@@ -524,6 +596,64 @@ int bt_hogp_suspend(struct bt_hogp *hogp);
  */
 int bt_hogp_exit_suspend(struct bt_hogp *hogp);
 
+#if defined(CONFIG_BT_HOGP_SCI)
+/**
+ * @brief Read the current HID SCI mode from the HID device.
+ * @param hogp HOGP object.
+ * @param mode Pointer to the HID SCI mode value to read.
+ *
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a (negative) error code is returned.
+ */
+int bt_hogp_sci_mode_read(struct bt_hogp *hogp, bt_hogp_sci_mode_read_cb func);
+
+/**
+ * @brief Request HID SCI mode activation.
+ *
+ * This function is used to request that the HID device enters a specific
+ * HID SCI mode
+ *
+ * @param hogp HOGP object.
+ * @param mode HID SCI mode to enable
+ *
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a (negative) error code is returned.
+ */
+int bt_hogp_sci_mode_req(struct bt_hogp *hogp, enum bt_hids_sci_mode_value mode);
+
+/**
+ * @brief Subscribe to HID SCI mode changed notifications.
+ * @param hogp HOGP object.
+ * @param func Function to call when the SCI mode is changed.
+ *
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a (negative) error code is returned.
+ */
+int bt_hogp_sci_mode_subscribe(struct bt_hogp *hogp, bt_hogp_sci_mode_changed_cb func);
+
+/**
+ * @brief Unsubscribe from SCI mode changed notifications.
+ * @param hogp HOGP object.
+ *
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a (negative) error code is returned.
+ */
+int bt_hogp_sci_mode_unsubscribe(struct bt_hogp *hogp);
+/**
+ * @brief Get the cached HID SCI Information.
+ *
+ * This function fills the SCI Information structure with the cached SCI Information.
+ * It does not generate any traffic on the radio.
+ *
+ * @param hogp HOGP object.
+ * @param sci_info Pointer to the SCI Information structure to fill.
+ *
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a (negative) error code is returned.
+ */
+int bt_hogp_sci_info_get(struct bt_hogp *hogp, struct bt_hogp_sci_info *sci_info);
+
+#endif
 
 /**
  * @brief Get the connection object from the HIDS client.

subsys/bluetooth/services/Kconfig.hids

@@ -68,6 +68,8 @@ config BT_HIDS_DEFAULT_PERM_RW_AUTHEN
 
 endchoice
 
+rsource "Kconfig.hids.sci"
+
 module = BT_HIDS
 module-str = HIDS
 source "$(ZEPHYR_BASE)/subsys/logging/Kconfig.template.log_config"