1 /** 2 * @file 3 * @brief Bluetooth Microphone Control Profile (MICP) APIs. 4 */ 5 6 /* 7 * Copyright (c) 2020-2024 Nordic Semiconductor ASA 8 * 9 * SPDX-License-Identifier: Apache-2.0 10 */ 11 12 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MICP_H_ 13 #define ZEPHYR_INCLUDE_BLUETOOTH_MICP_H_ 14 15 /** 16 * @brief Microphone Control Profile (MICP) 17 * 18 * @defgroup bt_gatt_micp Microphone Control Profile (MICP) 19 * 20 * @since 2.7 21 * @version 0.8.0 22 * 23 * @ingroup bluetooth 24 * @{ 25 */ 26 27 #include <stdint.h> 28 29 #include <zephyr/bluetooth/audio/aics.h> 30 #include <zephyr/bluetooth/conn.h> 31 #include <zephyr/sys/slist.h> 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /** 38 * Defines the maximum number of Microphone Control Service instances for the 39 * Microphone Control Profile Microphone Device 40 */ 41 #if defined(CONFIG_BT_MICP_MIC_DEV) 42 #define BT_MICP_MIC_DEV_AICS_CNT CONFIG_BT_MICP_MIC_DEV_AICS_INSTANCE_COUNT 43 #else 44 #define BT_MICP_MIC_DEV_AICS_CNT 0 45 #endif /* CONFIG_BT_MICP_MIC_DEV */ 46 47 /** 48 * @name Application error codes 49 * @{ 50 */ 51 /** Mute/unmute commands are disabled. */ 52 #define BT_MICP_ERR_MUTE_DISABLED 0x80 53 /** @} */ 54 55 /** 56 * @name Microphone Control Profile mute states 57 * @{ 58 */ 59 /** The microphone state is unmuted */ 60 #define BT_MICP_MUTE_UNMUTED 0x00 61 /** The microphone state is muted */ 62 #define BT_MICP_MUTE_MUTED 0x01 63 /** The microphone state is disabled and cannot be muted or unmuted */ 64 #define BT_MICP_MUTE_DISABLED 0x02 65 /** @} */ 66 67 /** @brief Opaque Microphone Controller instance. */ 68 struct bt_micp_mic_ctlr; 69 70 /** @brief Register parameters structure for Microphone Control Service */ 71 struct bt_micp_mic_dev_register_param { 72 #if defined(CONFIG_BT_MICP_MIC_DEV_AICS) || defined(__DOXYGEN__) 73 /** Register parameter structure for Audio Input Control Services */ 74 struct bt_aics_register_param aics_param[BT_MICP_MIC_DEV_AICS_CNT]; 75 #endif /* CONFIG_BT_MICP_MIC_DEV_AICS */ 76 77 /** Microphone Control Profile callback structure. */ 78 struct bt_micp_mic_dev_cb *cb; 79 }; 80 81 /** 82 * @brief Microphone Control Profile included services 83 * 84 * Used for to represent the Microphone Control Profile included service 85 * instances, for either a Microphone Controller or a Microphone Device. 86 * The instance pointers either represent local service instances, 87 * or remote service instances. 88 */ 89 struct bt_micp_included { 90 /** Number of Audio Input Control Service instances */ 91 uint8_t aics_cnt; 92 /** Array of pointers to Audio Input Control Service instances */ 93 struct bt_aics **aics; 94 }; 95 96 /** 97 * @brief Initialize the Microphone Control Profile Microphone Device 98 * 99 * This will enable the Microphone Control Service instance and make it 100 * discoverable by Microphone Controllers. 101 * 102 * @param param Pointer to an initialization structure. 103 * 104 * @return 0 if success, errno on failure. 105 */ 106 int bt_micp_mic_dev_register(struct bt_micp_mic_dev_register_param *param); 107 108 /** 109 * @brief Get Microphone Device included services 110 * 111 * Returns a pointer to a struct that contains information about the 112 * Microphone Device included Audio Input Control Service instances. 113 * 114 * Requires that @kconfig{CONFIG_BT_MICP_MIC_DEV_AICS} is enabled. 115 * 116 * @param included Pointer to store the result in. 117 * 118 * @return 0 if success, errno on failure. 119 */ 120 int bt_micp_mic_dev_included_get(struct bt_micp_included *included); 121 122 /** 123 * @brief Struct to hold the Microphone Device callbacks 124 * 125 * These can be registered for usage with bt_micp_mic_dev_register(). 126 */ 127 struct bt_micp_mic_dev_cb { 128 /** 129 * @brief Callback function for Microphone Device mute. 130 * 131 * Called when the value is read with bt_micp_mic_dev_mute_get(), 132 * or if the value is changed by either the Microphone Device or a 133 * Microphone Controller. 134 * 135 * @param mute The mute setting of the Microphone Control Service. 136 */ 137 void (*mute)(uint8_t mute); 138 }; 139 140 /** 141 * @brief Unmute the Microphone Device. 142 * 143 * @return 0 on success, GATT error value on fail. 144 */ 145 int bt_micp_mic_dev_unmute(void); 146 147 /** 148 * @brief Mute the Microphone Device. 149 * 150 * @return 0 on success, GATT error value on fail. 151 */ 152 int bt_micp_mic_dev_mute(void); 153 154 /** 155 * @brief Disable the mute functionality on the Microphone Device. 156 * 157 * Can be reenabled by called @ref bt_micp_mic_dev_mute or @ref bt_micp_mic_dev_unmute. 158 * 159 * @return 0 on success, GATT error value on fail. 160 */ 161 int bt_micp_mic_dev_mute_disable(void); 162 163 /** 164 * @brief Read the mute state on the Microphone Device. 165 * 166 * @return 0 on success, GATT error value on fail. 167 */ 168 int bt_micp_mic_dev_mute_get(void); 169 170 /** 171 * @brief Struct to hold the Microphone Controller callbacks 172 * 173 * These can be registered for usage with bt_micp_mic_ctlr_cb_register(). 174 */ 175 struct bt_micp_mic_ctlr_cb { 176 /** 177 * @brief Callback function for Microphone Control Profile mute. 178 * 179 * Called when the value is read, 180 * or if the value is changed by either the Microphone Device or a 181 * Microphone Controller. 182 * 183 * @param mic_ctlr Microphone Controller instance pointer. 184 * @param err Error value. 0 on success, GATT error or errno on fail. 185 * For notifications, this will always be 0. 186 * @param mute The mute setting of the Microphone Control Service. 187 */ 188 void (*mute)(struct bt_micp_mic_ctlr *mic_ctlr, int err, uint8_t mute); 189 190 /** 191 * @brief Callback function for bt_micp_mic_ctlr_discover(). 192 * 193 * @param mic_ctlr Microphone Controller instance pointer. 194 * @param err Error value. 0 on success, GATT error or errno on fail. 195 * @param aics_count Number of Audio Input Control Service instances on 196 * peer device. 197 */ 198 void (*discover)(struct bt_micp_mic_ctlr *mic_ctlr, int err, 199 uint8_t aics_count); 200 201 /** 202 * @brief Callback function for Microphone Control Profile mute/unmute. 203 * 204 * @param mic_ctlr Microphone Controller instance pointer. 205 * @param err Error value. 0 on success, GATT error or errno on fail. 206 */ 207 void (*mute_written)(struct bt_micp_mic_ctlr *mic_ctlr, int err); 208 209 /** 210 * @brief Callback function for Microphone Control Profile mute/unmute. 211 * 212 * @param mic_ctlr Microphone Controller instance pointer. 213 * @param err Error value. 0 on success, GATT error or errno on fail. 214 */ 215 void (*unmute_written)(struct bt_micp_mic_ctlr *mic_ctlr, int err); 216 217 #if defined(CONFIG_BT_MICP_MIC_CTLR_AICS) 218 /** Audio Input Control Service client callback */ 219 struct bt_aics_cb aics_cb; 220 #endif /* CONFIG_BT_MICP_MIC_CTLR_AICS */ 221 222 /** @internal Internally used field for list handling */ 223 sys_snode_t _node; 224 }; 225 226 /** 227 * @brief Get Microphone Control Profile included services 228 * 229 * Returns a pointer to a struct that contains information about the 230 * Microphone Control Profile included services instances, such as 231 * pointers to the Audio Input Control Service instances. 232 * 233 * Requires that @kconfig{CONFIG_BT_MICP_MIC_CTLR_AICS} is enabled. 234 * 235 * @param mic_ctlr Microphone Controller instance pointer. 236 * @param[out] included Pointer to store the result in. 237 * 238 * @return 0 if success, errno on failure. 239 */ 240 int bt_micp_mic_ctlr_included_get(struct bt_micp_mic_ctlr *mic_ctlr, 241 struct bt_micp_included *included); 242 243 /** 244 * @brief Get the connection pointer of a Microphone Controller instance 245 * 246 * Get the Bluetooth connection pointer of a Microphone Controller instance. 247 * 248 * @param mic_ctlr Microphone Controller instance pointer. 249 * @param conn Connection pointer. 250 * 251 * @return 0 if success, errno on failure. 252 */ 253 int bt_micp_mic_ctlr_conn_get(const struct bt_micp_mic_ctlr *mic_ctlr, 254 struct bt_conn **conn); 255 256 /** 257 * @brief Get the volume controller from a connection pointer 258 * 259 * Get the Volume Control Profile Volume Controller pointer from a connection pointer. 260 * Only volume controllers that have been initiated via bt_micp_mic_ctlr_discover() can be 261 * retrieved. 262 * 263 * @param conn Connection pointer. 264 * 265 * @retval Pointer to a Microphone Control Profile Microphone Controller instance 266 * @retval NULL if @p conn is NULL or if the connection has not done discovery yet 267 */ 268 struct bt_micp_mic_ctlr *bt_micp_mic_ctlr_get_by_conn(const struct bt_conn *conn); 269 270 /** 271 * @brief Discover Microphone Control Service 272 * 273 * This will start a GATT discovery and setup handles and subscriptions. 274 * This shall be called once before any other actions can be executed for the 275 * peer device, and the @ref bt_micp_mic_ctlr_cb.discover callback will notify 276 * when it is possible to start remote operations. 277 * * 278 * @param conn The connection to initialize the profile for. 279 * @param[out] mic_ctlr Valid remote instance object on success. 280 * 281 * @return 0 on success, GATT error value on fail. 282 */ 283 int bt_micp_mic_ctlr_discover(struct bt_conn *conn, 284 struct bt_micp_mic_ctlr **mic_ctlr); 285 286 /** 287 * @brief Unmute a remote Microphone Device. 288 * 289 * @param mic_ctlr Microphone Controller instance pointer. 290 * 291 * @return 0 on success, GATT error value on fail. 292 */ 293 int bt_micp_mic_ctlr_unmute(struct bt_micp_mic_ctlr *mic_ctlr); 294 295 /** 296 * @brief Mute a remote Microphone Device. 297 * 298 * @param mic_ctlr Microphone Controller instance pointer. 299 * 300 * @return 0 on success, GATT error value on fail. 301 */ 302 int bt_micp_mic_ctlr_mute(struct bt_micp_mic_ctlr *mic_ctlr); 303 304 /** 305 * @brief Read the mute state of a remote Microphone Device. 306 * 307 * @param mic_ctlr Microphone Controller instance pointer. 308 * 309 * @return 0 on success, GATT error value on fail. 310 */ 311 int bt_micp_mic_ctlr_mute_get(struct bt_micp_mic_ctlr *mic_ctlr); 312 313 /** 314 * @brief Registers the callbacks used by Microphone Controller. 315 * 316 * This can only be done as the client. 317 * 318 * @param cb The callback structure. 319 * 320 * @return 0 if success, errno on failure. 321 */ 322 int bt_micp_mic_ctlr_cb_register(struct bt_micp_mic_ctlr_cb *cb); 323 #ifdef __cplusplus 324 } 325 #endif 326 327 /** 328 * @} 329 */ 330 331 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MICP_H_ */ 332
