Line data Source code
1 1 : /** @file
2 : * @brief Health Client Model APIs.
3 : */
4 :
5 : /*
6 : * Copyright (c) 2017 Intel Corporation
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEALTH_CLI_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEALTH_CLI_H_
12 :
13 : #include <zephyr/bluetooth/mesh.h>
14 :
15 : /**
16 : * @brief Health Client Model
17 : * @defgroup bt_mesh_health_cli Health Client Model
18 : * @ingroup bt_mesh
19 : * @{
20 : */
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : /** Health Client Model Context */
27 1 : struct bt_mesh_health_cli {
28 : /** Composition data model entry pointer. */
29 1 : const struct bt_mesh_model *model;
30 :
31 : /** Publication structure instance */
32 1 : struct bt_mesh_model_pub pub;
33 :
34 : /** Publication buffer */
35 1 : struct net_buf_simple pub_buf;
36 :
37 : /** Publication data */
38 1 : uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_MODEL_OP_2(0x80, 0x32), 3)];
39 :
40 : /** @brief Optional callback for Health Period Status messages.
41 : *
42 : * Handles received Health Period Status messages from a Health
43 : * server. The @c divisor param represents the period divisor value.
44 : *
45 : * @param cli Health client that received the status message.
46 : * @param addr Address of the sender.
47 : * @param divisor Health Period Divisor value.
48 : */
49 1 : void (*period_status)(struct bt_mesh_health_cli *cli, uint16_t addr,
50 : uint8_t divisor);
51 :
52 : /** @brief Optional callback for Health Attention Status messages.
53 : *
54 : * Handles received Health Attention Status messages from a Health
55 : * server. The @c attention param represents the current attention value.
56 : *
57 : * @param cli Health client that received the status message.
58 : * @param addr Address of the sender.
59 : * @param attention Current attention value.
60 : */
61 1 : void (*attention_status)(struct bt_mesh_health_cli *cli, uint16_t addr,
62 : uint8_t attention);
63 :
64 : /** @brief Optional callback for Health Fault Status messages.
65 : *
66 : * Handles received Health Fault Status messages from a Health
67 : * server. The @c fault array represents all faults that are
68 : * currently present in the server's element.
69 : *
70 : * @see bt_mesh_health_faults
71 : *
72 : * @param cli Health client that received the status message.
73 : * @param addr Address of the sender.
74 : * @param test_id Identifier of a most recently performed test.
75 : * @param cid Company Identifier of the node.
76 : * @param faults Array of faults.
77 : * @param fault_count Number of faults in the fault array.
78 : */
79 1 : void (*fault_status)(struct bt_mesh_health_cli *cli, uint16_t addr,
80 : uint8_t test_id, uint16_t cid, uint8_t *faults,
81 : size_t fault_count);
82 :
83 : /** @brief Optional callback for Health Current Status messages.
84 : *
85 : * Handles received Health Current Status messages from a Health
86 : * server. The @c fault array represents all faults that are
87 : * currently present in the server's element.
88 : *
89 : * @see bt_mesh_health_faults
90 : *
91 : * @param cli Health client that received the status message.
92 : * @param addr Address of the sender.
93 : * @param test_id Identifier of a most recently performed test.
94 : * @param cid Company Identifier of the node.
95 : * @param faults Array of faults.
96 : * @param fault_count Number of faults in the fault array.
97 : */
98 1 : void (*current_status)(struct bt_mesh_health_cli *cli, uint16_t addr,
99 : uint8_t test_id, uint16_t cid, uint8_t *faults,
100 : size_t fault_count);
101 :
102 : /** @brief Optional callback for updating the message to be sent as periodic publication.
103 : *
104 : * This callback is called before sending the periodic publication message.
105 : * The callback can be used to update the message to be sent.
106 : *
107 : * If this callback is not implemented, periodic publication can still be enabled,
108 : * but no messages will be sent.
109 : *
110 : * @param cli Health client that is sending the periodic publication message.
111 : * @param pub_buf Publication message buffer to be updated.
112 : *
113 : * @return 0 if @p pub_buf is updated successfully, or (negative) error code on failure.
114 : * The message won't be sent if an error is returned.
115 : */
116 1 : int (*update)(struct bt_mesh_health_cli *cli, struct net_buf_simple *pub_buf);
117 :
118 : /* Internal parameters for tracking message responses. */
119 0 : struct bt_mesh_msg_ack_ctx ack_ctx;
120 : };
121 :
122 : /**
123 : * @brief Generic Health Client model composition data entry.
124 : *
125 : * @param cli_data Pointer to a @ref bt_mesh_health_cli instance.
126 : */
127 1 : #define BT_MESH_MODEL_HEALTH_CLI(cli_data) \
128 : BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_HEALTH_CLI, bt_mesh_health_cli_op, \
129 : &(cli_data)->pub, cli_data, &bt_mesh_health_cli_cb)
130 :
131 : /** @brief Get the registered fault state for the given Company ID.
132 : *
133 : * This method can be used asynchronously by setting @p test_id
134 : * and ( @p faults or @p fault_count ) as NULL This way the method
135 : * will not wait for response and will return immediately after
136 : * sending the command.
137 : *
138 : * To process the response arguments of an async method, register
139 : * the @c fault_status callback in @c bt_mesh_health_cli struct.
140 : *
141 : * @see bt_mesh_health_faults
142 : *
143 : * @param cli Client model to send on.
144 : * @param ctx Message context, or NULL to use the configured publish
145 : * parameters.
146 : * @param cid Company ID to get the registered faults of.
147 : * @param test_id Test ID response buffer.
148 : * @param faults Fault array response buffer.
149 : * @param fault_count Fault count response buffer.
150 : *
151 : * @return 0 on success, or (negative) error code on failure.
152 : */
153 1 : int bt_mesh_health_cli_fault_get(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
154 : uint16_t cid, uint8_t *test_id, uint8_t *faults,
155 : size_t *fault_count);
156 :
157 : /** @brief Clear the registered faults for the given Company ID.
158 : *
159 : * This method can be used asynchronously by setting @p test_id
160 : * and ( @p faults or @p fault_count ) as NULL This way the method
161 : * will not wait for response and will return immediately after
162 : * sending the command.
163 : *
164 : * To process the response arguments of an async method, register
165 : * the @c fault_status callback in @c bt_mesh_health_cli struct.
166 : *
167 : * @see bt_mesh_health_faults
168 : *
169 : * @param cli Client model to send on.
170 : * @param ctx Message context, or NULL to use the configured publish
171 : * parameters.
172 : * @param cid Company ID to clear the registered faults for.
173 : * @param test_id Test ID response buffer.
174 : * @param faults Fault array response buffer.
175 : * @param fault_count Fault count response buffer.
176 : *
177 : * @return 0 on success, or (negative) error code on failure.
178 : */
179 1 : int bt_mesh_health_cli_fault_clear(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
180 : uint16_t cid, uint8_t *test_id, uint8_t *faults,
181 : size_t *fault_count);
182 :
183 : /** @brief Clear the registered faults for the given Company ID (unacked).
184 : *
185 : * @see bt_mesh_health_faults
186 : *
187 : * @param cli Client model to send on.
188 : * @param ctx Message context, or NULL to use the configured publish
189 : * parameters.
190 : * @param cid Company ID to clear the registered faults for.
191 : *
192 : * @return 0 on success, or (negative) error code on failure.
193 : */
194 1 : int bt_mesh_health_cli_fault_clear_unack(struct bt_mesh_health_cli *cli,
195 : struct bt_mesh_msg_ctx *ctx, uint16_t cid);
196 :
197 : /** @brief Invoke a self-test procedure for the given Company ID.
198 : *
199 : * This method can be used asynchronously by setting @p faults
200 : * or @p fault_count as NULL This way the method will not wait
201 : * for response and will return immediately after sending the command.
202 : *
203 : * To process the response arguments of an async method, register
204 : * the @c fault_status callback in @c bt_mesh_health_cli struct.
205 : *
206 : * @param cli Client model to send on.
207 : * @param ctx Message context, or NULL to use the configured publish
208 : * parameters.
209 : * @param cid Company ID to invoke the test for.
210 : * @param test_id Test ID response buffer.
211 : * @param faults Fault array response buffer.
212 : * @param fault_count Fault count response buffer.
213 : *
214 : * @return 0 on success, or (negative) error code on failure.
215 : */
216 1 : int bt_mesh_health_cli_fault_test(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
217 : uint16_t cid, uint8_t test_id, uint8_t *faults,
218 : size_t *fault_count);
219 :
220 : /** @brief Invoke a self-test procedure for the given Company ID (unacked).
221 : *
222 : * @param cli Client model to send on.
223 : * @param ctx Message context, or NULL to use the configured publish
224 : * parameters.
225 : * @param cid Company ID to invoke the test for.
226 : * @param test_id Test ID response buffer.
227 : *
228 : * @return 0 on success, or (negative) error code on failure.
229 : */
230 1 : int bt_mesh_health_cli_fault_test_unack(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
231 : uint16_t cid, uint8_t test_id);
232 :
233 : /** @brief Get the target node's Health fast period divisor.
234 : *
235 : * The health period divisor is used to increase the publish rate when a fault
236 : * is registered. Normally, the Health server will publish with the period in
237 : * the configured publish parameters. When a fault is registered, the publish
238 : * period is divided by (1 << divisor). For example, if the target node's
239 : * Health server is configured to publish with a period of 16 seconds, and the
240 : * Health fast period divisor is 5, the Health server will publish with an
241 : * interval of 500 ms when a fault is registered.
242 : *
243 : * This method can be used asynchronously by setting @p divisor
244 : * as NULL. This way the method will not wait for response and will
245 : * return immediately after sending the command.
246 : *
247 : * To process the response arguments of an async method, register
248 : * the @c period_status callback in @c bt_mesh_health_cli struct.
249 : *
250 : * @param cli Client model to send on.
251 : * @param ctx Message context, or NULL to use the configured publish
252 : * parameters.
253 : * @param divisor Health period divisor response buffer.
254 : *
255 : * @return 0 on success, or (negative) error code on failure.
256 : */
257 1 : int bt_mesh_health_cli_period_get(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
258 : uint8_t *divisor);
259 :
260 : /** @brief Set the target node's Health fast period divisor.
261 : *
262 : * The health period divisor is used to increase the publish rate when a fault
263 : * is registered. Normally, the Health server will publish with the period in
264 : * the configured publish parameters. When a fault is registered, the publish
265 : * period is divided by (1 << divisor). For example, if the target node's
266 : * Health server is configured to publish with a period of 16 seconds, and the
267 : * Health fast period divisor is 5, the Health server will publish with an
268 : * interval of 500 ms when a fault is registered.
269 : *
270 : * This method can be used asynchronously by setting @p updated_divisor
271 : * as NULL. This way the method will not wait for response and will
272 : * return immediately after sending the command.
273 : *
274 : * To process the response arguments of an async method, register
275 : * the @c period_status callback in @c bt_mesh_health_cli struct.
276 : *
277 : * @param cli Client model to send on.
278 : * @param ctx Message context, or NULL to use the configured publish
279 : * parameters.
280 : * @param divisor New Health period divisor.
281 : * @param updated_divisor Health period divisor response buffer.
282 : *
283 : * @return 0 on success, or (negative) error code on failure.
284 : */
285 1 : int bt_mesh_health_cli_period_set(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
286 : uint8_t divisor, uint8_t *updated_divisor);
287 :
288 : /** @brief Set the target node's Health fast period divisor (unacknowledged).
289 : *
290 : * This is an unacknowledged version of this API.
291 : *
292 : * @param cli Client model to send on.
293 : * @param ctx Message context, or NULL to use the configured publish
294 : * parameters.
295 : * @param divisor New Health period divisor.
296 : *
297 : * @return 0 on success, or (negative) error code on failure.
298 : */
299 1 : int bt_mesh_health_cli_period_set_unack(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
300 : uint8_t divisor);
301 :
302 : /** @brief Get the current attention timer value.
303 : *
304 : * This method can be used asynchronously by setting @p attention
305 : * as NULL. This way the method will not wait for response and will
306 : * return immediately after sending the command.
307 : *
308 : * To process the response arguments of an async method, register
309 : * the @c attention_status callback in @c bt_mesh_health_cli struct.
310 : *
311 : * @param cli Client model to send on.
312 : * @param ctx Message context, or NULL to use the configured publish
313 : * parameters.
314 : * @param attention Attention timer response buffer, measured in seconds.
315 : *
316 : * @return 0 on success, or (negative) error code on failure.
317 : */
318 1 : int bt_mesh_health_cli_attention_get(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
319 : uint8_t *attention);
320 :
321 : /** @brief Set the attention timer.
322 : *
323 : * This method can be used asynchronously by setting @p updated_attention
324 : * as NULL. This way the method will not wait for response and will
325 : * return immediately after sending the command.
326 : *
327 : * To process the response arguments of an async method, register
328 : * the @c attention_status callback in @c bt_mesh_health_cli struct.
329 : *
330 : * @param cli Client model to send on.
331 : * @param ctx Message context, or NULL to use the configured publish
332 : * parameters.
333 : * @param attention New attention timer time, in seconds.
334 : * @param updated_attention Attention timer response buffer, measured in
335 : * seconds.
336 : *
337 : * @return 0 on success, or (negative) error code on failure.
338 : */
339 1 : int bt_mesh_health_cli_attention_set(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx,
340 : uint8_t attention, uint8_t *updated_attention);
341 :
342 : /** @brief Set the attention timer (unacknowledged).
343 : *
344 : * @param cli Client model to send on.
345 : * @param ctx Message context, or NULL to use the configured publish
346 : * parameters.
347 : * @param attention New attention timer time, in seconds.
348 : *
349 : * @return 0 on success, or (negative) error code on failure.
350 : */
351 1 : int bt_mesh_health_cli_attention_set_unack(struct bt_mesh_health_cli *cli,
352 : struct bt_mesh_msg_ctx *ctx, uint8_t attention);
353 :
354 : /** @brief Get the current transmission timeout value.
355 : *
356 : * @return The configured transmission timeout in milliseconds.
357 : */
358 1 : int32_t bt_mesh_health_cli_timeout_get(void);
359 :
360 : /** @brief Set the transmission timeout value.
361 : *
362 : * @param timeout The new transmission timeout.
363 : */
364 1 : void bt_mesh_health_cli_timeout_set(int32_t timeout);
365 :
366 : /** @cond INTERNAL_HIDDEN */
367 : extern const struct bt_mesh_model_op bt_mesh_health_cli_op[];
368 : extern const struct bt_mesh_model_cb bt_mesh_health_cli_cb;
369 : /** @endcond */
370 :
371 : #ifdef __cplusplus
372 : }
373 : #endif
374 :
375 : /**
376 : * @}
377 : */
378 :
379 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEALTH_CLI_H_ */
|
