Health Client

The Health Client model interacts with a Health Server model to read out diagnostics and control the node’s attention state.

All message passing functions in the Health Client API have cli as their first parameter. This is a pointer to the client model instance to be used in this function call. The second parameter is the ctx or message context. Message context contains netkey index, appkey index and unicast address that the target node uses.

The Health Client model is optional, and may be instantiated in any element. However, if a Health Client model is instantiated in an element other than the first, an instance must also be present in the first element.

See Health faults for a list of specification defined fault values.

API reference

group bt_mesh_health_cli

Health Client Model.

Defines

BT_MESH_MODEL_HEALTH_CLI(cli_data)

Generic Health Client model composition data entry.

Parameters

Functions

int bt_mesh_health_cli_set(struct bt_mesh_model *model)

Set Health client model instance to use for communication.

Parameters

  • model – Health Client model instance from the composition data.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_fault_get(uint16_t addr, uint16_t app_idx, uint16_t cid, uint8_t *test_id, uint8_t *faults, size_t *fault_count)

Get the registered fault state for the given Company ID.

This method can be used asynchronously by setting test_id and ( faults or fault_count ) as NULL This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the fault_status callback in bt_mesh_health_cli struct.

See also

Health faults

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • cid – Company ID to get the registered faults of.

  • test_id – Test ID response buffer.

  • faults – Fault array response buffer.

  • fault_count – Fault count response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_fault_clear(uint16_t addr, uint16_t app_idx, uint16_t cid, uint8_t *test_id, uint8_t *faults, size_t *fault_count)

Clear the registered faults for the given Company ID.

This method can be used asynchronously by setting test_id and ( faults or fault_count ) as NULL This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the fault_status callback in bt_mesh_health_cli struct.

See also

Health faults

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • cid – Company ID to clear the registered faults for.

  • test_id – Test ID response buffer.

  • faults – Fault array response buffer.

  • fault_count – Fault count response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_fault_clear_unack(uint16_t addr, uint16_t app_idx, uint16_t cid)

Clear the registered faults for the given Company ID (unacked).

See also

Health faults

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • cid – Company ID to clear the registered faults for.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_fault_test(uint16_t addr, uint16_t app_idx, uint16_t cid, uint8_t test_id, uint8_t *faults, size_t *fault_count)

Invoke a self-test procedure for the given Company ID.

This method can be used asynchronously by setting faults or fault_count as NULL This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the fault_status callback in bt_mesh_health_cli struct.

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • cid – Company ID to invoke the test for.

  • test_id – Test ID response buffer.

  • faults – Fault array response buffer.

  • fault_count – Fault count response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_fault_test_unack(uint16_t addr, uint16_t app_idx, uint16_t cid, uint8_t test_id)

Invoke a self-test procedure for the given Company ID (unacked).

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • cid – Company ID to invoke the test for.

  • test_id – Test ID response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_period_get(uint16_t addr, uint16_t app_idx, uint8_t *divisor)

Get the target node’s Health fast period divisor.

The health period divisor is used to increase the publish rate when a fault is registered. Normally, the Health server will publish with the period in the configured publish parameters. When a fault is registered, the publish period is divided by (1 << divisor). For example, if the target node’s Health server is configured to publish with a period of 16 seconds, and the Health fast period divisor is 5, the Health server will publish with an interval of 500 ms when a fault is registered.

This method can be used asynchronously by setting divisor as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the period_status callback in bt_mesh_health_cli struct.

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • divisor – Health period divisor response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_period_set(uint16_t addr, uint16_t app_idx, uint8_t divisor, uint8_t *updated_divisor)

Set the target node’s Health fast period divisor.

The health period divisor is used to increase the publish rate when a fault is registered. Normally, the Health server will publish with the period in the configured publish parameters. When a fault is registered, the publish period is divided by (1 << divisor). For example, if the target node’s Health server is configured to publish with a period of 16 seconds, and the Health fast period divisor is 5, the Health server will publish with an interval of 500 ms when a fault is registered.

