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 struct bt_mesh_health_cli { 28 /** Composition data model entry pointer. */ 29 const struct bt_mesh_model *model; 30 31 /** Publication structure instance */ 32 struct bt_mesh_model_pub pub; 33 34 /** Publication buffer */ 35 struct net_buf_simple pub_buf; 36 37 /** Publication data */ 38 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 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 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 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 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 int (*update)(struct bt_mesh_health_cli *cli, struct net_buf_simple *pub_buf); 117 118 /* Internal parameters for tracking message responses. */ 119 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 #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 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 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 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 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 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 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 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 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 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 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 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 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 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_ */ 380
