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

The input is transparent / pass-through.

◆ BT_AICS_INPUT_TYPE_ANALOG

#define BT_AICS_INPUT_TYPE_ANALOG 0x03

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

The input is analog.

◆ BT_AICS_INPUT_TYPE_BLUETOOTH

#define BT_AICS_INPUT_TYPE_BLUETOOTH 0x01

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

The input is digital.

◆ BT_AICS_INPUT_TYPE_MICROPHONE

#define BT_AICS_INPUT_TYPE_MICROPHONE 0x02

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

The input is a microphone.

◆ BT_AICS_INPUT_TYPE_RADIO

#define BT_AICS_INPUT_TYPE_RADIO 0x05

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

The input is unspecified.

◆ BT_AICS_MODE_AUTO

#define BT_AICS_MODE_AUTO 0x03

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

The mute state is disabled.

◆ BT_AICS_STATE_MUTED

#define BT_AICS_STATE_MUTED 0x01

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

The mute state is muted.

◆ BT_AICS_STATE_UNMUTED

#define BT_AICS_STATE_UNMUTED 0x00

#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 <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

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
description	The 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 <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

inst	The instance pointer.
err	Error 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 <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

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
units	The value that reflect the size of a single increment or decrement of the Gain Setting value in 0.1 decibel units.
minimum	The minimum gain allowed for the gain setting.
maximum	The 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 <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

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
gain	The gain setting value.
mute	The mute value.
mode	The mode value.

◆ bt_aics_status_cb

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

#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

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
active	Whether 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 <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

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
type	The input type.

◆ bt_aics_write_cb

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

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

Callback function for writes.

Parameters

inst	The instance pointer.
err	Error 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 <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

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Set the input gain to automatic.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Registers the callbacks for the Audio Input Control Service client.

Parameters

inst	The instance pointer.
cb	Pointer 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 <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

aics	Audio Input Control Service client instance pointer.
conn	Connection 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 <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 <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

inst	The instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_aics_description_get()

int bt_aics_description_get ( struct bt_aics * inst )

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

Read the Audio Input Control Service description.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Set the Audio Input Control Service description.

Parameters

inst	The instance pointer.
description	The 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 <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

inst	The 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 <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

conn	Connection to the peer with the Audio Input Control Service.
inst	The instance pointer.
param	Pointer 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 <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 <zephyr/bluetooth/audio/aics.h>

Set the input gain.

Parameters

inst	The instance pointer.
gain	The 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 <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

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Set manual only gain mode in Audio Input Control Service.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Read the Audio Input Control Service gain settings.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Set input gain to manual.

Parameters

inst	The instance pointer.

Returns: 0 on success, GATT error value on fail.

◆ bt_aics_mute()

int bt_aics_mute ( struct bt_aics * inst )

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

Mute the Audio Input Control Service input.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Initialize the Audio Input Control Service instance.

Parameters

aics	Audio Input Control Service instance.
param	Audio 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 <zephyr/bluetooth/audio/aics.h>

Read the Audio Input Control Service input state.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Read the Audio Input Control Service input status.

Parameters

inst	The 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 <zephyr/bluetooth/audio/aics.h>

Get the service declaration attribute.

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

Parameters

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

Read the Audio Input Control Service input type.

Parameters

inst	The instance pointer.

Returns: 0 on success, GATT error value on fail.

◆ bt_aics_unmute()

int bt_aics_unmute ( struct bt_aics * inst )

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

Unmute the Audio Input Control Service input.

Parameters

inst	The instance pointer.

Returns: 0 on success, GATT error value on fail.

Data Structures

Typedefs

Functions

Audio Input Control Service mute states

Audio Input Control Service input modes

Audio Input Control Service input types

Audio Input Control Service Error codes

Detailed Description

Macro Definition Documentation

◆ BT_AICS_ERR_GAIN_MODE_NOT_ALLOWED

◆ BT_AICS_ERR_INVALID_COUNTER

◆ BT_AICS_ERR_MUTE_DISABLED

◆ BT_AICS_ERR_OP_NOT_SUPPORTED

◆ BT_AICS_ERR_OUT_OF_RANGE

◆ BT_AICS_INPUT_TYPE_AMBIENT

◆ BT_AICS_INPUT_TYPE_ANALOG

◆ BT_AICS_INPUT_TYPE_BLUETOOTH

◆ BT_AICS_INPUT_TYPE_DIGITAL

◆ BT_AICS_INPUT_TYPE_MICROPHONE

◆ BT_AICS_INPUT_TYPE_RADIO

◆ BT_AICS_INPUT_TYPE_STREAMING

◆ BT_AICS_INPUT_TYPE_UNSPECIFIED

◆ BT_AICS_MODE_AUTO

◆ BT_AICS_MODE_AUTO_ONLY

◆ BT_AICS_MODE_MANUAL

◆ BT_AICS_MODE_MANUAL_ONLY

◆ BT_AICS_STATE_MUTE_DISABLED

◆ BT_AICS_STATE_MUTED

◆ BT_AICS_STATE_UNMUTED

Typedef Documentation

◆ bt_aics_description_cb

◆ bt_aics_discover_cb

◆ bt_aics_gain_setting_cb

◆ bt_aics_state_cb

◆ bt_aics_status_cb

◆ bt_aics_type_cb

◆ bt_aics_write_cb

Function Documentation

◆ bt_aics_activate()

◆ bt_aics_automatic_gain_set()

◆ bt_aics_client_cb_register()

◆ bt_aics_client_conn_get()

◆ bt_aics_client_free_instance_get()

◆ bt_aics_deactivate()

◆ bt_aics_description_get()

◆ bt_aics_description_set()

◆ bt_aics_disable_mute()

◆ bt_aics_discover()

◆ bt_aics_free_instance_get()

◆ bt_aics_gain_set()

◆ bt_aics_gain_set_auto_only()

◆ bt_aics_gain_set_manual_only()

◆ bt_aics_gain_setting_get()

◆ bt_aics_manual_gain_set()

◆ bt_aics_mute()

◆ bt_aics_register()

◆ bt_aics_state_get()

◆ bt_aics_status_get()

◆ bt_aics_svc_decl_get()

◆ bt_aics_type_get()

◆ bt_aics_unmute()