Line data Source code
1 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_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 1 : #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 1 : #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 1 : #define BT_MICP_MUTE_UNMUTED 0x00 61 : /** The microphone state is muted */ 62 1 : #define BT_MICP_MUTE_MUTED 0x01 63 : /** The microphone state is disabled and cannot be muted or unmuted */ 64 1 : #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 1 : 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 1 : 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 1 : 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 1 : struct bt_micp_included { 90 : /** Number of Audio Input Control Service instances */ 91 1 : uint8_t aics_cnt; 92 : /** Array of pointers to Audio Input Control Service instances */ 93 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
