1 /* 2 * Copyright (c) 2020 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_AICS_H_ 8 #define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_AICS_H_ 9 10 /** 11 * @brief Audio Input Control Service (AICS) 12 * 13 * @defgroup bt_gatt_aics Audio Input Control Service (AICS) 14 * 15 * @ingroup bluetooth 16 * @{ 17 * 18 * The Audio Input Control Service is a secondary service, and as such should not be used on its 19 * own, but rather in the context of another (primary) service. 20 * 21 * This API implements both the server and client functionality. 22 * Note that the API abstracts away the change counter in the audio input control state and will 23 * automatically handle any changes to that. If out of date, the client implementation will 24 * autonomously read the change counter value when executing a write request. 25 * 26 * [Experimental] Users should note that the APIs can change as a part of ongoing development. 27 */ 28 29 #include <zephyr/bluetooth/bluetooth.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** Audio Input Control Service mute states */ 36 #define BT_AICS_STATE_UNMUTED 0x00 37 #define BT_AICS_STATE_MUTED 0x01 38 #define BT_AICS_STATE_MUTE_DISABLED 0x02 39 40 /** Audio Input Control Service input modes */ 41 #define BT_AICS_MODE_MANUAL_ONLY 0x00 42 #define BT_AICS_MODE_AUTO_ONLY 0x01 43 #define BT_AICS_MODE_MANUAL 0x02 44 #define BT_AICS_MODE_AUTO 0x03 45 46 /** Audio Input Control Service input types */ 47 #define BT_AICS_INPUT_TYPE_UNSPECIFIED 0x00 48 #define BT_AICS_INPUT_TYPE_BLUETOOTH 0x01 49 #define BT_AICS_INPUT_TYPE_MICROPHONE 0x02 50 #define BT_AICS_INPUT_TYPE_ANALOG 0x03 51 #define BT_AICS_INPUT_TYPE_DIGITAL 0x04 52 #define BT_AICS_INPUT_TYPE_RADIO 0x05 53 #define BT_AICS_INPUT_TYPE_STREAMING 0x06 54 55 /** Audio Input Control Service Error codes */ 56 #define BT_AICS_ERR_INVALID_COUNTER 0x80 57 #define BT_AICS_ERR_OP_NOT_SUPPORTED 0x81 58 #define BT_AICS_ERR_MUTE_DISABLED 0x82 59 #define BT_AICS_ERR_OUT_OF_RANGE 0x83 60 #define BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED 0x84 61 62 /** @brief Opaque Audio Input Control Service instance. */ 63 struct bt_aics; 64 65 /** @brief Structure for initializing a Audio Input Control Service instance. */ 66 struct bt_aics_register_param { 67 /** Initial audio input gain (-128 to 127) */ 68 int8_t gain; 69 70 /** Initial audio input mute state */ 71 uint8_t mute; 72 73 /** Initial audio input mode */ 74 uint8_t gain_mode; 75 76 /** Initial audio input gain units (N * 0.1 dB) */ 77 uint8_t units; 78 79 /** Initial audio input minimum gain */ 80 int8_t min_gain; 81 82 /** Initial audio input maximum gain */ 83 int8_t max_gain; 84 85 /** Initial audio input type */ 86 uint8_t type; 87 88 /** Initial audio input status (active/inactive) */ 89 bool status; 90 91 /** Boolean to set whether the description is writable by clients */ 92 bool desc_writable; 93 94 /** Initial audio input description */ 95 char *description; 96 97 /** Pointer to the callback structure. */ 98 struct bt_aics_cb *cb; 99 }; 100 101 /** @brief Structure for discovering a Audio Input Control Service instance. */ 102 struct bt_aics_discover_param { 103 /** @brief The start handle of the discovering. 104 * 105 * Typically the @p start_handle of a @ref bt_gatt_include. 106 */ 107 uint16_t start_handle; 108 /** @brief The end handle of the discovering. 109 * 110 * Typically the @p end_handle of a @ref bt_gatt_include. 111 */ 112 uint16_t end_handle; 113 }; 114 115 /** 116 * @brief Get a free instance of Audio Input Control Service from the pool. 117 * 118 * @return Audio Input Control Service instance in case of success or NULL in case of error. 119 */ 120 struct bt_aics *bt_aics_free_instance_get(void); 121 122 /** 123 * @brief Get the service declaration attribute. 124 * 125 * The first service attribute returned can be included in any other GATT service. 126 * 127 * @param aics Audio Input Control Service instance. 128 * 129 * @return Pointer to the attributes of the service. 130 */ 131 void *bt_aics_svc_decl_get(struct bt_aics *aics); 132 133 /** 134 * @brief Get the connection pointer of a client instance 135 * 136 * Get the Bluetooth connection pointer of a Audio Input Control Service 137 * client instance. 138 * 139 * @param aics Audio Input Control Service client instance pointer. 140 * @param conn Connection pointer. 141 * 142 * @return 0 if success, errno on failure. 143 */ 144 int bt_aics_client_conn_get(const struct bt_aics *aics, struct bt_conn **conn); 145 146 /** 147 * @brief Initialize the Audio Input Control Service instance. 148 * 149 * @param aics Audio Input Control Service instance. 150 * @param param Audio Input Control Service register parameters. 151 * 152 * @return 0 if success, errno on failure. 153 */ 154 int bt_aics_register(struct bt_aics *aics, struct bt_aics_register_param *param); 155 156 /** 157 * @brief Callback function for writes. 158 * 159 * @param inst The instance pointer. 160 * @param err Error value. 0 on success, GATT error on positive value 161 * or errno on negative value. 162 */ 163 typedef void (*bt_aics_write_cb)(struct bt_aics *inst, int err); 164 165 /** 166 * @brief Callback function for the input state. 167 * 168 * Called when the value is read, 169 * or if the value is changed by either the server or client. 170 * 171 * @param inst The instance pointer. 172 * @param err Error value. 0 on success, GATT error on positive value 173 * or errno on negative value. 174 * For notifications, this will always be 0. 175 * @param gain The gain setting value. 176 * @param mute The mute value. 177 * @param mode The mode value. 178 */ 179 typedef void (*bt_aics_state_cb)(struct bt_aics *inst, int err, int8_t gain, 180 uint8_t mute, uint8_t mode); 181 182 /** 183 * @brief Callback function for the gain settings. 184 * 185 * Called when the value is read, 186 * or if the value is changed by either the server or client. 187 * 188 * @param inst The instance pointer. 189 * @param err Error value. 0 on success, GATT error on positive value 190 * or errno on negative value. 191 * For notifications, this will always be 0. 192 * @param units The value that reflect the size of a single increment or decrement of the 193 * Gain Setting value in 0.1 decibel units. 194 * @param minimum The minimum gain allowed for the gain setting. 195 * @param maximum The maximum gain allowed for the gain setting. 196 */ 197 typedef void (*bt_aics_gain_setting_cb)(struct bt_aics *inst, int err, 198 uint8_t units, int8_t minimum, 199 int8_t maximum); 200 201 /** 202 * @brief Callback function for the input type. 203 * 204 * Called when the value is read, or if the value is changed by either the server or client. 205 * 206 * @param inst The instance pointer. 207 * @param err Error value. 0 on success, GATT error on positive value 208 * or errno on negative value. 209 * For notifications, this will always be 0. 210 * @param type The input type. 211 */ 212 typedef void (*bt_aics_type_cb)(struct bt_aics *inst, int err, uint8_t type); 213 214 /** 215 * @brief Callback function for the input status. 216 * 217 * Called when the value is read, or if the value is changed by either the server or client. 218 * 219 * @param inst The instance pointer. 220 * @param err Error value. 0 on success, GATT error on positive value 221 * or errno on negative value. 222 * For notifications, this will always be 0. 223 * @param active Whether the instance is active or inactive. 224 */ 225 typedef void (*bt_aics_status_cb)(struct bt_aics *inst, int err, bool active); 226 227 /** 228 * @brief Callback function for the description. 229 * 230 * Called when the value is read, or if the value is changed by either the server or client. 231 * 232 * @param inst The instance pointer. 233 * @param err Error value. 0 on success, GATT error on positive value 234 * or errno on negative value. 235 * For notifications, this will always be 0. 236 * @param description The description as an UTF-8 encoded string (may have been clipped). 237 */ 238 typedef void (*bt_aics_description_cb)(struct bt_aics *inst, int err, 239 char *description); 240 241 /** 242 * @brief Callback function for bt_aics_discover. 243 * 244 * This callback will usually be overwritten by the primary service that 245 * includes the Audio Input Control Service client. 246 * 247 * @param inst The instance pointer. 248 * @param err Error value. 0 on success, GATT error on positive value 249 * or errno on negative value. 250 * For notifications, this will always be 0. 251 */ 252 typedef void (*bt_aics_discover_cb)(struct bt_aics *inst, int err); 253 254 struct bt_aics_cb { 255 bt_aics_state_cb state; 256 bt_aics_gain_setting_cb gain_setting; 257 bt_aics_type_cb type; 258 bt_aics_status_cb status; 259 bt_aics_description_cb description; 260 261 #if defined(CONFIG_BT_AICS_CLIENT) 262 bt_aics_discover_cb discover; 263 bt_aics_write_cb set_gain; 264 bt_aics_write_cb unmute; 265 bt_aics_write_cb mute; 266 bt_aics_write_cb set_manual_mode; 267 bt_aics_write_cb set_auto_mode; 268 #endif /* CONFIG_BT_AICS_CLIENT */ 269 }; 270 271 272 /** 273 * @brief Discover a Audio Input Control Service. 274 * 275 * Attempts to discover a Audio Input Control Service on a server given the 276 * @p param. 277 * 278 * @param conn Connection to the peer with the Audio Input Control Service. 279 * @param inst The instance pointer. 280 * @param param Pointer to the parameters. 281 * 282 * @return 0 on success, errno on fail. 283 */ 284 int bt_aics_discover(struct bt_conn *conn, struct bt_aics *inst, 285 const struct bt_aics_discover_param *param); 286 287 /** 288 * @brief Deactivates a Audio Input Control Service instance. 289 * 290 * Audio Input Control Services are activated by default, but this will allow 291 * the server to deactivate an Audio Input Control Service. 292 * 293 * @param inst The instance pointer. 294 * 295 * @return 0 if success, errno on failure. 296 */ 297 int bt_aics_deactivate(struct bt_aics *inst); 298 299 /** 300 * @brief Activates a Audio Input Control Service instance. 301 * 302 * Audio Input Control Services are activated by default, but this will allow 303 * the server reactivate a Audio Input Control Service instance after it has 304 * been deactivated with @ref bt_aics_deactivate. 305 * 306 * @param inst The instance pointer. 307 * 308 * @return 0 if success, errno on failure. 309 */ 310 int bt_aics_activate(struct bt_aics *inst); 311 312 /** 313 * @brief Read the Audio Input Control Service input state. 314 * 315 * @param inst The instance pointer. 316 * 317 * @return 0 on success, GATT error value on fail. 318 */ 319 int bt_aics_state_get(struct bt_aics *inst); 320 321 /** 322 * @brief Read the Audio Input Control Service gain settings. 323 * 324 * @param inst The instance pointer. 325 * 326 * @return 0 on success, GATT error value on fail. 327 */ 328 int bt_aics_gain_setting_get(struct bt_aics *inst); 329 330 /** 331 * @brief Read the Audio Input Control Service input type. 332 * 333 * @param inst The instance pointer. 334 * 335 * @return 0 on success, GATT error value on fail. 336 */ 337 int bt_aics_type_get(struct bt_aics *inst); 338 339 /** 340 * @brief Read the Audio Input Control Service input status. 341 * 342 * @param inst The instance pointer. 343 * 344 * @return 0 on success, GATT error value on fail. 345 */ 346 int bt_aics_status_get(struct bt_aics *inst); 347 348 /** 349 * @brief Disable mute in the Audio Input Control Service. 350 * 351 * Calling bt_aics_unmute() or bt_aics_mute() will enable 352 * mute again and set the mute state to either unmuted or muted. 353 * 354 * @param inst The instance pointer. 355 * 356 * @return 0 on success, errno value on fail. 357 */ 358 int bt_aics_disable_mute(struct bt_aics *inst); 359 360 /** 361 * @brief Unmute the Audio Input Control Service input. 362 * 363 * @param inst The instance pointer. 364 * 365 * @return 0 on success, GATT error value on fail. 366 */ 367 int bt_aics_unmute(struct bt_aics *inst); 368 369 /** 370 * @brief Mute the Audio Input Control Service input. 371 * 372 * @param inst The instance pointer. 373 * 374 * @return 0 on success, GATT error value on fail. 375 */ 376 int bt_aics_mute(struct bt_aics *inst); 377 378 /** 379 * @brief Set manual only gain mode in Audio Input Control Service. 380 * 381 * @param inst The instance pointer. 382 * 383 * @return 0 on success, errno value on fail. 384 */ 385 int bt_aics_gain_set_manual_only(struct bt_aics *inst); 386 387 /** 388 * @brief Set automatic only gain mode in Audio Input Control Service. 389 * 390 * Using this function and enabling automatic only gain disables 391 * setting the gain with bt_aics_gain_set 392 * 393 * @param inst The instance pointer. 394 * 395 * @return 0 on success, errno value on fail. 396 */ 397 int bt_aics_gain_set_auto_only(struct bt_aics *inst); 398 399 /** 400 * @brief Set input gain to manual. 401 * 402 * @param inst The instance pointer. 403 * 404 * @return 0 on success, GATT error value on fail. 405 */ 406 int bt_aics_manual_gain_set(struct bt_aics *inst); 407 408 /** 409 * @brief Set the input gain to automatic. 410 * 411 * @param inst The instance pointer. 412 * 413 * @return 0 on success, GATT error value on fail. 414 */ 415 int bt_aics_automatic_gain_set(struct bt_aics *inst); 416 417 /** 418 * @brief Set the input gain. 419 * 420 * @param inst The instance pointer. 421 * @param gain The gain to set (-128 to 127) in gain setting units 422 * (see @ref bt_aics_gain_setting_cb). 423 * 424 * @return 0 on success, GATT error value on fail. 425 */ 426 int bt_aics_gain_set(struct bt_aics *inst, int8_t gain); 427 428 /** 429 * @brief Read the Audio Input Control Service description. 430 * 431 * @param inst The instance pointer. 432 * 433 * @return 0 on success, GATT error value on fail. 434 */ 435 int bt_aics_description_get(struct bt_aics *inst); 436 437 /** 438 * @brief Set the Audio Input Control Service description. 439 * 440 * @param inst The instance pointer. 441 * @param description The description as an UTF-8 encoded string. 442 * 443 * @return 0 on success, GATT error value on fail. 444 */ 445 int bt_aics_description_set(struct bt_aics *inst, const char *description); 446 447 /** 448 * @brief Get a new Audio Input Control Service client instance. 449 * 450 * @return Pointer to the instance, or NULL if no free instances are left. 451 */ 452 struct bt_aics *bt_aics_client_free_instance_get(void); 453 454 /** 455 * @brief Registers the callbacks for the Audio Input Control Service client. 456 * 457 * @param inst The instance pointer. 458 * @param cb Pointer to the callback structure. 459 */ 460 void bt_aics_client_cb_register(struct bt_aics *inst, struct bt_aics_cb *cb); 461 462 #ifdef __cplusplus 463 } 464 #endif 465 466 /** 467 * @} 468 */ 469 470 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_AICS_H_ */ 471