This method can be used asynchronously by setting updated_divisor as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the period_status callback in bt_mesh_health_cli struct.

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • divisor – New Health period divisor.

  • updated_divisor – Health period divisor response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_period_set_unack(uint16_t addr, uint16_t app_idx, uint8_t divisor)

Set the target node’s Health fast period divisor (unacknowledged).

This is an unacknowledged version of this API.

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • divisor – New Health period divisor.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_attention_get(uint16_t addr, uint16_t app_idx, uint8_t *attention)

Get the current attention timer value.

This method can be used asynchronously by setting attention as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the attention_status callback in bt_mesh_health_cli struct.

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • attention – Attention timer response buffer, measured in seconds.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_attention_set(uint16_t addr, uint16_t app_idx, uint8_t attention, uint8_t *updated_attention)

Set the attention timer.

This method can be used asynchronously by setting updated_attention as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the attention_status callback in bt_mesh_health_cli struct.

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • attention – New attention timer time, in seconds.

  • updated_attention – Attention timer response buffer, measured in seconds.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_attention_set_unack(uint16_t addr, uint16_t app_idx, uint8_t attention)

Set the attention timer (unacknowledged).

Parameters

  • addr – Target node element address.

  • app_idx – Application index to encrypt with.

  • attention – New attention timer time, in seconds.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_fault_get(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t cid, uint8_t *test_id, uint8_t *faults, size_t *fault_count)

Get the registered fault state for the given Company ID.

This method can be used asynchronously by setting test_id and ( faults or fault_count ) as NULL This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the fault_status callback in bt_mesh_health_cli struct.

See also

Health faults

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • cid – Company ID to get the registered faults of.

  • test_id – Test ID response buffer.

  • faults – Fault array response buffer.

  • fault_count – Fault count response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_fault_clear(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t cid, uint8_t *test_id, uint8_t *faults, size_t *fault_count)

Clear the registered faults for the given Company ID.

This method can be used asynchronously by setting test_id and ( faults or fault_count ) as NULL This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the fault_status callback in bt_mesh_health_cli struct.

See also

Health faults

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • cid – Company ID to clear the registered faults for.

  • test_id – Test ID response buffer.

  • faults – Fault array response buffer.

  • fault_count – Fault count response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_fault_clear_unack(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t cid)

Clear the registered faults for the given Company ID (unacked).

See also

Health faults

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • cid – Company ID to clear the registered faults for.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_fault_test(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t cid, uint8_t test_id, uint8_t *faults, size_t *fault_count)

Invoke a self-test procedure for the given Company ID.

This method can be used asynchronously by setting faults or fault_count as NULL This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the fault_status callback in bt_mesh_health_cli struct.

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • cid – Company ID to invoke the test for.

  • test_id – Test ID response buffer.

  • faults – Fault array response buffer.

  • fault_count – Fault count response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_fault_test_unack(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t cid, uint8_t test_id)

Invoke a self-test procedure for the given Company ID (unacked).

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • cid – Company ID to invoke the test for.

  • test_id – Test ID response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_period_get(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t *divisor)

Get the target node’s Health fast period divisor.

The health period divisor is used to increase the publish rate when a fault is registered. Normally, the Health server will publish with the period in the configured publish parameters. When a fault is registered, the publish period is divided by (1 << divisor). For example, if the target node’s Health server is configured to publish with a period of 16 seconds, and the Health fast period divisor is 5, the Health server will publish with an interval of 500 ms when a fault is registered.

This method can be used asynchronously by setting divisor as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the period_status callback in bt_mesh_health_cli struct.

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • divisor – Health period divisor response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_period_set(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t divisor, uint8_t *updated_divisor)

Set the target node’s Health fast period divisor.

The health period divisor is used to increase the publish rate when a fault is registered. Normally, the Health server will publish with the period in the configured publish parameters. When a fault is registered, the publish period is divided by (1 << divisor). For example, if the target node’s Health server is configured to publish with a period of 16 seconds, and the Health fast period divisor is 5, the Health server will publish with an interval of 500 ms when a fault is registered.

