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