Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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
 Struct to hold callbacks for the Audio Input Control Service. More...
 

Typedefs

typedef void(* bt_aics_write_cb) (struct bt_aics *inst, int err)
 Callback function for writes.
 
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.
 
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.
 
typedef void(* bt_aics_type_cb) (struct bt_aics *inst, int err, uint8_t type)
 Callback function for the input type.
 
typedef void(* bt_aics_status_cb) (struct bt_aics *inst, int err, bool active)
 Callback function for the input status.
 
typedef void(* bt_aics_description_cb) (struct bt_aics *inst, int err, char *description)
 Callback function for the description.
 
typedef void(* bt_aics_discover_cb) (struct bt_aics *inst, int err)
 Callback function for bt_aics_discover.
 

Functions

struct bt_aics * bt_aics_free_instance_get (void)
 Get a free instance of Audio Input Control Service from the pool.
 
void * bt_aics_svc_decl_get (struct bt_aics *aics)
 Get the service declaration attribute.
 
int bt_aics_client_conn_get (const struct bt_aics *aics, struct bt_conn **conn)
 Get the connection pointer of a client instance.
 
int bt_aics_register (struct bt_aics *aics, struct bt_aics_register_param *param)
 Initialize the Audio Input Control Service instance.
 
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.
 
int bt_aics_deactivate (struct bt_aics *inst)
 Deactivates a Audio Input Control Service instance.
 
int bt_aics_activate (struct bt_aics *inst)
 Activates a Audio Input Control Service instance.
 
int bt_aics_state_get (struct bt_aics *inst)
 Read the Audio Input Control Service input state.
 
int bt_aics_gain_setting_get (struct bt_aics *inst)
 Read the Audio Input Control Service gain settings.
 
int bt_aics_type_get (struct bt_aics *inst)
 Read the Audio Input Control Service input type.
 
int bt_aics_status_get (struct bt_aics *inst)
 Read the Audio Input Control Service input status.
 
int bt_aics_disable_mute (struct bt_aics *inst)
 Disable mute in the Audio Input Control Service.
 
int bt_aics_unmute (struct bt_aics *inst)
 Unmute the Audio Input Control Service input.
 
int bt_aics_mute (struct bt_aics *inst)
 Mute the Audio Input Control Service input.
 
int bt_aics_gain_set_manual_only (struct bt_aics *inst)
 Set manual only gain mode in Audio Input Control Service.
 
int bt_aics_gain_set_auto_only (struct bt_aics *inst)
 Set automatic only gain mode in Audio Input Control Service.
 
int bt_aics_manual_gain_set (struct bt_aics *inst)
 Set input gain to manual.
 
int bt_aics_automatic_gain_set (struct bt_aics *inst)
 Set the input gain to automatic.
 
int bt_aics_gain_set (struct bt_aics *inst, int8_t gain)
 Set the input gain.
 
int bt_aics_description_get (struct bt_aics *inst)
 Read the Audio Input Control Service description.
 
int bt_aics_description_set (struct bt_aics *inst, const char *description)
 Set the Audio Input Control Service description.
 
struct bt_aics * bt_aics_client_free_instance_get (void)
 Get a new Audio Input Control Service client instance.
 
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.
 

Audio Input Control Service mute states

#define BT_AICS_STATE_UNMUTED   0x00
 The mute state is unmuted.
 
#define BT_AICS_STATE_MUTED   0x01
 The mute state is muted.
 
#define BT_AICS_STATE_MUTE_DISABLED   0x02
 The mute state is disabled.
 

Audio Input Control Service input modes

#define BT_AICS_MODE_MANUAL_ONLY   0x00
 The gain mode is manual only and cannot be changed to automatic.
 
#define BT_AICS_MODE_AUTO_ONLY   0x01
 The gain mode is automatic only and cannot be changed to manual.
 
#define BT_AICS_MODE_MANUAL   0x02
 The gain mode is manual.
 
#define BT_AICS_MODE_AUTO   0x03
 The gain mode is automatic.
 

Audio Input Control Service input types

#define BT_AICS_INPUT_TYPE_UNSPECIFIED   0x00
 The input is unspecified.
 
#define BT_AICS_INPUT_TYPE_BLUETOOTH   0x01
 The input is a Bluetooth Audio Stream.
 
#define BT_AICS_INPUT_TYPE_MICROPHONE   0x02
 The input is a microphone.
 
#define BT_AICS_INPUT_TYPE_ANALOG   0x03
 The input is analog.
 
#define BT_AICS_INPUT_TYPE_DIGITAL   0x04
 The input is digital.
 
#define BT_AICS_INPUT_TYPE_RADIO   0x05
 The input is a radio (AM/FM/XM/etc.)
 
#define BT_AICS_INPUT_TYPE_STREAMING   0x06
 The input is a Streaming Audio Source.
 
#define BT_AICS_INPUT_TYPE_AMBIENT   0x07
 The input is transparent / pass-through.
 

Audio Input Control Service Error codes

#define BT_AICS_ERR_INVALID_COUNTER   0x80
 The Change_Counter operand value does not match the Change_Counter field value of the Audio Input State characteristic.
 
#define BT_AICS_ERR_OP_NOT_SUPPORTED   0x81
 An invalid opcode has been used in a control point procedure.
 
