1 /* 2 * Copyright (C) 2018 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS 24 * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 #ifndef __MESH_ACCESS_H 39 #define __MESH_ACCESS_H 40 41 #include <stdint.h> 42 #include <stdarg.h> 43 44 #include "bluetooth_company_id.h" 45 #include "btstack_linked_list.h" 46 47 #include "mesh/mesh_lower_transport.h" 48 #include "mesh/mesh_keys.h" 49 #include "mesh/mesh_node.h" 50 51 #ifdef __cplusplus 52 extern "C" 53 { 54 #endif 55 56 #define MAX_NR_MESH_APPKEYS_PER_MODEL 3u 57 #define MAX_NR_MESH_SUBSCRIPTION_PER_MODEL 3u 58 59 #define MESH_APPKEY_INVALID 0xffffu 60 61 struct mesh_model; 62 struct mesh_element; 63 64 // function to handle model operation message 65 typedef void (*mesh_operation_handler)(struct mesh_model * mesh_model, mesh_pdu_t * pdu); 66 67 // function to publish the current state of a model 68 // @param mesh_model to publish 69 // @returns mesh_pdu with status message 70 typedef mesh_pdu_t * (*mesh_publish_state_t)(struct mesh_model * mesh_model); 71 72 typedef enum { 73 MESH_DEFAULT_TRANSITION_STEP_RESOLUTION_100ms = 0x00u, 74 MESH_DEFAULT_TRANSITION_STEP_RESOLUTION_1s, 75 MESH_DEFAULT_TRANSITION_STEP_RESOLUTION_10s, 76 MESH_DEFAULT_TRANSITION_STEP_RESOLUTION_10min 77 } mesh_default_transition_step_resolution_t; 78 79 typedef enum { 80 MODEL_STATE_UPDATE_REASON_SET = 0x00u, 81 MODEL_STATE_UPDATE_REASON_TRANSITION_START, 82 // MODEL_STATE_UPDATE_REASON_TRANSITION_ACTIVE, 83 MODEL_STATE_UPDATE_REASON_TRANSITION_END, 84 MODEL_STATE_UPDATE_REASON_TRANSITION_ABORT, 85 // MODEL_STATE_UPDATE_REASON_BOUND_STATE, 86 MODEL_STATE_UPDATE_REASON_APPLICATION_CHANGE 87 } model_state_update_reason_t; 88 89 typedef enum { 90 TRANSITION_START, 91 TRANSITION_UPDATE 92 } transition_event_t; 93 94 typedef enum { 95 MESH_TRANSITION_STATE_IDLE, 96 MESH_TRANSITION_STATE_DELAYED, 97 MESH_TRANSITION_STATE_ACTIVE 98 } mesh_transition_state_t; 99 100 typedef enum { 101 MODEL_STATE_ID_GENERIC_ON_OFF = (BLUETOOTH_COMPANY_ID_BLUETOOTH_SIG_INC << 16) | 0u, 102 MODEL_STATE_ID_GENERIC_LEVEL = (BLUETOOTH_COMPANY_ID_BLUETOOTH_SIG_INC << 16) | 1u, 103 } model_state_id_t; 104 105 typedef enum { 106 MESH_MODEL_PUBLICATION_STATE_IDLE, 107 MESH_MODEL_PUBLICATION_STATE_W4_PUBLICATION_MS, 108 MESH_MODEL_PUBLICATION_STATE_W4_RETRANSMIT_MS, 109 } mesh_model_publication_state_t; 110 111 typedef struct { 112 mesh_publish_state_t publish_state_fn; 113 mesh_model_publication_state_t state; 114 uint32_t next_publication_ms; 115 uint32_t next_retransmit_ms; 116 uint8_t retransmit_count; 117 uint8_t publish_now; 118 119 uint16_t address; 120 uint16_t appkey_index; 121 uint8_t friendship_credential_flag; 122 uint8_t period; 123 uint8_t ttl; 124 uint8_t retransmit; 125 } mesh_publication_model_t; 126 127 128 typedef struct { 129 uint32_t opcode; 130 uint16_t minimum_length; 131 mesh_operation_handler handler; 132 } mesh_operation_t; 133 134 typedef struct mesh_model { 135 // linked list item 136 btstack_linked_item_t item; 137 138 // element 139 struct mesh_element * element; 140 141 // internal model enumeration 142 uint16_t mid; 143 144 // vendor_id << 16 | model id, use BLUETOOTH_COMPANY_ID_BLUETOOTH_SIG_INC for SIG models 145 uint32_t model_identifier; 146 147 // model operations 148 const mesh_operation_t * operations; 149 150 // publication model if supported 151 mesh_publication_model_t * publication_model; 152 153 // data 154 void * model_data; 155 156 // bound appkeys 157 uint16_t appkey_indices[MAX_NR_MESH_APPKEYS_PER_MODEL]; 158 159 // subscription list 160 uint16_t subscriptions[MAX_NR_MESH_SUBSCRIPTION_PER_MODEL]; 161 162 // packet handler for transition events in server, event callback handler in client 163 btstack_packet_handler_t * model_packet_handler; 164 } mesh_model_t; 165 166 typedef struct { 167 btstack_linked_list_iterator_t it; 168 } mesh_model_iterator_t; 169 170 #define MESH_MAX_NUM_FAULTS 3 171 172 typedef struct { 173 // linked list item 174 btstack_linked_item_t item; 175 uint8_t test_id; 176 uint16_t company_id; 177 uint16_t num_faults; 178 uint8_t faults[MESH_MAX_NUM_FAULTS]; 179 } mesh_fault_t; 180 181 typedef struct { 182 uint32_t opcode; 183 uint8_t * data; 184 uint16_t len; 185 } mesh_access_parser_state_t; 186 187 typedef struct { 188 uint32_t opcode; 189 const char * format; 190 } mesh_access_message_t; 191 192 typedef enum { 193 MESH_TRANSACTION_STATUS_NEW = 0, 194 MESH_TRANSACTION_STATUS_RETRANSMISSION, 195 MESH_TRANSACTION_STATUS_DIFFERENT_DST_OR_SRC 196 } mesh_transaction_status_t; 197 198 typedef struct mesh_transition { 199 btstack_linked_item_t item; 200 201 mesh_transition_state_t state; 202 203 uint8_t transaction_identifier; 204 uint32_t transaction_timestamp_ms; 205 uint16_t src_address; 206 uint16_t dst_address; 207 208 mesh_default_transition_step_resolution_t step_duration_ms; 209 uint32_t phase_start_ms; 210 uint32_t remaining_delay_time_ms; 211 uint32_t remaining_transition_time_ms; 212 // to send events and/or publish changes 213 mesh_model_t * mesh_model; 214 215 // to execute transition 216 void (* transition_callback)(struct mesh_transition * transition, transition_event_t event, uint32_t current_timestamp); 217 } mesh_transition_t; 218 219 /** 220 * @brief Init access layer 221 */ 222 void mesh_access_init(void); 223 224 /** 225 * @brief Inform access layer that access message was processed by higher layer 226 * @param pdu 227 */ 228 void mesh_access_message_processed(mesh_pdu_t * pdu); 229 230 /** 231 * @brief Get number of retransmissions used by default 232 */ 233 uint8_t mesh_access_acknowledged_message_retransmissions(void); 234 235 /** 236 * @brief Get retransmission timeout 237 */ 238 uint32_t mesh_access_acknowledged_message_timeout_ms(void); 239 240 /** 241 * @brief Send unacknowledged message 242 * @param pdu 243 */ 244 void mesh_access_send_unacknowledged_pdu(mesh_pdu_t * pdu); 245 246 /** 247 * @brief Send acknowledged message. Retransmits message if no acknowledgement with expected opcode is received 248 * @param pdu 249 * @param retransmissions 250 * @param ack_opcode opcode of acknowledgement 251 */ 252 void mesh_access_send_acknowledged_pdu(mesh_pdu_t * pdu, uint8_t retransmissions, uint32_t ack_opcode); 253 254 /** 255 * @brief Get element index for give model 256 * @param mesh_model 257 */ 258 uint8_t mesh_access_get_element_index(mesh_model_t * mesh_model); 259 260 /** 261 * @brief Get unicast address for give model 262 * @param mesh_model 263 */ 264 uint16_t mesh_access_get_element_address(mesh_model_t * mesh_model); 265 266 /** 267 * @brief Add model to element 268 * @param element 269 * @param mesh_model 270 */ 271 void mesh_element_add_model(mesh_element_t * element, mesh_model_t * mesh_model); 272 273 // Mesh Model Iterator 274 275 void mesh_model_iterator_init(mesh_model_iterator_t * iterator, mesh_element_t * element); 276 277 int mesh_model_iterator_has_next(mesh_model_iterator_t * iterator); 278 279 mesh_model_t * mesh_model_iterator_next(mesh_model_iterator_t * iterator); 280 281 // Mesh Model Utility 282 283 mesh_model_t * mesh_model_get_by_identifier(mesh_element_t * element, uint32_t model_identifier); 284 285 uint32_t mesh_model_get_model_identifier_bluetooth_sig(uint16_t model_id); 286 287 int mesh_model_is_bluetooth_sig(uint32_t model_identifier); 288 289 uint16_t mesh_model_get_model_id(uint32_t model_identifier); 290 291 uint32_t mesh_model_get_model_identifier(uint16_t vendor_id, uint16_t model_id); 292 293 mesh_model_t * mesh_model_get_configuration_server(void); 294 295 mesh_model_t * mesh_access_model_for_address_and_model_identifier(uint16_t element_address, uint32_t model_identifier, uint8_t * status); 296 297 uint8_t mesh_access_transitions_num_steps_from_gdtt(uint8_t time_gdtt); 298 uint32_t mesh_access_time_gdtt2ms(uint8_t time_gdtt); 299 300 void mesh_access_emit_state_update_bool(btstack_packet_handler_t * event_handler, uint8_t element_index, uint32_t model_identifier, 301 model_state_id_t state_identifier, model_state_update_reason_t reason, uint8_t value); 302 void mesh_access_emit_state_update_int16(btstack_packet_handler_t * event_handler, uint8_t element_index, uint32_t model_identifier, 303 model_state_id_t state_identifier, model_state_update_reason_t reason, int16_t value); 304 305 // Mesh Model Transitions 306 void mesh_access_transitions_setup_transaction(mesh_transition_t * transition, uint8_t transaction_identifier, uint16_t src_address, uint16_t dst_address); 307 void mesh_access_transitions_abort_transaction(mesh_transition_t * transition); 308 mesh_transaction_status_t mesh_access_transitions_transaction_status(mesh_transition_t * transition, uint8_t transaction_identifier, uint16_t src_address, uint16_t dst_address); 309 310 void mesh_access_transitions_setup(mesh_transition_t * transition, mesh_model_t * mesh_model, 311 uint8_t transition_time_gdtt, uint8_t delay_gdtt, 312 void (* transition_callback)(struct mesh_transition * transition, transition_event_t event, uint32_t current_timestamp)); 313 314 void mesh_access_transitions_add(mesh_transition_t * transition); 315 void mesh_access_transitions_remove(mesh_transition_t * transition); 316 uint8_t mesh_access_transactions_get_next_transaction_id(void); 317 318 // Key Refresh 319 void mesh_access_key_refresh_revoke_keys(mesh_subnet_t * subnet); 320 321 // Mesh Model Publicaation 322 323 /** 324 * Inform Mesh Access that the state of a model has changed. may trigger state publication 325 * @param mesh_model 326 */ 327 void mesh_access_state_changed(mesh_model_t * mesh_model); 328 329 /** 330 * Start Model Publication 331 * @param mesh_model 332 */ 333 void mesh_model_publication_start(mesh_model_t * mesh_model); 334 335 /** 336 * Stop Model Publication 337 * @param mesh_model 338 */ 339 void mesh_model_publication_stop(mesh_model_t * mesh_model); 340 341 // Mesh PDU Getter 342 uint16_t mesh_pdu_src(mesh_pdu_t * pdu); 343 uint16_t mesh_pdu_dst(mesh_pdu_t * pdu); 344 uint16_t mesh_pdu_netkey_index(mesh_pdu_t * pdu); 345 uint16_t mesh_pdu_appkey_index(mesh_pdu_t * pdu); 346 uint16_t mesh_pdu_len(mesh_pdu_t * pdu); 347 uint8_t * mesh_pdu_data(mesh_pdu_t * pdu); 348 349 // Mesh NetKey List 350 void mesh_store_network_key(mesh_network_key_t * network_key); 351 void mesh_delete_network_key(uint16_t internal_index); 352 void mesh_delete_network_keys(void); 353 void mesh_load_network_keys(void); 354 355 void mesh_access_netkey_finalize(mesh_network_key_t * network_key); 356 357 // Mesh Appkeys 358 void mesh_store_app_key(mesh_transport_key_t * app_key); 359 void mesh_delete_app_key(uint16_t internal_index); 360 void mesh_delete_app_keys(void); 361 void mesh_load_app_keys(void); 362 363 void mesh_access_appkey_finalize(mesh_transport_key_t * transport_key); 364 365 // Mesh Model Subscriptions 366 int mesh_model_contains_subscription(mesh_model_t * mesh_model, uint16_t address); 367 368 // Mesh Model to Appkey List 369 void mesh_load_appkey_lists(void); 370 void mesh_delete_appkey_lists(void); 371 void mesh_model_reset_appkeys(mesh_model_t * mesh_model); 372 uint8_t mesh_model_bind_appkey(mesh_model_t * mesh_model, uint16_t appkey_index); 373 void mesh_model_unbind_appkey(mesh_model_t * mesh_model, uint16_t appkey_index); 374 int mesh_model_contains_appkey(mesh_model_t * mesh_model, uint16_t appkey_index); 375 376 // Mesh IV Index and sequence number 377 void mesh_store_iv_index_after_provisioning(uint32_t iv_index); 378 void mesh_store_iv_index_and_sequence_number(void); 379 void mesh_restore_iv_index_and_sequence_number(void); 380 381 // Mesh Access Parser 382 int mesh_access_pdu_get_opcode(mesh_pdu_t * pdu, uint32_t * opcode, uint16_t * opcode_size); 383 int mesh_access_parser_init(mesh_access_parser_state_t * state, mesh_pdu_t * pdu); 384 void mesh_access_parser_skip(mesh_access_parser_state_t * state, uint16_t bytes_to_skip); 385 uint16_t mesh_access_parser_available(mesh_access_parser_state_t * state); 386 uint8_t mesh_access_parser_get_u8(mesh_access_parser_state_t * state); 387 uint16_t mesh_access_parser_get_u16(mesh_access_parser_state_t * state); 388 uint32_t mesh_access_parser_get_u24(mesh_access_parser_state_t * state); 389 uint32_t mesh_access_parser_get_u32(mesh_access_parser_state_t * state); 390 void mesh_access_parser_get_u128(mesh_access_parser_state_t * state, uint8_t * dest); 391 void mesh_access_parser_get_label_uuid(mesh_access_parser_state_t * state, uint8_t * dest); 392 void mesh_access_parser_get_key(mesh_access_parser_state_t * state, uint8_t * dest); 393 uint32_t mesh_access_parser_get_model_identifier(mesh_access_parser_state_t * parser); 394 395 // Foundation state 396 void mesh_foundation_state_load(void); 397 void mesh_foundation_state_store(void); 398 399 // message builder transport 400 mesh_transport_pdu_t * mesh_access_transport_init(uint32_t opcode); 401 void mesh_access_transport_add_uint8(mesh_transport_pdu_t * pdu, uint8_t value); 402 void mesh_access_transport_add_uint16(mesh_transport_pdu_t * pdu, uint16_t value); 403 void mesh_access_transport_add_uint24(mesh_transport_pdu_t * pdu, uint32_t value); 404 void mesh_access_transport_add_uint32(mesh_transport_pdu_t * pdu, uint32_t value); 405 void mesh_access_transport_add_model_identifier(mesh_transport_pdu_t * pdu, uint32_t model_identifier); 406 407 // message builder network 408 mesh_network_pdu_t * mesh_access_network_init(uint32_t opcode); 409 void mesh_access_network_add_uint8(mesh_network_pdu_t * pdu, uint8_t value); 410 void mesh_access_network_add_uint16(mesh_network_pdu_t * pdu, uint16_t value); 411 void mesh_access_network_add_uint24(mesh_network_pdu_t * pdu, uint16_t value); 412 void mesh_access_network_add_uint32(mesh_network_pdu_t * pdu, uint16_t value); 413 void mesh_access_network_add_model_identifier(mesh_network_pdu_t * pdu, uint32_t model_identifier); 414 415 // message builder using template 416 mesh_network_pdu_t * mesh_access_setup_unsegmented_message(const mesh_access_message_t *template, ...); 417 mesh_transport_pdu_t * mesh_access_setup_segmented_message(const mesh_access_message_t *template, ...); 418 419 // setup 420 void mesh_access_setup_from_provisioning_data(const mesh_provisioning_data_t * provisioning_data); 421 void mesh_access_setup_without_provisiong_data(void); 422 423 #ifdef __cplusplus 424 } /* end of extern "C" */ 425 #endif 426 427 #endif 428