nRF5 SDK for Mesh v5.0.0
Modules | Macros | Functions
Core Mesh API

Interface for the message sending part of the mesh stack. More...


 Flash Manager
 The Flash Manager provides an entry-based persistent storage interface that works with the mesh.
 Mesh config
 Common interface for operating on all mesh states.
 Mesh friendship types
 A collection of types common to both the Low Power node (LPN) and the Friend role.
 Mesh Low Power node (LPN)
 Core mesh type definitions.
 Assert API
 Allows the framework to propagate errors that can't be recovered from.
 Core mesh definitions.
 Mesh events
 Runtime events in the core mesh.
 Mesh options
 Configuration options for the core mesh.
 Mesh section variables
 Mesh wrapper for the nRF5 SDK section variables.
 Utility functions
 Utility functions for mesh users.
 Internal event module
 Module for reporting internal stack events, to help traceability and debugging.


#define NRF_MESH_INITIAL_TOKEN   0x00000000ul
 Initial value of tokens. More...
#define NRF_MESH_SERVICE_BORDER_TOKEN   0xF0000000ul
 The upper border of the token values which are used for general communication. More...
 Reserved token values. More...
 End of the reserved friendship token range. More...


uint32_t nrf_mesh_init (const nrf_mesh_init_params_t *p_init_params)
 Initializes the Bluetooth Mesh stack. More...
uint32_t nrf_mesh_enable (void)
 Enables the Mesh. More...
uint32_t nrf_mesh_disable (void)
 Starts disabling the Mesh. More...
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. More...
bool nrf_mesh_process (void)
 Runs the mesh packet processing process. More...
uint32_t nrf_mesh_on_sd_evt (uint32_t sd_evt)
 Pass SoftDevice SoC events to the Mesh. More...
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. More...
void nrf_mesh_rx_cb_clear (void)
 Unregister the RX callback, if any.
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. More...
nrf_mesh_tx_token_t nrf_mesh_unique_token_get (void)
 Get unique token to be able to recognize tx complete events. More...

Detailed Description

Interface for the message sending part of the mesh stack.

Macro Definition Documentation


#define NRF_MESH_INITIAL_TOKEN   0x00000000ul

Initial value of tokens.

Definition at line 63 of file nrf_mesh.h.


#define NRF_MESH_SERVICE_BORDER_TOKEN   0xF0000000ul

The upper border of the token values which are used for general communication.

Definition at line 65 of file nrf_mesh.h.



Reserved token values.

Beginning of the reserved friendship token range.

Used by the Core TX Friend to resolve the Friend Bearer.

Definition at line 73 of file nrf_mesh.h.



End of the reserved friendship token range.

Definition at line 75 of file nrf_mesh.h.

Function Documentation

◆ nrf_mesh_init()

uint32_t nrf_mesh_init ( const nrf_mesh_init_params_t p_init_params)

Initializes the Bluetooth Mesh stack.

The Nordic Semiconductor SoftDevice must be initialized by the application before this function is called.
Calling this function only initializes the Mesh stack. To start transmitting and receiving messages, nrf_mesh_enable() must also be called. In addition, network and application keys must be added for the device to participate in a mesh network.
The Mesh is initialized with default parameters for the radio. To change these, use the options API, nrf_mesh_opt_set().
Enabling any proprietary extensions will break Bluetooth Mesh compatibility.
See also
nrf_mesh_enable(), nrf_mesh_opt_set()
[in]p_init_paramsPointer to initialization parameter structure.
Return values
NRF_SUCCESSThe mesh system was successfully initialized.
NRF_ERROR_SOFTDEVICE_NOT_ENABLEDThe SoftDevice has not been enabled.
NRF_ERROR_INVALID_STATEThe mesh stack has already been initialized.
NRF_ERROR_NULLThe p_init_params parameter was NULL.

◆ nrf_mesh_enable()

uint32_t nrf_mesh_enable ( void  )

Enables the Mesh.

Calling this function alone will not generate any events unless:
  • Network and application keys have been added.
  • At least one RX address has been added.
See also
Return values
NRF_SUCCESSThe Mesh was started successfully.
NRF_ERROR_INVALID_STATEThe mesh was not initialized, see nrf_mesh_init().

