Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
Audio Input Control Service (AICS)

Audio Input Control Service (AICS) More...

Data Structures

struct  bt_aics_register_param
 Structure for initializing a Audio Input Control Service instance. More...
 
struct  bt_aics_discover_param
 Structure for discovering a Audio Input Control Service instance. More...
 
struct  bt_aics_cb
 

Macros

#define BT_AICS_STATE_UNMUTED   0x00
 
#define BT_AICS_STATE_MUTED   0x01
 
#define BT_AICS_STATE_MUTE_DISABLED   0x02
 
#define BT_AICS_MODE_MANUAL_ONLY   0x00
 
#define BT_AICS_MODE_AUTO_ONLY   0x01
 
#define BT_AICS_MODE_MANUAL   0x02
 
#define BT_AICS_MODE_AUTO   0x03
 
#define BT_AICS_INPUT_TYPE_UNSPECIFIED   0x00
 
#define BT_AICS_INPUT_TYPE_BLUETOOTH   0x01
 
#define BT_AICS_INPUT_TYPE_MICROPHONE   0x02
 
#define BT_AICS_INPUT_TYPE_ANALOG   0x03
 
#define BT_AICS_INPUT_TYPE_DIGITAL   0x04
 
#define BT_AICS_INPUT_TYPE_RADIO   0x05
 
#define BT_AICS_INPUT_TYPE_STREAMING   0x06
 
#define BT_AICS_ERR_INVALID_COUNTER   0x80
 
#define BT_AICS_ERR_OP_NOT_SUPPORTED   0x81
 
#define BT_AICS_ERR_MUTE_DISABLED   0x82
 
#define BT_AICS_ERR_OUT_OF_RANGE   0x83
 
#define BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED   0x84
 

Typedefs

typedef void(* bt_aics_write_cb) (struct bt_aics *inst, int err)
 Callback function for writes. More...
 
typedef void(* bt_aics_state_cb) (struct bt_aics *inst, int err, int8_t gain, uint8_t mute, uint8_t mode)
 Callback function for the input state. More...
 
typedef void(* bt_aics_gain_setting_cb) (struct bt_aics *inst, int err, uint8_t units, int8_t minimum, int8_t maximum)
 Callback function for the gain settings. More...
 
typedef void(* bt_aics_type_cb) (struct bt_aics *inst, int err, uint8_t type)
 Callback function for the input type. More...
 
typedef void(* bt_aics_status_cb) (struct bt_aics *inst, int err, bool active)
 Callback function for the input status. More...
 
typedef void(* bt_aics_description_cb) (struct bt_aics *inst, int err, char *description)
 Callback function for the description. More...
 
typedef void(* bt_aics_discover_cb) (struct bt_aics *inst, int err)
 Callback function for bt_aics_discover. More...
 

Functions

struct bt_aics * bt_aics_free_instance_get (void)
 Get a free instance of Audio Input Control Service from the pool. More...
 
voidbt_aics_svc_decl_get (struct bt_aics *aics)
 Get the service declaration attribute. More...
 
int bt_aics_client_conn_get (const struct bt_aics *aics, struct bt_conn **conn)
 Get the connection pointer of a client instance. More...
 
int bt_aics_register (struct bt_aics *aics, struct bt_aics_register_param *param)
 Initialize the Audio Input Control Service instance. More...
 
int bt_aics_discover (struct bt_conn *conn, struct bt_aics *inst, const struct bt_aics_discover_param *param)
 Discover a Audio Input Control Service. More...
 
int bt_aics_deactivate (struct bt_aics *inst)
 Deactivates a Audio Input Control Service instance. More...
 
int bt_aics_activate (struct bt_aics *inst)
 Activates a Audio Input Control Service instance. More...
 
int bt_aics_state_get (struct bt_aics *inst)
 Read the Audio Input Control Service input state. More...
 
int bt_aics_gain_setting_get (struct bt_aics *inst)
 Read the Audio Input Control Service gain settings. More...
 
