xref: /btstack/src/mesh/mesh_network.h (revision bb588228dfe9304f77394ce1346265d38a29618b)
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_CAN_SEND_NOW,
66 } mesh_network_callback_type_t;
67 
68 typedef enum {
69     MESH_PDU_TYPE_NETWORK = 0,
70     MESH_PDU_TYPE_TRANSPORT,
71     MESH_PDU_TYPE_MESSAGE,
72 } mesh_pdu_type_t;
73 
74 typedef struct mesh_pdu {
75     // allow for linked lists
76     btstack_linked_item_t item;
77     // type
78     mesh_pdu_type_t pdu_type;
79 
80 } mesh_pdu_t;
81 
82 //
83 #define MESH_NETWORK_PDU_FLAGS_PROXY_CONFIGURATION 1
84 #define MESH_NETWORK_PDU_FLAGS_GATT_BEARER         2
85 #define MESH_NETWORK_PDU_FLAGS_RELAY               4
86 
87 typedef struct mesh_network_pdu {
88     mesh_pdu_t pdu_header;
89 
90     // callback
91     void (*callback)(struct mesh_network_pdu * network_pdu);
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 
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 enum {
184     MESH_KEY_REFRESH_NOT_ACTIVE = 0,
185     MESH_KEY_REFRESH_FIRST_PHASE,
186     MESH_KEY_REFRESH_SECOND_PHASE
187 } mesh_key_refresh_state_t;
188 
189 typedef enum {
190     MESH_SECURE_NETWORK_BEACON_W2_AUTH_VALUE,
191     MESH_SECURE_NETWORK_BEACON_W4_AUTH_VALUE,
192     MESH_SECURE_NETWORK_BEACON_AUTH_VALUE,
193     MESH_SECURE_NETWORK_BEACON_W2_SEND_ADV,
194     MESH_SECURE_NETWORK_BEACON_ADV_SENT,
195     MESH_SECURE_NETWORK_BEACON_W2_SEND_GATT,
196     MESH_SECURE_NETWORK_BEACON_GATT_SENT,
197     MESH_SECURE_NETWORK_BEACON_W4_INTERVAL
198 } mesh_secure_network_beacon_state_t;
199 
200 typedef struct {
201     btstack_linked_item_t item;
202 
203     // netkey index
204     uint16_t              netkey_index;
205 
206     // current / old key
207     mesh_network_key_t * old_key;
208 
209     // new key (only set during key refresh)
210     mesh_network_key_t * new_key;
211 
212     // key refresh state
213     mesh_key_refresh_state_t key_refresh;
214 
215     // advertisement using node id active
216     uint8_t node_id_advertisement_running;
217 
218 
219     // advertisement using network id (used by proxy)
220     adv_bearer_connectable_advertisement_data_item_t advertisement_with_network_id;
221 
222     // advertising using node id (used by proxy)
223     adv_bearer_connectable_advertisement_data_item_t advertisement_with_node_id;
224 
225     // secure network beacons
226     mesh_secure_network_beacon_state_t beacon_state;
227     uint32_t                           beacon_interval_ms;
228     uint32_t                           beacon_observation_start_ms;
229     uint16_t                           beacon_observation_counter;
230 
231 } mesh_subnet_t;
232 
233 typedef struct {
234     btstack_linked_list_iterator_t it;
235 } mesh_subnet_iterator_t;
236 
237 /**
238  * @brief Init Mesh Network Layer
239  */
240 void mesh_network_init(void);
241 
242 /**
243  * @brief Set higher layer Network PDU handler
244  * @param packet_handler
245  */
246 void mesh_network_set_higher_layer_handler(void (*packet_handler)(mesh_network_callback_type_t callback_type, mesh_network_pdu_t * network_pdu));
247 
248 /**
249  * @brief Set higher layer Proxy PDU handler
250  * @param packet_handler
251  */
252 void mesh_network_set_proxy_message_handler(void (*packet_handler)(mesh_network_callback_type_t callback_type, mesh_network_pdu_t * network_pdu));
253 
254 /**
255  * @brief Mark packet as processed
256  * @param newtork_pdu received via call packet_handler
257  */
258 void mesh_network_message_processed_by_higher_layer(mesh_network_pdu_t * network_pdu);
259 
260 /**
261  * @brief Send network_pdu after encryption
262  * @param network_pdu
263  */
264 void mesh_network_send_pdu(mesh_network_pdu_t * network_pdu);
265 
266 /*
267  * @brief Setup network pdu header
268  * @param netkey_index
269  * @param nid
270  * @param ctl
271  * @param ttl
272  * @param seq
273  * @param dst
274  * @param transport_pdu_data
275  * @param transport_pdu_len
276  */
277 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);
278 
279 /**
280  * Setup network pdu header without modifying len or payload
281  * @param network_pdu
282  * @param netkey_index
283  * @param nid
284  * @param ctl
285  * @param ttl
286  * @param seq
287  * @param src
288  * @param dest
289  */
290 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);
291 
292 /**
293  * @brief Validate network addresses
294  * @param ctl
295  * @param src
296  * @param dst
297  * @returns 1 if valid,
298  */
299 int mesh_network_addresses_valid(uint8_t ctl, uint16_t src, uint16_t dst);
300 
301 /**
302  * @brief Check if Unicast address
303  * @param addr
304  * @returns 1 if unicast
305  */
306 int mesh_network_address_unicast(uint16_t addr);
307 
308 /**
309  * @brief Check if Unicast address
310  * @param addr
311  * @returns 1 if unicast
312  */
313 int mesh_network_address_group(uint16_t addr);
314 
315 /**
316  * @brief Check if All Proxies address
317  * @param addr
318  * @returns 1 if all proxies
319  */
320 int mesh_network_address_all_proxies(uint16_t addr);
321 
322 /**
323  * @brief Check if All Nodes address
324  * @param addr
325  * @returns 1 if all nodes
326  */
327 int mesh_network_address_all_nodes(uint16_t addr);
328 
329 /**
330  * @brief Check if All Friends address
331  * @param addr
332  * @returns 1 if all friends
333  */
334 int mesh_network_address_all_friends(uint16_t addr);
335 
336 /**
337  * @brief Check if All Relays address
338  * @param addr
339  * @returns 1 if all relays
340  */
341 int mesh_network_address_all_relays(uint16_t addr);
342 
343 
344 /**
345  * @brief Check if Virtual address
346  * @param addr
347  * @returns 1 if virtual
348  */
349 int mesh_network_address_virtual(uint16_t addr);
350 
351 
352 /**
353  * @brief Add subnet to list
354  * @param subnet
355  */
356 void mesh_subnet_add(mesh_subnet_t * subnet);
357 
358 /**
359  * @brief Remove subnet from list
360  * @param subnet
361  */
362 void mesh_subnet_remove(mesh_subnet_t * subnet);
363 
364 /**
365  * @brief Get subnet for netkey_index
366  * @param netkey_index
367  * @returns mesh_subnet_t or NULL
368  */
369 mesh_subnet_t * mesh_subnet_get_by_netkey_index(uint16_t netkey_index);
370 
371 /**
372  * @brief Get number of stored subnets
373  * @returns count
374  */
375 int mesh_subnet_list_count(void);
376 
377 /**
378  * @brief Iterate over all subnets
379  * @param it
380  */
381 void mesh_subnet_iterator_init(mesh_subnet_iterator_t *it);
382 
383 /**
384  * @brief Check if another subnet is available
385  * @param it
386  * @return
387  */
388 int mesh_subnet_iterator_has_more(mesh_subnet_iterator_t *it);
389 
390 /**
391  * @brief Get next subnet
392  * @param it
393  * @return
394  */
395 mesh_subnet_t * mesh_subnet_iterator_get_next(mesh_subnet_iterator_t *it);
396 
397 /**
398  * @brief Setup subnet for given netkey index
399  */
400 void mesh_subnet_setup_for_netkey_index(uint16_t netkey_index);
401 
402 
403 /**
404  * @brief Get outgoing network key for subnet based on key refresh phase
405  */
406 mesh_network_key_t * mesh_subnet_get_outgoing_network_key(mesh_subnet_t * subnet);
407 
408 // buffer pool
409 mesh_network_pdu_t * mesh_network_pdu_get(void);
410 void mesh_network_pdu_free(mesh_network_pdu_t * network_pdu);
411 
412 // Mesh Network PDU Getter
413 uint16_t  mesh_network_control(mesh_network_pdu_t * network_pdu);
414 uint8_t   mesh_network_nid(mesh_network_pdu_t * network_pdu);
415 uint8_t   mesh_network_ttl(mesh_network_pdu_t * network_pdu);
416 uint32_t  mesh_network_seq(mesh_network_pdu_t * network_pdu);
417 uint16_t  mesh_network_src(mesh_network_pdu_t * network_pdu);
418 uint16_t  mesh_network_dst(mesh_network_pdu_t * network_pdu);
419 int       mesh_network_segmented(mesh_network_pdu_t * network_pdu);
420 uint8_t   mesh_network_control_opcode(mesh_network_pdu_t * network_pdu);
421 uint8_t * mesh_network_pdu_data(mesh_network_pdu_t * network_pdu);
422 uint8_t   mesh_network_pdu_len(mesh_network_pdu_t * network_pdu);
423 
424 // Mesh Network PDU Setter
425 void mesh_network_pdu_set_seq(mesh_network_pdu_t * network_pdu, uint32_t seq);
426 
427 // Testing only
428 void mesh_network_received_message(const uint8_t * pdu_data, uint8_t pdu_len, uint8_t flags);
429 void mesh_network_process_proxy_configuration_message(const uint8_t * pdu_data, uint8_t pdu_len);
430 void mesh_network_encrypt_proxy_configuration_message(mesh_network_pdu_t * network_pdu, void (* callback)(mesh_network_pdu_t * callback));
431 void mesh_network_dump(void);
432 void mesh_network_reset(void);
433 
434 #if defined __cplusplus
435 }
436 #endif
437 
438 #endif
439