Health Server
The Health Server model provides attention callbacks and node diagnostics for Health Client models. It is primarily used to report faults in the mesh node and map the mesh nodes to their physical location.
Faults
The Health Server model may report a list of faults that have occurred in the device’s lifetime. Typically, the faults are events or conditions that may alter the behavior of the node, like power outages or faulty peripherals. Faults are split into warnings and errors. Warnings indicate conditions that are close to the limits of what the node is designed to withstand, but not necessarily damaging to the device. Errors indicate conditions that are outside of the node’s design limits, and may have caused invalid behavior or permanent damage to the device.
Fault values 0x01 to 0x7f are reserved for the Bluetooth mesh
specification, and the full list of specification defined faults are available
in Health faults. Fault values 0x80 to 0xff are
vendor specific. The list of faults are always reported with a company ID to
help interpreting the vendor specific faults.
Attention state
The attention state is used to make the device call attention to itself through some physical behavior like blinking, playing a sound or vibrating. The attention state may be used during provisioning to let the user know which device they’re provisioning, as well as through the Health models at runtime.
The attention state is always assigned a timeout in the range of one to 255
seconds when enabled. The Health Server API provides two callbacks for the
application to run their attention calling behavior:
bt_mesh_health_srv_cb.attn_on is called at the beginning of the
attention period, bt_mesh_health_srv_cb.attn_off is called at
the end.
The remaining time for the attention period may be queried through
bt_mesh_health_srv.attn_timer.
API reference
- group bt_mesh_health_srv
Health Server Model.
Defines
-
BT_MESH_HEALTH_PUB_DEFINE(_name, _max_faults)
A helper to define a health publication context
- Parameters
_name – Name given to the publication context variable.
_max_faults – Maximum number of faults the element can have.
-
BT_MESH_MODEL_HEALTH_SRV(srv, pub)
Define a new health server model. Note that this API needs to be repeated for each element that the application wants to have a health server model on. Each instance also needs a unique bt_mesh_health_srv and bt_mesh_model_pub context.
- Parameters
srv – Pointer to a unique struct bt_mesh_health_srv.
pub – Pointer to a unique struct bt_mesh_model_pub.
- Returns
New mesh model instance.
Functions
-
int bt_mesh_fault_update(struct bt_mesh_elem *elem)
Notify the stack that the fault array state of the given element has changed.
This prompts the Health server on this element to publish the current fault array if periodic publishing is disabled.
- Parameters
elem – Element to update the fault state of.
- Returns
0 on success, or (negative) error code otherwise.
-
struct bt_mesh_health_srv_cb
- #include <health_srv.h>
Callback function for the Health Server model
Public Members
-
int (*fault_get_cur)(struct bt_mesh_model *model, uint8_t *test_id, uint16_t *company_id, uint8_t *faults, uint8_t *fault_count)
Callback for fetching current faults.
Fault values may either be defined by the specification, or by a vendor. Vendor specific faults should be interpreted in the context of the accompanying Company ID. Specification defined faults may be reported for any Company ID, and the same fault may be presented for multiple Company IDs.
All faults shall be associated with at least one Company ID, representing the device vendor or some other vendor whose vendor specific fault values are used.
If there are multiple Company IDs that have active faults, return only the faults associated with one of them at the time. To report faults for multiple Company IDs, interleave which Company ID is reported for each call.
- Param model
Health Server model instance to get faults of.
- Param test_id
Test ID response buffer.
- Param company_id
Company ID response buffer.
- Param faults
Array to fill with current faults.
- Param fault_count
The number of faults the fault array can fit. Should be updated to reflect the number of faults copied into the array.
- Return
0 on success, or (negative) error code otherwise.
-
int (*fault_get_reg)(struct bt_mesh_model *model, uint16_t company_id, uint8_t *test_id, uint8_t *faults, uint8_t *fault_count)
Callback for fetching all registered faults.
Registered faults are all past and current faults since the last call to
fault_clear. Only faults associated with the given Company ID should be reported.Fault values may either be defined by the specification, or by a vendor. Vendor specific faults should be interpreted in the context of the accompanying Company ID. Specification defined faults may be reported for any Company ID, and the same fault may be presented for multiple Company IDs.
- Param model
Health Server model instance to get faults of.
- Param company_id
Company ID to get faults for.
- Param test_id
Test ID response buffer.
- Param faults
Array to fill with registered faults.
- Param fault_count
The number of faults the fault array can fit. Should be updated to reflect the number of faults copied into the array.
- Return
0 on success, or (negative) error code otherwise.
-
int (*fault_clear)(struct bt_mesh_model *model, uint16_t company_id)
Clear all registered faults associated with the given Company ID.
- Param model
Health Server model instance to clear faults of.
- Param company_id
Company ID to clear faults for.
- Return
0 on success, or (negative) error code otherwise.
-
int (*fault_test)(struct bt_mesh_model *model, uint8_t test_id, uint16_t company_id)
Run a self-test.
The Health server may support up to 256 self-tests for each Company ID. The behavior for all test IDs are vendor specific, and should be interpreted based on the accompanying Company ID. Test failures should result in changes to the fault array.
- Param model
Health Server model instance to run test for.
- Param test_id
Test ID to run.
- Param company_id
Company ID to run test for.
- Return
0 if the test execution was started successfully, or (negative) error code otherwise. Note that the fault array will not be reported back to the client if the test execution didn’t start.
-
void (*attn_on)(struct bt_mesh_model *model)
Start calling attention to the device.
The attention state is used to map an element address to a physical device. When this callback is called, the device should start some physical procedure meant to call attention to itself, like blinking, buzzing, vibrating or moving. If there are multiple Health server instances on the device, the attention state should also help identify the specific element the server is in.
The attention calling behavior should continue until the
attn_offcallback is called.- Param model
Health Server model to start the attention state of.
-
void (*attn_off)(struct bt_mesh_model *model)
Stop the attention state.
Any physical activity started to call attention to the device should be stopped.
- Param model
-
int (*fault_get_cur)(struct bt_mesh_model *model, uint8_t *test_id, uint16_t *company_id, uint8_t *faults, uint8_t *fault_count)
-
struct bt_mesh_health_srv
- #include <health_srv.h>
Mesh Health Server Model Context
Public Members
-
struct bt_mesh_model *model
Composition data model entry pointer.
-
const struct bt_mesh_health_srv_cb *cb
Optional callback struct
-
struct k_work_delayable attn_timer
Attention Timer state
-
struct bt_mesh_model *model
-
BT_MESH_HEALTH_PUB_DEFINE(_name, _max_faults)
Health faults
Fault values defined by the Bluetooth mesh specification.
- group bt_mesh_health_faults
List of specification defined Health fault values.
Defines
-
BT_MESH_HEALTH_FAULT_NO_FAULT
No fault has occurred.
-
BT_MESH_HEALTH_FAULT_BATTERY_LOW_WARNING
-
BT_MESH_HEALTH_FAULT_BATTERY_LOW_ERROR
-
BT_MESH_HEALTH_FAULT_SUPPLY_VOLTAGE_TOO_LOW_WARNING
-
BT_MESH_HEALTH_FAULT_SUPPLY_VOLTAGE_TOO_LOW_ERROR
-
BT_MESH_HEALTH_FAULT_SUPPLY_VOLTAGE_TOO_HIGH_WARNING
-
BT_MESH_HEALTH_FAULT_SUPPLY_VOLTAGE_TOO_HIGH_ERROR
-
BT_MESH_HEALTH_FAULT_POWER_SUPPLY_INTERRUPTED_WARNING
-
BT_MESH_HEALTH_FAULT_POWER_SUPPLY_INTERRUPTED_ERROR
-
BT_MESH_HEALTH_FAULT_NO_LOAD_WARNING
-
BT_MESH_HEALTH_FAULT_NO_LOAD_ERROR
-
BT_MESH_HEALTH_FAULT_OVERLOAD_WARNING
-
BT_MESH_HEALTH_FAULT_OVERLOAD_ERROR
-
BT_MESH_HEALTH_FAULT_OVERHEAT_WARNING
-
BT_MESH_HEALTH_FAULT_OVERHEAT_ERROR
-
BT_MESH_HEALTH_FAULT_CONDENSATION_WARNING
-
BT_MESH_HEALTH_FAULT_CONDENSATION_ERROR
-
BT_MESH_HEALTH_FAULT_VIBRATION_WARNING
-
BT_MESH_HEALTH_FAULT_VIBRATION_ERROR
-
BT_MESH_HEALTH_FAULT_CONFIGURATION_WARNING
-
BT_MESH_HEALTH_FAULT_CONFIGURATION_ERROR
-
BT_MESH_HEALTH_FAULT_ELEMENT_NOT_CALIBRATED_WARNING
-
BT_MESH_HEALTH_FAULT_ELEMENT_NOT_CALIBRATED_ERROR
-
BT_MESH_HEALTH_FAULT_MEMORY_WARNING
-
BT_MESH_HEALTH_FAULT_MEMORY_ERROR
-
BT_MESH_HEALTH_FAULT_SELF_TEST_WARNING
-
BT_MESH_HEALTH_FAULT_SELF_TEST_ERROR
-
BT_MESH_HEALTH_FAULT_INPUT_TOO_LOW_WARNING
-
BT_MESH_HEALTH_FAULT_INPUT_TOO_LOW_ERROR
-
BT_MESH_HEALTH_FAULT_INPUT_TOO_HIGH_WARNING
-
BT_MESH_HEALTH_FAULT_INPUT_TOO_HIGH_ERROR
-
BT_MESH_HEALTH_FAULT_INPUT_NO_CHANGE_WARNING
-
BT_MESH_HEALTH_FAULT_INPUT_NO_CHANGE_ERROR
-
BT_MESH_HEALTH_FAULT_ACTUATOR_BLOCKED_WARNING
-
BT_MESH_HEALTH_FAULT_ACTUATOR_BLOCKED_ERROR
-
BT_MESH_HEALTH_FAULT_HOUSING_OPENED_WARNING
-
BT_MESH_HEALTH_FAULT_HOUSING_OPENED_ERROR
-
BT_MESH_HEALTH_FAULT_TAMPER_WARNING
-
BT_MESH_HEALTH_FAULT_TAMPER_ERROR
-
BT_MESH_HEALTH_FAULT_DEVICE_MOVED_WARNING
-
BT_MESH_HEALTH_FAULT_DEVICE_MOVED_ERROR
-
BT_MESH_HEALTH_FAULT_DEVICE_DROPPED_WARNING
-
BT_MESH_HEALTH_FAULT_DEVICE_DROPPED_ERROR
-
BT_MESH_HEALTH_FAULT_OVERFLOW_WARNING
-
BT_MESH_HEALTH_FAULT_OVERFLOW_ERROR
-
BT_MESH_HEALTH_FAULT_EMPTY_WARNING
-
BT_MESH_HEALTH_FAULT_EMPTY_ERROR
-
BT_MESH_HEALTH_FAULT_INTERNAL_BUS_WARNING
-
BT_MESH_HEALTH_FAULT_INTERNAL_BUS_ERROR
-
BT_MESH_HEALTH_FAULT_MECHANISM_JAMMED_WARNING
-
BT_MESH_HEALTH_FAULT_MECHANISM_JAMMED_ERROR
-
BT_MESH_HEALTH_FAULT_VENDOR_SPECIFIC_START
Start of the vendor specific fault values.
All values below this are reserved for the Bluetooth Specification.
-
BT_MESH_HEALTH_FAULT_NO_FAULT