int bt_aics_type_get (struct bt_aics *inst)
 Read the Audio Input Control Service input type. More...
 
int bt_aics_status_get (struct bt_aics *inst)
 Read the Audio Input Control Service input status. More...
 
int bt_aics_unmute (struct bt_aics *inst)
 Unmute the Audio Input Control Service input. More...
 
int bt_aics_mute (struct bt_aics *inst)
 Mute the Audio Input Control Service input. More...
 
int bt_aics_manual_gain_set (struct bt_aics *inst)
 Set input gain to manual. More...
 
int bt_aics_automatic_gain_set (struct bt_aics *inst)
 Set the input gain to automatic. More...
 
int bt_aics_gain_set (struct bt_aics *inst, int8_t gain)
 Set the input gain. More...
 
int bt_aics_description_get (struct bt_aics *inst)
 Read the Audio Input Control Service description. More...
 
int bt_aics_description_set (struct bt_aics *inst, const char *description)
 Set the Audio Input Control Service description. More...
 
struct bt_aics * bt_aics_client_free_instance_get (void)
 Get a new Audio Input Control Service client instance. More...
 
void bt_aics_client_cb_register (struct bt_aics *inst, struct bt_aics_cb *cb)
 Registers the callbacks for the Audio Input Control Service client. More...
 

Detailed Description

Audio Input Control Service (AICS)

The Audio Input Control Service is a secondary service, and as such should not be used on its own, but rather in the context of another (primary) service.

This API implements both the server and client functionality. Note that the API abstracts away the change counter in the audio input control state and will automatically handle any changes to that. If out of date, the client implementation will autonomously read the change counter value when executing a write request.

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Macro Definition Documentation

◆ BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED

#define BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED   0x84

◆ BT_AICS_ERR_INVALID_COUNTER

#define BT_AICS_ERR_INVALID_COUNTER   0x80

#include <include/bluetooth/audio/aics.h>

Audio Input Control Service Error codes

◆ BT_AICS_ERR_MUTE_DISABLED

#define BT_AICS_ERR_MUTE_DISABLED   0x82

◆ BT_AICS_ERR_OP_NOT_SUPPORTED

#define BT_AICS_ERR_OP_NOT_SUPPORTED   0x81

◆ BT_AICS_ERR_OUT_OF_RANGE

#define BT_AICS_ERR_OUT_OF_RANGE   0x83

◆ BT_AICS_INPUT_TYPE_ANALOG

#define BT_AICS_INPUT_TYPE_ANALOG   0x03

◆ BT_AICS_INPUT_TYPE_BLUETOOTH

#define BT_AICS_INPUT_TYPE_BLUETOOTH   0x01

◆ BT_AICS_INPUT_TYPE_DIGITAL

#define BT_AICS_INPUT_TYPE_DIGITAL   0x04

◆ BT_AICS_INPUT_TYPE_MICROPHONE

#define BT_AICS_INPUT_TYPE_MICROPHONE   0x02

◆ BT_AICS_INPUT_TYPE_RADIO

#define BT_AICS_INPUT_TYPE_RADIO   0x05

◆ BT_AICS_INPUT_TYPE_STREAMING

#define BT_AICS_INPUT_TYPE_STREAMING   0x06

◆ BT_AICS_INPUT_TYPE_UNSPECIFIED

#define BT_AICS_INPUT_TYPE_UNSPECIFIED   0x00

#include <include/bluetooth/audio/aics.h>

Audio Input Control Service input types

◆ BT_AICS_MODE_AUTO

#define BT_AICS_MODE_AUTO   0x03

◆ BT_AICS_MODE_AUTO_ONLY

#define BT_AICS_MODE_AUTO_ONLY   0x01

◆ BT_AICS_MODE_MANUAL

#define BT_AICS_MODE_MANUAL   0x02

◆ BT_AICS_MODE_MANUAL_ONLY