◆ nrf_mesh_disable()

uint32_t nrf_mesh_disable ( void  )

Starts disabling the Mesh.

Calling this function will stop the Mesh, i.e, it will stop ordering time slots from the SoftDevice and will not generate events.

The mesh will produce an NRF_MESH_EVT_DISABLED once it has been fully disabled.

The mesh should be fully disabled before the Softdevice is disabled. If the application uses the Softdevice Handler module from the nRF5 SDK, this will be handled automatically. Otherwise, the application should wait for NRF_MESH_EVT_DISABLED before disabling the Softdevice.
Return values
NRF_SUCCESSThe Mesh was stopped successfully.
NRF_ERROR_INVALID_STATEThe mesh was already disabled.

◆ nrf_mesh_packet_send()

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.

Calling this function will give an NRF_MESH_EVT_TX_COMPLETE event when the packet has been sent on air. The parameter given with the event is the same reference as returned in p_packet_reference.
If the length of the message is greater than NRF_MESH_UNSEG_PAYLOAD_SIZE_MAX, the message will be sent as a segmented message and reassembled on the peer side.
[in]p_paramsPointer to a structure containing the parameters for the message to send.
[out]p_packet_referencePointer to store a reference to the packet queued for transmission. This parameter may be set to NULL for ignoring the reference.
Return values
NRF_SUCCESSThe message was successfully queued for transmission.
NRF_ERROR_NO_MEMA packet buffer could not be allocated for the packet. The application should try to send the packet again at a later point.
NRF_ERROR_INVALID_ADDRThe source address is not a unicast address, or the destination is invalid.
NRF_ERROR_NULLp_params is a NULL pointer or a required field of the struct (other than p_data) is NULL.
NRF_ERROR_FORBIDDENFailed to allocate a sequence number from network.
NRF_ERROR_INVALID_STATEThere's already a segmented packet that is being to sent to this destination. Wait for the transmission to finish before sending new segmented packets.

◆ nrf_mesh_process()

bool nrf_mesh_process ( void  )

Runs the mesh packet processing process.

Calling this function allows the mesh to run. The mesh stack will process buffered incoming packets and send outgoing messages.

This function must be called from the main loop if the mesh is configured to be running in NRF_MESH_IRQ_PRIORITY_THREAD, and only then. If the mesh in running in IRQ level, the processing will be triggered from inside the mesh, and this function must not be called.
During nrf_mesh_process(), all events generated by the Mesh will be directly forwarded to the application if it has registered an event callback using nrf_mesh_evt_handler_add().
The Mesh will discard any data as soon as it has passed it on to the application.
Return values
trueProcessing is done, i.e. no more packets are pending. It is safe to go to sleep by calling sd_app_evt_wait().
falseProcessing is not done, i.e. packets are still pending.

◆ nrf_mesh_on_sd_evt()

uint32_t nrf_mesh_on_sd_evt ( uint32_t  sd_evt)

Pass SoftDevice SoC events to the Mesh.

Add this function in the SoC event dispatcher function used with the SoftDevice handler module (see softdevice_sys_evt_handler_set() softdevice_handler.h in the SDK).

It is vital for the Mesh to retrieve SoC events for it to function.
[in]sd_evtSoftDevice SoC event.
Return values
NRF_SUCCESSEvent successfully received.

◆ nrf_mesh_rx_cb_set()

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.

The main BT Mesh packets are not filtered and will be passed to the callback.

See Packet filtering for the details about packet's filtering.

This function must be called after nrf_mesh_init().

[in]rx_cbReceive callback function.

◆ nrf_mesh_subnet_added()

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.

[in]net_key_indexKey index of the added subnet.
[in]p_network_idNetwork ID of the added subnet.

◆ nrf_mesh_unique_token_get()

nrf_mesh_tx_token_t nrf_mesh_unique_token_get ( void  )

Get unique token to be able to recognize tx complete events.

The function guarantees that the given token will no be intersected with tokens of services from the mesh stack.

Return values
32bitsunique token value.

Documentation feedback | Developer Zone | Subscribe | Updated