nRF5 SDK for Mesh v5.0.0
nrf_mesh.h
1 /* Copyright (c) 2010 - 2020, Nordic Semiconductor ASA
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without modification,
5  * are permitted provided that the following conditions are met:
6  *
7  * 1. Redistributions of source code must retain the above copyright notice, this
8  * list of conditions and the following disclaimer.
9  *
10  * 2. Redistributions in binary form, except as embedded into a Nordic
11  * Semiconductor ASA integrated circuit in a product or a software update for
12  * such product, must reproduce the above copyright notice, this list of
13  * conditions and the following disclaimer in the documentation and/or other
14  * materials provided with the distribution.
15  *
16  * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
17  * contributors may be used to endorse or promote products derived from this
18  * software without specific prior written permission.
19  *
20  * 4. This software, with or without modification, must only be used with a
21  * Nordic Semiconductor ASA integrated circuit.
22  *
23  * 5. Any software provided in binary form under this license must not be reverse
24  * engineered, decompiled, modified and/or disassembled.
25  *
26  * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
27  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28  * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
29  * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
30  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
32  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
35  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36  */
37 
38 #ifndef NRF_MESH_H__
39 #define NRF_MESH_H__
40 
41 #include <stdint.h>
42 #include <stdbool.h>
43 
44 #include "timer.h"
45 
46 #include "ble.h"
47 #include "ble_gap.h"
48 
49 #include "nrf_mesh_defines.h"
50 #include "nrf_mesh_config_core.h"
51 
52 #include "nrf.h"
53 #include "nrf_sdm.h"
54 
63 #define NRF_MESH_INITIAL_TOKEN 0x00000000ul
64 
65 #define NRF_MESH_SERVICE_BORDER_TOKEN 0xF0000000ul
66 
73 #define NRF_MESH_FRIEND_TOKEN_BEGIN 0xFFFFFE00ul
74 
75 #define NRF_MESH_FRIEND_TOKEN_END 0xFFFFFEFFul
76 
77 #define NRF_MESH_FRIEND_POLL_TOKEN 0xFFFFFFF8ul
78 #define NRF_MESH_FRIEND_REQUEST_TOKEN 0xFFFFFFF9ul
79 #define NRF_MESH_FRIEND_CLEAR_TOKEN 0xFFFFFFFAul
80 #define NRF_MESH_SUBMAN_ADD_TOKEN 0xFFFFFFFBul
81 #define NRF_MESH_SUBMAN_REMOVE_TOKEN 0xFFFFFFFCul
82 #define NRF_MESH_HEARTBEAT_TOKEN 0xFFFFFFFDul
83 #define NRF_MESH_SAR_TOKEN 0xFFFFFFFEul
84 #define NRF_MESH_RELAY_TOKEN 0xFFFFFFFFul
85 
102 typedef void (*nrf_mesh_assertion_handler_t)(uint32_t pc);
103 
105 typedef uint32_t nrf_mesh_tx_token_t;
106 
108 typedef enum
109 {
115 
117 typedef struct
118 {
119  timestamp_t timestamp;
120  uint32_t access_addr;
121  uint8_t channel;
122  int8_t rssi;
123  ble_gap_addr_t adv_addr;
124  uint8_t adv_type;
126 
128 typedef struct
129 {
130  uint16_t data_id;
131  uint8_t set_id;
133 
135 typedef struct
136 {
137  timestamp_t timestamp;
138  uint8_t channel;
139  int8_t rssi;
140  struct
141  {
143  uint8_t packet_index;
145  } event;
147 
148 typedef struct
149 {
150  timestamp_t timestamp;
151  uint16_t connection_index;
153 
155 typedef struct
156 {
159 
161 typedef struct
162 {
164  union
165  {
174  } params;
176 
198 typedef bool (*nrf_mesh_relay_check_cb_t)(uint16_t src, uint16_t dst, uint8_t ttl);
199 
201 typedef struct
202 {
203  uint8_t adv_type;
204  uint8_t length;
205  const uint8_t * p_payload;
208 
218 typedef void (*nrf_mesh_rx_cb_t)(const nrf_mesh_adv_packet_rx_data_t * p_rx_data);
219 
225 typedef enum
226 {
236 
245 typedef struct
246 {
250  uint8_t aid;
252  uint8_t key[NRF_MESH_KEY_SIZE];
254 
261 typedef struct
262 {
264  uint8_t nid;
266  uint8_t encryption_key[NRF_MESH_KEY_SIZE];
268  uint8_t privacy_key[NRF_MESH_KEY_SIZE];
270 
278 typedef struct
279 {
281  uint8_t key[NRF_MESH_KEY_SIZE];
283  uint8_t net_id[NRF_MESH_NETID_SIZE];
284 #if MESH_FEATURE_GATT_PROXY_ENABLED
285 
286  uint8_t identity_key[NRF_MESH_KEY_SIZE];
287 #endif
289 
294 typedef struct
295 {
297  uint16_t rx_count;
301  uint16_t interval;
303  timestamp_t tx_timestamp;
305 
311 typedef struct
312 {
323 
332 typedef struct
333 {
339 
341 typedef enum
342 {
348 
357 typedef enum
358 {
368 
374 typedef struct
375 {
379  uint16_t value;
381  const uint8_t * p_virtual_uuid;
383 
385 typedef enum
386 {
396 
406 typedef struct
407 {
411  uint16_t src;
413  uint8_t ttl;
419  const uint8_t * p_data;
421  uint16_t data_len;
427 
431 typedef struct
432 {
433 #if (defined(S140) || defined(S130) || defined(S132) || defined(S112) || defined(S113) || defined(HOST))
434  nrf_clock_lf_cfg_t lfclksrc;
435 #elif defined(S110)
436  nrf_clock_lfclksrc_t lfclksrc;
437 #else
438  #error "Unknown target softdevice version"
439 #endif
441  uint8_t irq_priority;
442  const uint8_t * p_uuid;
444 
471 uint32_t nrf_mesh_init(const nrf_mesh_init_params_t * p_init_params);
472 
486 uint32_t nrf_mesh_enable(void);
487 
504 uint32_t nrf_mesh_disable(void);
505 
537 uint32_t nrf_mesh_packet_send(const nrf_mesh_tx_params_t * p_params,
538  uint32_t * const p_packet_reference);
539 
562 bool nrf_mesh_process(void);
563 
577 uint32_t nrf_mesh_on_sd_evt(uint32_t sd_evt);
578 
591 
595 void nrf_mesh_rx_cb_clear(void);
596 
603 void nrf_mesh_subnet_added(uint16_t net_key_index, const uint8_t * p_network_id);
604 
613 
616 #endif /* NRF_MESH_H__ */
uint8_t observation_count
Counter of broadcast intervals.
Definition: nrf_mesh.h:299
Invalid address.
Definition: nrf_mesh.h:360
uint32_t nrf_mesh_init(const nrf_mesh_init_params_t *p_init_params)
Initializes the Bluetooth Mesh stack.
uint32_t nrf_mesh_packet_send(const nrf_mesh_tx_params_t *p_params, uint32_t *const p_packet_reference)
Queues a mesh packet for transmission.
uint32_t nrf_mesh_disable(void)
Starts disabling the Mesh.
RX packet metadata.
Definition: nrf_mesh.h:161
uint16_t data_id
ID for this particular event.
Definition: nrf_mesh.h:130
nrf_mesh_instaburst_event_id_t id
Event ID for the full advertising event.
Definition: nrf_mesh.h:142
const uint8_t * p_virtual_uuid
128-bit virtual label UUID, will be NULL if type is not NRF_MESH_ADDRESS_VIRTUAL .
Definition: nrf_mesh.h:381
nrf_mesh_rx_metadata_instaburst_t instaburst
Instaburst packet metadata.
Definition: nrf_mesh.h:169
bool force_segmented
See Bluetooth Mesh Profile Specification (MshPRFv1.0.1) section 3.7.5.2.
Definition: nrf_mesh.h:415
#define NRF_MESH_KEY_SIZE
Size (in octets) of an encryption key.
uint16_t value
Address value.
Definition: nrf_mesh.h:379
timestamp_t timestamp
Device local timestamp of the packet preamble of the adv ext packet in microseconds.
Definition: nrf_mesh.h:137
Network security material structure.
Definition: nrf_mesh.h:261
Selects 4 byte MIC size for the transport PDU.
Definition: nrf_mesh.h:388
nrf_mesh_beacon_secmat_t secmat
Beacon security material.
Definition: nrf_mesh.h:319
const nrf_mesh_application_secmat_t * p_app
Required for transport layer encryption.
Definition: nrf_mesh.h:337
bool is_last_in_chain
Whether this packet is the last packet in the advertising event.
Definition: nrf_mesh.h:144
int8_t rssi
RSSI value of the received packet.
Definition: nrf_mesh.h:139
uint32_t access_addr
Access address the packet was received on.
Definition: nrf_mesh.h:120
Selects default stack configured MIC size for the transport PDU.
Definition: nrf_mesh.h:392
timestamp_t timestamp
Device local timestamp of the packet being processed in the stack in microseconds.
Definition: nrf_mesh.h:150
Information structure for the Bluetooth Mesh network beacons.
Definition: nrf_mesh.h:311
uint8_t adv_type
BLE GAP advertising type.
Definition: nrf_mesh.h:203
The packet came from the scanner.
Definition: nrf_mesh.h:110
uint16_t interval
Actual beacon interval at the moment.
Definition: nrf_mesh.h:301
Mesh packet transmission parameters.
Definition: nrf_mesh.h:406
Key refresh phase 2.
Definition: nrf_mesh.h:232
uint16_t data_len
Length of the payload being sent.
Definition: nrf_mesh.h:421
nrf_mesh_tx_token_t tx_token
Token that can be used as a reference in the TX complete callback.
Definition: nrf_mesh.h:425
nrf_mesh_rx_metadata_gatt_t gatt
GATT packet metadata.
Definition: nrf_mesh.h:171
bool(* nrf_mesh_relay_check_cb_t)(uint16_t src, uint16_t dst, uint8_t ttl)
Callback function type for checking if a given packet should be relayed on to other nodes...
Definition: nrf_mesh.h:198
uint8_t length
Length of the advertisement packet payload.
Definition: nrf_mesh.h:204
Application security material structure.
Definition: nrf_mesh.h:245
const uint8_t * p_data
Points to the payload to be sent.
Definition: nrf_mesh.h:419
uint8_t channel
Channel the packet was received on.
Definition: nrf_mesh.h:138
The packet came from an Instaburst event.
Definition: nrf_mesh.h:112
Arguments structure for the RX callback function.
Definition: nrf_mesh.h:201
uint32_t nrf_mesh_enable(void)
Enables the Mesh.
nrf_mesh_address_type_t
Bluetooth Mesh address types.
Definition: nrf_mesh.h:357
nrf_mesh_beacon_secmat_t secmat_updated
Beacon security material during key refresh.
Definition: nrf_mesh.h:321
Event ID for an extended advertising event with Instaburst.
Definition: nrf_mesh.h:128
Run-time transmission information for individual beacons.
Definition: nrf_mesh.h:294
IV update procedure in progress.
Definition: nrf_mesh.h:346
The packet came from a GATT connection.
Definition: nrf_mesh.h:111
void nrf_mesh_subnet_added(uint16_t net_key_index, const uint8_t *p_network_id)
Notify the core stack that a subnet was added to the device.
uint16_t src
Address of the element the packet originates from (must be a unicast address).
Definition: nrf_mesh.h:411
Bluetooth Mesh security material structure.
Definition: nrf_mesh.h:332
nrf_mesh_address_type_t type
Address type.
Definition: nrf_mesh.h:377
bool iv_update_permitted
Flag indicating whether the given structure is allowed to initiate an IV update.
Definition: nrf_mesh.h:315
bool nrf_mesh_process(void)
Runs the mesh packet processing process.
void nrf_mesh_rx_cb_clear(void)
Unregister the RX callback, if any.
uint8_t irq_priority
Application IRQ priority (NRF_MESH_IRQ_PRIORITY_LOWEST or NRF_MESH_IRQ_PRIORITY_THREAD).
Definition: nrf_mesh.h:441
uint8_t channel
Channel the packet was received on.
Definition: nrf_mesh.h:121
Metadata structure for packets that originated on this device.
Definition: nrf_mesh.h:155
uint16_t connection_index
Proxy connection index the packet was received from.
Definition: nrf_mesh.h:151
void(* nrf_mesh_rx_cb_t)(const nrf_mesh_adv_packet_rx_data_t *p_rx_data)
Advertisement received callback function type.
Definition: nrf_mesh.h:218
Key refresh phase 1.
Definition: nrf_mesh.h:230
nrf_mesh_beacon_tx_info_t * p_tx_info
Pointer to a transmission info structure.
Definition: nrf_mesh.h:317
nrf_mesh_rx_source_t source
Source of the received packet.
Definition: nrf_mesh.h:163
nrf_mesh_tx_token_t nrf_mesh_unique_token_get(void)
Get unique token to be able to recognize tx complete events.
uint32_t nrf_mesh_tx_token_t
TX Token type, used as a context parameter to notify the application of ended transmissions.
Definition: nrf_mesh.h:105
nrf_mesh_relay_check_cb_t relay_cb
Application call back for relay decisions, can be NULL.
Definition: nrf_mesh.h:440
nrf_mesh_key_refresh_phase_t
Key refresh phase.
Definition: nrf_mesh.h:225
nrf_mesh_rx_metadata_loopback_t loopback
Loopback packet metadata.
Definition: nrf_mesh.h:173
uint8_t packet_index
Index of the packet in the advertising event.
Definition: nrf_mesh.h:143
Metadata structure for packets received with Instaburst.
Definition: nrf_mesh.h:135
nrf_mesh_transmic_size_t transmic_size
Transport MIC Size selection.
Definition: nrf_mesh.h:417
nrf_mesh_rx_metadata_scanner_t scanner
Scanner packet metadata.
Definition: nrf_mesh.h:167
nrf_mesh_rx_source_t
RX packet type.
Definition: nrf_mesh.h:108
Initialization parameters structure.
Definition: nrf_mesh.h:431
uint16_t rx_count
Rolling number of beacons received in each preceding period.
Definition: nrf_mesh.h:297
uint8_t ttl
Time to live value for the packet, this is a 7 bit value.
Definition: nrf_mesh.h:413
uint8_t adv_type
BLE GAP advertising type.
Definition: nrf_mesh.h:124
Metadata structure for packets received with the scanner.
Definition: nrf_mesh.h:117
nrf_mesh_address_t dst
Packet destination address.
Definition: nrf_mesh.h:409
uint8_t set_id
ID for the set this event belongs in.
Definition: nrf_mesh.h:131
In normal operation.
Definition: nrf_mesh.h:344
Key refresh phase 3.
Definition: nrf_mesh.h:234
nrf_mesh_transmic_size_t
Message MIC size selection.
Definition: nrf_mesh.h:385
Bluetooth Mesh address.
Definition: nrf_mesh.h:374
void nrf_mesh_rx_cb_set(nrf_mesh_rx_cb_t rx_cb)
Set a callback which will be called for every received non-filtered packet.
Virtual address.
Definition: nrf_mesh.h:364
int8_t rssi
RSSI value of the received packet.
Definition: nrf_mesh.h:122
Selects 8 byte MIC size for the transport PDU.
Definition: nrf_mesh.h:390
void(* nrf_mesh_assertion_handler_t)(uint32_t pc)
Mesh assertion handler type.
Definition: nrf_mesh.h:102
uint8_t nid
Network identifier.
Definition: nrf_mesh.h:264
timestamp_t timestamp
Device local timestamp of the start of the advertisement header of the packet in microseconds.
Definition: nrf_mesh.h:119
uint8_t aid
Application ID.
Definition: nrf_mesh.h:250
nrf_mesh_tx_token_t tx_token
TX Token attached to the loopback packet.
Definition: nrf_mesh.h:157
The packet came from this device.
Definition: nrf_mesh.h:113
const nrf_mesh_rx_metadata_t * p_metadata
Metadata structure for the given packet.
Definition: nrf_mesh.h:206
uint32_t nrf_mesh_on_sd_evt(uint32_t sd_evt)
Pass SoftDevice SoC events to the Mesh.
Security material for the Bluetooth Mesh network beacons.
Definition: nrf_mesh.h:278
Key refresh phase 0.
Definition: nrf_mesh.h:228
#define NRF_MESH_NETID_SIZE
Size (in octets) of the network ID.
timestamp_t tx_timestamp
Last transmission time for this beacon.
Definition: nrf_mesh.h:303
ble_gap_addr_t adv_addr
Advertisement address in the packet.
Definition: nrf_mesh.h:123
bool is_device_key
Indicates whether the device key or the application is used.
Definition: nrf_mesh.h:248
net_state_iv_update_t
State of IV update procedure.
Definition: nrf_mesh.h:341
const nrf_mesh_network_secmat_t * p_net
Required for network layer encryption.
Definition: nrf_mesh.h:335
nrf_mesh_secmat_t security_material
Required for encryption.
Definition: nrf_mesh.h:423
Unicast address.
Definition: nrf_mesh.h:362
const uint8_t * p_payload
Pointer to the raw advertisement packet payload.
Definition: nrf_mesh.h:205

Documentation feedback | Developer Zone | Subscribe | Updated