#define BT_AICS_MODE_MANUAL_ONLY   0x00

#include <include/bluetooth/audio/aics.h>

Audio Input Control Service input modes

◆ BT_AICS_STATE_MUTE_DISABLED

#define BT_AICS_STATE_MUTE_DISABLED   0x02

◆ BT_AICS_STATE_MUTED

#define BT_AICS_STATE_MUTED   0x01

◆ BT_AICS_STATE_UNMUTED

#define BT_AICS_STATE_UNMUTED   0x00

#include <include/bluetooth/audio/aics.h>

Audio Input Control Service mute states

Typedef Documentation

◆ bt_aics_description_cb

typedef void(* bt_aics_description_cb) (struct bt_aics *inst, int err, char *description)

#include <include/bluetooth/audio/aics.h>

Callback function for the description.

Called when the value is read, or if the value is changed by either the server or client.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
descriptionThe description as an UTF-8 encoded string (may have been clipped).

◆ bt_aics_discover_cb

typedef void(* bt_aics_discover_cb) (struct bt_aics *inst, int err)

#include <include/bluetooth/audio/aics.h>

Callback function for bt_aics_discover.

This callback will usually be overwritten by the primary service that includes the Audio Input Control Service client.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.

◆ bt_aics_gain_setting_cb

typedef void(* bt_aics_gain_setting_cb) (struct bt_aics *inst, int err, uint8_t units, int8_t minimum, int8_t maximum)

#include <include/bluetooth/audio/aics.h>

Callback function for the gain settings.

Called when the value is read, or if the value is changed by either the server or client.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
unitsThe value that reflect the size of a single increment or decrement of the Gain Setting value in 0.1 decibel units.
minimumThe minimum gain allowed for the gain setting.
maximumThe maximum gain allowed for the gain setting.

◆ bt_aics_state_cb

typedef void(* bt_aics_state_cb) (struct bt_aics *inst, int err, int8_t gain, uint8_t mute, uint8_t mode)

#include <include/bluetooth/audio/aics.h>

Callback function for the input state.

Called when the value is read, or if the value is changed by either the server or client.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
gainThe gain setting value.
muteThe mute value.
modeThe mode value.

◆ bt_aics_status_cb

typedef void(* bt_aics_status_cb) (struct bt_aics *inst, int err, bool active)

#include <include/bluetooth/audio/aics.h>

Callback function for the input status.

Called when the value is read, or if the value is changed by either the server or client.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
activeWhether the instance is active or inactive.

◆ bt_aics_type_cb

typedef void(* bt_aics_type_cb) (struct bt_aics *inst, int err, uint8_t type)

#include <include/bluetooth/audio/aics.h>

Callback function for the input type.

Called when the value is read, or if the value is changed by either the server or client.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
typeThe input type.

◆ bt_aics_write_cb

typedef void(* bt_aics_write_cb) (struct bt_aics *inst, int err)

#include <include/bluetooth/audio/aics.h>

Callback function for writes.

Parameters
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value.

Function Documentation

◆ bt_aics_activate()

int bt_aics_activate ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Activates a Audio Input Control Service instance.

Audio Input Control Services are activated by default, but this will allow the server reactivate a Audio Input Control Service instance after it has been deactivated with bt_aics_deactivate.

Parameters
instThe instance pointer.
Returns
0 if success, errno on failure.

◆ bt_aics_automatic_gain_set()

int bt_aics_automatic_gain_set ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Set the input gain to automatic.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_client_cb_register()

void bt_aics_client_cb_register ( struct bt_aics *  inst,
struct bt_aics_cb cb 
)

#include <include/bluetooth/audio/aics.h>

Registers the callbacks for the Audio Input Control Service client.

Parameters
instThe instance pointer.
cbPointer to the callback structure.

◆ bt_aics_client_conn_get()

int bt_aics_client_conn_get ( const struct bt_aics *  aics,
struct bt_conn **  conn 
)

