Line data Source code
1 1 : /** @file 2 : * @brief Health Server 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_SRV_H_ 11 : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEALTH_SRV_H_ 12 : 13 : /** 14 : * @brief Health Server Model 15 : * @defgroup bt_mesh_health_srv Health Server Model 16 : * @ingroup bt_mesh 17 : * @{ 18 : */ 19 : 20 : #include <zephyr/bluetooth/mesh.h> 21 : #include <zephyr/bluetooth/byteorder.h> 22 : 23 : #ifdef __cplusplus 24 : extern "C" { 25 : #endif 26 : 27 : /** Callback function for the Health Server model */ 28 1 : struct bt_mesh_health_srv_cb { 29 : /** @brief Callback for fetching current faults. 30 : * 31 : * Fault values may either be defined by the specification, or by a 32 : * vendor. Vendor specific faults should be interpreted in the context 33 : * of the accompanying Company ID. Specification defined faults may be 34 : * reported for any Company ID, and the same fault may be presented 35 : * for multiple Company IDs. 36 : * 37 : * All faults shall be associated with at least one Company ID, 38 : * representing the device vendor or some other vendor whose vendor 39 : * specific fault values are used. 40 : * 41 : * If there are multiple Company IDs that have active faults, 42 : * return only the faults associated with one of them at the time. 43 : * To report faults for multiple Company IDs, interleave which Company 44 : * ID is reported for each call. 45 : * 46 : * @param model Health Server model instance to get faults of. 47 : * @param test_id Test ID response buffer. 48 : * @param company_id Company ID response buffer. 49 : * @param faults Array to fill with current faults. 50 : * @param fault_count The number of faults the fault array can fit. 51 : * Should be updated to reflect the number of faults 52 : * copied into the array. 53 : * 54 : * @return 0 on success, or (negative) error code otherwise. 55 : */ 56 1 : int (*fault_get_cur)(const struct bt_mesh_model *model, uint8_t *test_id, 57 : uint16_t *company_id, uint8_t *faults, 58 : uint8_t *fault_count); 59 : 60 : /** @brief Callback for fetching all registered faults. 61 : * 62 : * Registered faults are all past and current faults since the last 63 : * call to @c fault_clear. Only faults associated with the given 64 : * Company ID should be reported. 65 : * 66 : * Fault values may either be defined by the specification, or by a 67 : * vendor. Vendor specific faults should be interpreted in the context 68 : * of the accompanying Company ID. Specification defined faults may be 69 : * reported for any Company ID, and the same fault may be presented 70 : * for multiple Company IDs. 71 : * 72 : * @param model Health Server model instance to get faults of. 73 : * @param company_id Company ID to get faults for. 74 : * @param test_id Test ID response buffer. 75 : * @param faults Array to fill with registered faults. 76 : * @param fault_count The number of faults the fault array can fit. 77 : * Should be updated to reflect the number of faults 78 : * copied into the array. 79 : * 80 : * @return 0 on success, or (negative) error code otherwise. 81 : */ 82 1 : int (*fault_get_reg)(const struct bt_mesh_model *model, uint16_t company_id, 83 : uint8_t *test_id, uint8_t *faults, 84 : uint8_t *fault_count); 85 : 86 : /** @brief Clear all registered faults associated with the given Company 87 : * ID. 88 : * 89 : * @param model Health Server model instance to clear faults of. 90 : * @param company_id Company ID to clear faults for. 91 : * 92 : * @return 0 on success, or (negative) error code otherwise. 93 : */ 94 1 : int (*fault_clear)(const struct bt_mesh_model *model, uint16_t company_id); 95 : 96 : /** @brief Run a self-test. 97 : * 98 : * The Health server may support up to 256 self-tests for each Company 99 : * ID. The behavior for all test IDs are vendor specific, and should be 100 : * interpreted based on the accompanying Company ID. Test failures 101 : * should result in changes to the fault array. 102 : * 103 : * @param model Health Server model instance to run test for. 104 : * @param test_id Test ID to run. 105 : * @param company_id Company ID to run test for. 106 : * 107 : * @return 0 if the test execution was started successfully, or 108 : * (negative) error code otherwise. Note that the fault array will not 109 : * be reported back to the client if the test execution didn't start. 110 : */ 111 1 : int (*fault_test)(const struct bt_mesh_model *model, uint8_t test_id, 112 : uint16_t company_id); 113 : 114 : /** @brief Start calling attention to the device. 115 : * 116 : * The attention state is used to map an element address to a 117 : * physical device. When this callback is called, the device should 118 : * start some physical procedure meant to call attention to itself, 119 : * like blinking, buzzing, vibrating or moving. If there are multiple 120 : * Health server instances on the device, the attention state should 121 : * also help identify the specific element the server is in. 122 : * 123 : * The attention calling behavior should continue until the @c attn_off 124 : * callback is called. 125 : * 126 : * @param model Health Server model to start the attention state of. 127 : */ 128 1 : void (*attn_on)(const struct bt_mesh_model *model); 129 : 130 : /** @brief Stop the attention state. 131 : * 132 : * Any physical activity started to call attention to the device should 133 : * be stopped. 134 : * 135 : * @param model 136 : */ 137 1 : void (*attn_off)(const struct bt_mesh_model *model); 138 : }; 139 : 140 : /** 141 : * A helper to define a health publication context 142 : * 143 : * @param _name Name given to the publication context variable. 144 : * @param _max_faults Maximum number of faults the element can have. 145 : */ 146 1 : #define BT_MESH_HEALTH_PUB_DEFINE(_name, _max_faults) \ 147 : BT_MESH_MODEL_PUB_DEFINE(_name, NULL, (1 + 3 + (_max_faults))) 148 : 149 : /** Mesh Health Server Model Context */ 150 1 : struct bt_mesh_health_srv { 151 : /** Composition data model entry pointer. */ 152 1 : const struct bt_mesh_model *model; 153 : 154 : /** Optional callback struct */ 155 1 : const struct bt_mesh_health_srv_cb *cb; 156 : 157 : /** Attention Timer state */ 158 1 : struct k_work_delayable attn_timer; 159 : }; 160 : 161 : /** 162 : * Define a new health server model. Note that this API needs to be 163 : * repeated for each element that the application wants to have a 164 : * health server model on. Each instance also needs a unique 165 : * bt_mesh_health_srv and bt_mesh_model_pub context. 166 : * 167 : * @param srv Pointer to a unique struct bt_mesh_health_srv. 168 : * @param pub Pointer to a unique struct bt_mesh_model_pub. 169 : * @param ... Optional Health Server metadata if application is compiled with 170 : * Large Composition Data Server support, otherwise this parameter 171 : * is ignored. 172 : * 173 : * @return New mesh model instance. 174 : */ 175 1 : #define BT_MESH_MODEL_HEALTH_SRV(srv, pub, ...) \ 176 : BT_MESH_MODEL_METADATA_CB(BT_MESH_MODEL_ID_HEALTH_SRV, \ 177 : bt_mesh_health_srv_op, \ 178 : pub, \ 179 : srv, \ 180 : &bt_mesh_health_srv_cb, __VA_ARGS__) 181 : 182 : /** 183 : * 184 : * Health Test Information Metadata ID. 185 : */ 186 1 : #define BT_MESH_HEALTH_TEST_INFO_METADATA_ID 0x0000 187 : 188 0 : #define BT_MESH_HEALTH_TEST_INFO_METADATA(tests) \ 189 : { \ 190 : .len = ARRAY_SIZE(tests), \ 191 : .id = BT_MESH_HEALTH_TEST_INFO_METADATA_ID, \ 192 : .data = tests, \ 193 : } 194 : 195 : /** 196 : * 197 : * Define a Health Test Info Metadata array. 198 : * 199 : * @param cid Company ID of the Health Test suite. 200 : * @param tests A comma separated list of tests. 201 : * 202 : * @return A comma separated list of values that make Health Test Info Metadata 203 : */ 204 1 : #define BT_MESH_HEALTH_TEST_INFO(cid, tests...) \ 205 : BT_BYTES_LIST_LE16(cid), sizeof((uint8_t[]){ tests }), tests 206 : 207 : /** @brief Notify the stack that the fault array state of the given element has 208 : * changed. 209 : * 210 : * This prompts the Health server on this element to publish the current fault 211 : * array if periodic publishing is disabled. 212 : * 213 : * @param elem Element to update the fault state of. 214 : * 215 : * @return 0 on success, or (negative) error code otherwise. 216 : */ 217 1 : int bt_mesh_health_srv_fault_update(const struct bt_mesh_elem *elem); 218 : 219 : /** @cond INTERNAL_HIDDEN */ 220 : extern const struct bt_mesh_model_op bt_mesh_health_srv_op[]; 221 : extern const struct bt_mesh_model_cb bt_mesh_health_srv_cb; 222 : /** @endcond */ 223 : 224 : #ifdef __cplusplus 225 : } 226 : #endif 227 : 228 : /** 229 : * @} 230 : */ 231 : 232 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEALTH_SRV_H_ */
