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