nRF5 SDK for Mesh v3.2.0  08c60f6
Core Mesh API

Modules

 Flash Manager
 
 Mesh config
 
 Mesh friendship types
 
 Mesh Low Power node (LPN)
 
 Types
 Core mesh type definitions.
 
 Assert API
 
 Defines
 
 Mesh events
 
 Mesh options
 
 Mesh section variables
 
 Utility functions
 
 Internal event module
 

Macros

#define NRF_MESH_INITIAL_TOKEN   0x00000000ul
 Initial value of tokens.
 
#define NRF_MESH_SERVICE_BORDER_TOKEN   0xF0000000ul
 The upper border of the token values which are used for general communication.
 
#define NRF_MESH_FRIEND_TOKEN_BEGIN   0xFFFFFE00ul
 Reserved token values. More...
 
#define NRF_MESH_FRIEND_TOKEN_END   0xFFFFFEFFul
 End of the reserved friendship token range.
 
#define NRF_MESH_FRIEND_POLL_TOKEN   0xFFFFFFF8ul
 
#define NRF_MESH_FRIEND_REQUEST_TOKEN   0xFFFFFFF9ul
 
#define NRF_MESH_FRIEND_CLEAR_TOKEN   0xFFFFFFFAul
 
#define NRF_MESH_SUBMAN_ADD_TOKEN   0xFFFFFFFBul
 
#define NRF_MESH_SUBMAN_REMOVE_TOKEN   0xFFFFFFFCul
 
#define NRF_MESH_HEARTBEAT_TOKEN   0xFFFFFFFDul
 
#define NRF_MESH_SAR_TOKEN   0xFFFFFFFEul
 
#define NRF_MESH_RELAY_TOKEN   0xFFFFFFFFul
 

Functions

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 packet being received. 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

◆ NRF_MESH_FRIEND_TOKEN_BEGIN

#define NRF_MESH_FRIEND_TOKEN_BEGIN   0xFFFFFE00ul

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.

Function Documentation

◆ nrf_mesh_init()

uint32_t nrf_mesh_init ( const nrf_mesh_init_params_t p_init_params)

Initializes the Bluetooth Mesh stack.

Note
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().
Warning
Enabling any proprietary extensions will break Bluetooth Mesh compatibility.
See also
nrf_mesh_enable(), nrf_mesh_opt_set()
Parameters
[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.

Note
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
nrf_mesh_rx_addr_add()
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.

Warning
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.

Note
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.
Parameters
[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_INVALID_PARAMTTL was larger than NRF_MESH_TTL_MAX.
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 to this destination in progress. Wait for it 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.

Note
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().
Warning
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).

Warning
It is vital for the Mesh to retrieve SoC events for it to function.
Parameters
[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 packet being received.

This function must be called after nrf_mesh_init().

Parameters
[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.

Parameters
[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.