#include <include/bluetooth/audio/aics.h>

Get the connection pointer of a client instance.

Get the Bluetooth connection pointer of a Audio Input Control Service client instance.

Parameters
aicsAudio Input Control Service client instance pointer.
connConnection pointer.
Returns
0 if success, errno on failure.

◆ bt_aics_client_free_instance_get()

struct bt_aics * bt_aics_client_free_instance_get ( void  )

#include <include/bluetooth/audio/aics.h>

Get a new Audio Input Control Service client instance.

Returns
Pointer to the instance, or NULL if no free instances are left.

◆ bt_aics_deactivate()

int bt_aics_deactivate ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Deactivates a Audio Input Control Service instance.

Audio Input Control Services are activated by default, but this will allow the server to deactivate an Audio Input Control Service.

Parameters
instThe instance pointer.
Returns
0 if success, errno on failure.

◆ bt_aics_description_get()

int bt_aics_description_get ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Read the Audio Input Control Service description.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_description_set()

int bt_aics_description_set ( struct bt_aics *  inst,
const char *  description 
)

#include <include/bluetooth/audio/aics.h>

Set the Audio Input Control Service description.

Parameters
instThe instance pointer.
descriptionThe description as an UTF-8 encoded string.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_discover()

int bt_aics_discover ( struct bt_conn *  conn,
struct bt_aics *  inst,
const struct bt_aics_discover_param param 
)

#include <include/bluetooth/audio/aics.h>

Discover a Audio Input Control Service.

Attempts to discover a Audio Input Control Service on a server given the param.

Parameters
connConnection to the peer with the Audio Input Control Service.
instThe instance pointer.
paramPointer to the parameters.
Returns
0 on success, errno on fail.

◆ bt_aics_free_instance_get()

struct bt_aics * bt_aics_free_instance_get ( void  )

#include <include/bluetooth/audio/aics.h>

Get a free instance of Audio Input Control Service from the pool.

Returns
Audio Input Control Service instance in case of success or NULL in case of error.

◆ bt_aics_gain_set()

int bt_aics_gain_set ( struct bt_aics *  inst,
int8_t  gain 
)

#include <include/bluetooth/audio/aics.h>

Set the input gain.

Parameters
instThe instance pointer.
gainThe gain to set (-128 to 127) in gain setting units (see bt_aics_gain_setting_cb).
Returns
0 on success, GATT error value on fail.

◆ bt_aics_gain_setting_get()

int bt_aics_gain_setting_get ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Read the Audio Input Control Service gain settings.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_manual_gain_set()

int bt_aics_manual_gain_set ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Set input gain to manual.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_mute()

int bt_aics_mute ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Mute the Audio Input Control Service input.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_register()

int bt_aics_register ( struct bt_aics *  aics,
struct bt_aics_register_param param 
)

#include <include/bluetooth/audio/aics.h>

Initialize the Audio Input Control Service instance.

Parameters
aicsAudio Input Control Service instance.
paramAudio Input Control Service register parameters.
Returns
0 if success, errno on failure.

◆ bt_aics_state_get()

int bt_aics_state_get ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Read the Audio Input Control Service input state.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_status_get()

int bt_aics_status_get ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Read the Audio Input Control Service input status.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_svc_decl_get()

void * bt_aics_svc_decl_get ( struct bt_aics *  aics)

#include <include/bluetooth/audio/aics.h>

Get the service declaration attribute.

The first service attribute returned can be included in any other GATT service.

Parameters
aicsAudio Input Control Service instance.
Returns
Pointer to the attributes of the service.

◆ bt_aics_type_get()

int bt_aics_type_get ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Read the Audio Input Control Service input type.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.

◆ bt_aics_unmute()

int bt_aics_unmute ( struct bt_aics *  inst)

#include <include/bluetooth/audio/aics.h>

Unmute the Audio Input Control Service input.

Parameters
instThe instance pointer.
Returns
0 on success, GATT error value on fail.