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