This method can be used asynchronously by setting updated_divisor as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the period_status callback in bt_mesh_health_cli struct.

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • divisor – New Health period divisor.

  • updated_divisor – Health period divisor response buffer.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_period_set_unack(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t divisor)

Set the target node’s Health fast period divisor (unacknowledged).

This is an unacknowledged version of this API.

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • divisor – New Health period divisor.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_attention_get(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t *attention)

Get the current attention timer value.

This method can be used asynchronously by setting attention as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the attention_status callback in bt_mesh_health_cli struct.

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • attention – Attention timer response buffer, measured in seconds.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_attention_set(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t attention, uint8_t *updated_attention)

Set the attention timer.

This method can be used asynchronously by setting updated_attention as NULL. This way the method will not wait for response and will return immediately after sending the command.

To process the response arguments of an async method, register the attention_status callback in bt_mesh_health_cli struct.

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • attention – New attention timer time, in seconds.

  • updated_attention – Attention timer response buffer, measured in seconds.

Returns

0 on success, or (negative) error code on failure.

int bt_mesh_health_cli_attention_set_unack(struct bt_mesh_health_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t attention)

Set the attention timer (unacknowledged).

Parameters

  • cli – Client model to send on.

  • ctx – Message context, or NULL to use the configured publish parameters.

  • attention – New attention timer time, in seconds.

Returns

0 on success, or (negative) error code on failure.

int32_t bt_mesh_health_cli_timeout_get(void)

Get the current transmission timeout value.

Returns

The configured transmission timeout in milliseconds.

void bt_mesh_health_cli_timeout_set(int32_t timeout)

Set the transmission timeout value.

Parameters

  • timeout – The new transmission timeout.

struct bt_mesh_health_cli
#include <health_cli.h>

Health Client Model Context

Public Members

struct bt_mesh_model *model

Composition data model entry pointer.

struct bt_mesh_model_pub pub

Publication structure instance

struct net_buf_simple pub_buf

Publication buffer

uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_MODEL_OP_2(0x80, 0x32), 3)]

Publication data

void (*period_status)(struct bt_mesh_health_cli *cli, uint16_t addr, uint8_t divisor)

Optional callback for Health Period Status messages.

Handles received Health Period Status messages from a Health server. The divisor param represents the period divisor value.

Param cli

Health client that received the status message.

Param addr

Address of the sender.

Param divisor

Health Period Divisor value.

void (*attention_status)(struct bt_mesh_health_cli *cli, uint16_t addr, uint8_t attention)

Optional callback for Health Attention Status messages.

Handles received Health Attention Status messages from a Health server. The attention param represents the current attention value.

Param cli

Health client that received the status message.

Param addr

Address of the sender.

Param attention

Current attention value.

void (*fault_status)(struct bt_mesh_health_cli *cli, uint16_t addr, uint8_t test_id, uint16_t cid, uint8_t *faults, size_t fault_count)

Optional callback for Health Fault Status messages.

Handles received Health Fault Status messages from a Health server. The fault array represents all faults that are currently present in the server’s element.

See also

Health faults

Param cli

Health client that received the status message.

Param addr

Address of the sender.

Param test_id

Identifier of a most recently performed test.

Param cid

Company Identifier of the node.

Param faults

Array of faults.

Param fault_count

Number of faults in the fault array.

void (*current_status)(struct bt_mesh_health_cli *cli, uint16_t addr, uint8_t test_id, uint16_t cid, uint8_t *faults, size_t fault_count)

Optional callback for Health Current Status messages.

Handles received Health Current Status messages from a Health server. The fault array represents all faults that are currently present in the server’s element.

See also

Health faults

Param cli

Health client that received the status message.

Param addr

Address of the sender.

Param test_id

Identifier of a most recently performed test.

Param cid

Company Identifier of the node.

Param faults

Array of faults.

Param fault_count

Number of faults in the fault array.