xref: /btstack/src/mesh/mesh_network.h (revision e3bfb018e72c155adee7983e0fe5872c864f4f24)
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_NETWORK
39 #define __MESH_NETWORK
40 
41 #include "btstack_linked_list.h"
42 #include "btstack_run_loop.h"
43 
44 #include "mesh/provisioning.h"
45 #include "mesh/mesh_keys.h"
46 
47 #if defined __cplusplus
48 extern "C" {
49 #endif
50 
51 #define MESH_DEVICE_KEY_INDEX     0xffff
52 
53 #define MESH_NETWORK_PAYLOAD_MAX      29
54 #define MESH_ACCESS_PAYLOAD_MAX      384
55 
56 #define MESH_ADDRESS_UNSASSIGNED     0x0000u
57 #define MESH_ADDRESS_ALL_PROXIES     0xFFFCu
58 #define MESH_ADDRESS_ALL_FRIENDS     0xFFFDu
59 #define MESH_ADDRESS_ALL_RELAYS      0xFFFEu
60 #define MESH_ADDRESS_ALL_NODES       0xFFFFu
61 
62 typedef enum {
63     MESH_NETWORK_PDU_RECEIVED,
64     MESH_NETWORK_PDU_SENT,
65     MESH_NETWORK_PDU_ENCRYPTED,
66     MESH_NETWORK_CAN_SEND_NOW,
67 } mesh_network_callback_type_t;
68 
69 typedef enum {
70     MESH_PDU_TYPE_NETWORK = 0,
71     MESH_PDU_TYPE_TRANSPORT,
72     MESH_PDU_TYPE_MESSAGE,
73     MESH_PDU_TYPE_UNSEGMENTED_INCOMING,
74 } mesh_pdu_type_t;
75 
76 typedef struct mesh_pdu {
77     // allow for linked lists
78     btstack_linked_item_t item;
79     // type
80     mesh_pdu_type_t pdu_type;
81 
82 } mesh_pdu_t;
83 
84 //
85 #define MESH_NETWORK_PDU_FLAGS_PROXY_CONFIGURATION 1
86 #define MESH_NETWORK_PDU_FLAGS_GATT_BEARER         2
87 #define MESH_NETWORK_PDU_FLAGS_RELAY               4
88 
89 typedef struct mesh_network_pdu {
90     mesh_pdu_t pdu_header;
91 
92     // meta data network layer
93     uint16_t              netkey_index;
94     // MESH_NETWORK_PDU_FLAGS
95     uint16_t              flags;
96 
97     // pdu
98     uint16_t              len;
99     uint8_t               data[MESH_NETWORK_PAYLOAD_MAX];
100 } mesh_network_pdu_t;
101 
102 #define MESH_TRANSPORT_FLAG_SEQ_RESERVED    1
103 #define MESH_TRANSPORT_FLAG_SEGMENTED       2
104 
105 typedef struct {
106     mesh_pdu_t pdu_header;
107 
108     // access acknowledged message
109     uint16_t retransmit_count;
110     uint32_t retransmit_timeout_ms;
111     uint32_t ack_opcode;
112 
113     // rx/tx: acknowledgement timer / segment transmission timer
114     btstack_timer_source_t acknowledgement_timer;
115     // rx: incomplete timer / tx: resend timer
116     btstack_timer_source_t incomplete_timer;
117     // block access
118     uint32_t              block_ack;
119     // meta data network layer
120     uint16_t              netkey_index;
121     // meta data transport layer
122     uint16_t              appkey_index;
123     // transmic size
124     uint8_t               transmic_len;
125     // akf - aid for access, opcode for control
126     uint8_t               akf_aid_control;
127     // network pdu header
128     uint8_t               network_header[9];
129     // MESH_TRANSPORT_FLAG
130     uint16_t              flags;
131     // acknowledgement timer active
132     uint8_t               acknowledgement_timer_active;
133     // incomplete timer active
134     uint8_t               incomplete_timer_active;
135     // message complete
136     uint8_t               message_complete;
137     // seq_zero for segmented messages
138     uint16_t              seq_zero;
139     // pdu
140     uint16_t              len;
141     uint8_t               data[MESH_ACCESS_PAYLOAD_MAX];
142 } mesh_transport_pdu_t;
143 
144 typedef struct {
145     mesh_pdu_t pdu_header;
146 
147     // access acknowledged message
148     uint16_t retransmit_count;
149     uint32_t retransmit_timeout_ms;
150     uint32_t ack_opcode;
151 
152     // rx/tx: acknowledgement timer / segment transmission timer
153     btstack_timer_source_t acknowledgement_timer;
154     // rx: incomplete timer / tx: resend timer
155     btstack_timer_source_t incomplete_timer;
156     // block access
157     uint32_t              block_ack;
158     // meta data network layer
159     uint16_t              netkey_index;
160     // meta data transport layer
161     uint16_t              appkey_index;
162     // transmic size
163     uint8_t               transmic_len;
164     // akf - aid for access, opcode for control
165     uint8_t               akf_aid_control;
166     // network pdu header
167     uint8_t               network_header[9];
168     // MESH_TRANSPORT_FLAG
169     uint16_t              flags;
170     // acknowledgement timer active
171     uint8_t               acknowledgement_timer_active;
172     // incomplete timer active
173     uint8_t               incomplete_timer_active;
174     // message complete
175     uint8_t               message_complete;
176     // seq_zero for segmented messages
177     uint16_t              seq_zero;
178     // pdu segments
179     uint16_t              len;
180     btstack_linked_list_t segments;
181 } mesh_message_pdu_t;
182 
183 typedef struct {
184     // generic pdu header
185     mesh_pdu_t            pdu_header;
186     // meta data transport layer
187     uint16_t              appkey_index;
188     // MESH_TRANSPORT_FLAG
189     uint16_t              flags;
190     // pdu segments
191     uint16_t              len;
192     btstack_linked_list_t segments;
193 } mesh_unsegmented_incoming_pdu_t;
194 
195 typedef enum {
196     MESH_KEY_REFRESH_NOT_ACTIVE = 0,
197     MESH_KEY_REFRESH_FIRST_PHASE,
198     MESH_KEY_REFRESH_SECOND_PHASE
199 } mesh_key_refresh_state_t;
200 
201 typedef enum {
202     MESH_SECURE_NETWORK_BEACON_W2_AUTH_VALUE,
203     MESH_SECURE_NETWORK_BEACON_W4_AUTH_VALUE,
204     MESH_SECURE_NETWORK_BEACON_AUTH_VALUE,
205     MESH_SECURE_NETWORK_BEACON_W2_SEND_ADV,
206     MESH_SECURE_NETWORK_BEACON_ADV_SENT,
207     MESH_SECURE_NETWORK_BEACON_W2_SEND_GATT,
208     MESH_SECURE_NETWORK_BEACON_GATT_SENT,
209     MESH_SECURE_NETWORK_BEACON_W4_INTERVAL
210 } mesh_secure_network_beacon_state_t;
211 
212 typedef struct {
213     btstack_linked_item_t item;
214 
215     // netkey index
216     uint16_t              netkey_index;
217 
218     // current / old key
219     mesh_network_key_t * old_key;
220 
221     // new key (only set during key refresh)
222     mesh_network_key_t * new_key;
223 
224     // key refresh state
225     mesh_key_refresh_state_t key_refresh;
226 
227     // advertisement using node id active
228     uint8_t node_id_advertisement_running;
229 
230 
231     // advertisement using network id (used by proxy)
232     adv_bearer_connectable_advertisement_data_item_t advertisement_with_network_id;
233 
234     // advertising using node id (used by proxy)
235     adv_bearer_connectable_advertisement_data_item_t advertisement_with_node_id;
236 
237     // secure network beacons
238     mesh_secure_network_beacon_state_t beacon_state;
239     uint32_t                           beacon_interval_ms;
240     uint32_t                           beacon_observation_start_ms;
241     uint16_t                           beacon_observation_counter;
242 
243 } mesh_subnet_t;
244 
245 typedef struct {
246     btstack_linked_list_iterator_t it;
247 } mesh_subnet_iterator_t;
248 
249 /**
250  * @brief Init Mesh Network Layer
251  */
252 void mesh_network_init(void);
253 
254 /**
255  * @brief Set higher layer Network PDU handler
256  * @param packet_handler
257  */
258 void mesh_network_set_higher_layer_handler(void (*packet_handler)(mesh_network_callback_type_t callback_type, mesh_network_pdu_t * network_pdu));
259 
260 /**
261  * @brief Set higher layer Proxy PDU handler
262  * @param packet_handler
263  */
264 void mesh_network_set_proxy_message_handler(void (*packet_handler)(mesh_network_callback_type_t callback_type, mesh_network_pdu_t * network_pdu));
265 
266 /**
267  * @brief Mark packet as processed
268  * @param newtork_pdu received via call packet_handler
269  */
270 void mesh_network_message_processed_by_higher_layer(mesh_network_pdu_t * network_pdu);
271 
272 /**
273  * @brief Send network_pdu after encryption
274  * @param network_pdu
275  */
276 void mesh_network_send_pdu(mesh_network_pdu_t * network_pdu);
277 
278 /*
279  * @brief Setup network pdu header
280  * @param netkey_index
281  * @param nid
282  * @param ctl
283  * @param ttl
284  * @param seq
285  * @param dst
286  * @param transport_pdu_data
287  * @param transport_pdu_len
288  */
289 void mesh_network_setup_pdu(mesh_network_pdu_t * network_pdu, uint16_t netkey_index, uint8_t nid, uint8_t ctl, uint8_t ttl, uint32_t seq, uint16_t src, uint16_t dst, const uint8_t * transport_pdu_data, uint8_t transport_pdu_len);
290 
291 /**
292  * Setup network pdu header without modifying len or payload
293  * @param network_pdu
294  * @param netkey_index
295  * @param nid
296  * @param ctl
297  * @param ttl
298  * @param seq
299  * @param src
300  * @param dest
301  */
302 void mesh_network_setup_pdu_header(mesh_network_pdu_t * network_pdu, uint16_t netkey_index, uint8_t nid, uint8_t ctl, uint8_t ttl, uint32_t seq, uint16_t src, uint16_t dest);
303 
304 /**
305  * @brief Validate network addresses
306  * @param ctl
307  * @param src
308  * @param dst
309  * @returns 1 if valid,
310  */
311 int mesh_network_addresses_valid(uint8_t ctl, uint16_t src, uint16_t dst);
312 
313 /**
314  * @brief Check if Unicast address
315  * @param addr
316  * @returns 1 if unicast
317  */
318 int mesh_network_address_unicast(uint16_t addr);
319 
320 /**
321  * @brief Check if Unicast address
322  * @param addr
323  * @returns 1 if unicast
324  */
325 int mesh_network_address_group(uint16_t addr);
326 
327 /**
328  * @brief Check if All Proxies address
329  * @param addr
330  * @returns 1 if all proxies
331  */
332 int mesh_network_address_all_proxies(uint16_t addr);
333 
334 /**
335  * @brief Check if All Nodes address
336  * @param addr
337  * @returns 1 if all nodes
338  */
339 int mesh_network_address_all_nodes(uint16_t addr);
340 
341 /**
342  * @brief Check if All Friends address
343  * @param addr
344  * @returns 1 if all friends
345  */
346 int mesh_network_address_all_friends(uint16_t addr);
347 
348 /**
349  * @brief Check if All Relays address
350  * @param addr
351  * @returns 1 if all relays
352  */
353 int mesh_network_address_all_relays(uint16_t addr);
354 
355 
356 /**
357  * @brief Check if Virtual address
358  * @param addr
359  * @returns 1 if virtual
360  */
361 int mesh_network_address_virtual(uint16_t addr);
362 
363 
364 /**
365  * @brief Add subnet to list
366  * @param subnet
367  */
368 void mesh_subnet_add(mesh_subnet_t * subnet);
369 
370 /**
371  * @brief Remove subnet from list
372  * @param subnet
373  */
374 void mesh_subnet_remove(mesh_subnet_t * subnet);
375 
376 /**
377  * @brief Get subnet for netkey_index
378  * @param netkey_index
379  * @returns mesh_subnet_t or NULL
380  */
381 mesh_subnet_t * mesh_subnet_get_by_netkey_index(uint16_t netkey_index);
382 
383 /**
384  * @brief Get number of stored subnets
385  * @returns count
386  */
387 int mesh_subnet_list_count(void);
388 
389 /**
390  * @brief Iterate over all subnets
391  * @param it
392  */
393 void mesh_subnet_iterator_init(mesh_subnet_iterator_t *it);
394 
395 /**
396  * @brief Check if another subnet is available
397  * @param it
398  * @return
399  */
400 int mesh_subnet_iterator_has_more(mesh_subnet_iterator_t *it);
401 
402 /**
403  * @brief Get next subnet
404  * @param it
405  * @return
406  */
407 mesh_subnet_t * mesh_subnet_iterator_get_next(mesh_subnet_iterator_t *it);
408 
409 /**
410  * @brief Setup subnet for given netkey index
411  */
412 void mesh_subnet_setup_for_netkey_index(uint16_t netkey_index);
413 
414 
415 /**
416  * @brief Get outgoing network key for subnet based on key refresh phase
417  */
418 mesh_network_key_t * mesh_subnet_get_outgoing_network_key(mesh_subnet_t * subnet);
419 
420 // buffer pool
421 mesh_network_pdu_t * mesh_network_pdu_get(void);
422 void mesh_network_pdu_free(mesh_network_pdu_t * network_pdu);
423 
424 // Mesh Network PDU Getter
425 uint16_t  mesh_network_control(mesh_network_pdu_t * network_pdu);
426 uint8_t   mesh_network_nid(mesh_network_pdu_t * network_pdu);
427 uint8_t   mesh_network_ttl(mesh_network_pdu_t * network_pdu);
428 uint32_t  mesh_network_seq(mesh_network_pdu_t * network_pdu);
429 uint16_t  mesh_network_src(mesh_network_pdu_t * network_pdu);
430 uint16_t  mesh_network_dst(mesh_network_pdu_t * network_pdu);
431 int       mesh_network_segmented(mesh_network_pdu_t * network_pdu);
432 uint8_t   mesh_network_control_opcode(mesh_network_pdu_t * network_pdu);
433 uint8_t * mesh_network_pdu_data(mesh_network_pdu_t * network_pdu);
434 uint8_t   mesh_network_pdu_len(mesh_network_pdu_t * network_pdu);
435 
436 // Mesh Network PDU Setter
437 void mesh_network_pdu_set_seq(mesh_network_pdu_t * network_pdu, uint32_t seq);
438 
439 // Testing only
440 void mesh_network_received_message(const uint8_t * pdu_data, uint8_t pdu_len, uint8_t flags);
441 void mesh_network_process_proxy_configuration_message(const uint8_t * pdu_data, uint8_t pdu_len);
442 void mesh_network_encrypt_proxy_configuration_message(mesh_network_pdu_t * network_pdu);
443 void mesh_network_dump(void);
444 void mesh_network_reset(void);
445 
446 #if defined __cplusplus
447 }
448 #endif
449 
450 #endif
451