#define BT_AICS_ERR_MUTE_DISABLED   0x82
 Mute/unmute commands are disabled.
 
#define BT_AICS_ERR_OUT_OF_RANGE   0x83
 An operand value used in a control point procedure is outside the permissible range.
 
#define BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED   0x84
 A requested gain mode change is not allowed.
 

Detailed Description

Audio Input Control Service (AICS)

Since
2.6
Version
0.8.0

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.

Macro Definition Documentation

◆ BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED

#define BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED   0x84

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

A requested gain mode change is not allowed.

◆ BT_AICS_ERR_INVALID_COUNTER

#define BT_AICS_ERR_INVALID_COUNTER   0x80

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

The Change_Counter operand value does not match the Change_Counter field value of the Audio Input State characteristic.

◆ BT_AICS_ERR_MUTE_DISABLED

#define BT_AICS_ERR_MUTE_DISABLED   0x82

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

Mute/unmute commands are disabled.

(see BT_AICS_STATE_MUTE_DISABLED)

◆ BT_AICS_ERR_OP_NOT_SUPPORTED

#define BT_AICS_ERR_OP_NOT_SUPPORTED   0x81

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

An invalid opcode has been used in a control point procedure.

◆ BT_AICS_ERR_OUT_OF_RANGE

#define BT_AICS_ERR_OUT_OF_RANGE   0x83

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

An operand value used in a control point procedure is outside the permissible range.

◆ BT_AICS_INPUT_TYPE_AMBIENT

#define BT_AICS_INPUT_TYPE_AMBIENT   0x07

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

The input is transparent / pass-through.

◆ BT_AICS_INPUT_TYPE_ANALOG

#define BT_AICS_INPUT_TYPE_ANALOG   0x03

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

The input is analog.

◆ BT_AICS_INPUT_TYPE_BLUETOOTH

#define BT_AICS_INPUT_TYPE_BLUETOOTH   0x01

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

The input is a Bluetooth Audio Stream.

◆ BT_AICS_INPUT_TYPE_DIGITAL

#define BT_AICS_INPUT_TYPE_DIGITAL   0x04

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

The input is digital.

◆ BT_AICS_INPUT_TYPE_MICROPHONE

#define BT_AICS_INPUT_TYPE_MICROPHONE   0x02

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

The input is a microphone.

◆ BT_AICS_INPUT_TYPE_RADIO

#define BT_AICS_INPUT_TYPE_RADIO   0x05

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

The input is a radio (AM/FM/XM/etc.)

◆ BT_AICS_INPUT_TYPE_STREAMING

#define BT_AICS_INPUT_TYPE_STREAMING   0x06

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

The input is a Streaming Audio Source.

◆ BT_AICS_INPUT_TYPE_UNSPECIFIED

#define BT_AICS_INPUT_TYPE_UNSPECIFIED   0x00

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

The input is unspecified.

◆ BT_AICS_MODE_AUTO

#define BT_AICS_MODE_AUTO   0x03

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

The gain mode is automatic.

The gain cannot be controlled by the client.

◆ BT_AICS_MODE_AUTO_ONLY

#define BT_AICS_MODE_AUTO_ONLY   0x01

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

The gain mode is automatic only and cannot be changed to manual.

The gain cannot be controlled by the client.

◆ BT_AICS_MODE_MANUAL

#define BT_AICS_MODE_MANUAL   0x02

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

The gain mode is manual.

The gain can be controlled by the client.

◆ BT_AICS_MODE_MANUAL_ONLY

#define BT_AICS_MODE_MANUAL_ONLY   0x00

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

The gain mode is manual only and cannot be changed to automatic.

The gain can be controlled by the client.

◆ BT_AICS_STATE_MUTE_DISABLED

#define BT_AICS_STATE_MUTE_DISABLED   0x02

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

The mute state is disabled.

◆ BT_AICS_STATE_MUTED

#define BT_AICS_STATE_MUTED   0x01

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

The mute state is muted.

◆ BT_AICS_STATE_UNMUTED

#define BT_AICS_STATE_UNMUTED   0x00

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

The mute state is unmuted.

Typedef Documentation

◆ bt_aics_description_cb

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

#include <include/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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_disable_mute()

int bt_aics_disable_mute ( struct bt_aics *  inst)

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

Disable mute in the Audio Input Control Service.

Calling bt_aics_unmute() or bt_aics_mute() will enable mute again and set the mute state to either unmuted or muted.

Parameters
instThe instance pointer.
Returns
0 on success, errno 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/zephyr/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/zephyr/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/zephyr/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_set_auto_only()

int bt_aics_gain_set_auto_only ( struct bt_aics *  inst)

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

Set automatic only gain mode in Audio Input Control Service.

Using this function and enabling automatic only gain disables setting the gain with bt_aics_gain_set

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

◆ bt_aics_gain_set_manual_only()

int bt_aics_gain_set_manual_only ( struct bt_aics *  inst)

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

Set manual only gain mode in Audio Input Control Service.

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

◆ bt_aics_gain_setting_get()

int bt_aics_gain_setting_get ( struct bt_aics *  inst)

#include <include/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/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/zephyr/bluetooth/audio/aics.h>

Unmute the Audio Input Control Service input.

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