nRF5 SDK for Mesh v3.2.0  08c60f6
Mesh Low Power node (LPN)

Data Structures

struct  friend_criteria_t
 Parameters of the Friend node Criteria field. More...
 
struct  mesh_lpn_friend_request_t
 Friend Request parameters. More...
 

Macros

#define MESH_LPN_FRIEND_REQUEST_TIMEOUT_MIN_MS   100
 Minimum Friend Request timeout (in milliseconds). More...
 
#define MESH_LPN_FRIEND_REQUEST_TIMEOUT_MAX_MS   1000
 Maximum Friend Request timeout (in milliseconds).
 
#define MESH_LPN_POLL_TIMEOUT_MIN_MS   1000
 Minimum supported poll timeout (in milliseconds).
 
#define MESH_LPN_POLL_TIMEOUT_MAX_MS   345599900
 Maximum supported poll timeout (in milliseconds). More...
 
#define MESH_LPN_RECEIVE_DELAY_MIN_MS   10
 Minimum allowed Receive Delay (in milliseconds).
 
#define MESH_LPN_RECEIVE_DELAY_MAX_MS   255
 Maximum allowed Receive Delay (in milliseconds).
 
#define MESH_LPN_POLL_RETRY_COUNT   5
 The number of times the LPN will retry polling the Friend before regarding the friendship as terminated.
 
#define MESH_LPN_FRIEND_REQUEST_RETRY_COUNT   5
 The number of times the LPN will retry the friend request procedure until NRF_MESH_EVT_LPN_FRIEND_REQUEST_TIMEOUT.
 
#define MESH_LPN_POLL_SEPARATION_INTERVAL_MS   50
 The minimum interval between two individual consecutive polls. More...
 

Functions

void mesh_lpn_init (void)
 Initialize the Low Power node.
 
uint32_t mesh_lpn_friend_request (mesh_lpn_friend_request_t friend_params, uint32_t request_timeout_ms)
 Initiate the friendship establishment procedure. More...
 
uint32_t mesh_lpn_friend_accept (const nrf_mesh_evt_lpn_friend_offer_t *p_friend_offer)
 Accept a Friend Offer. More...
 
uint32_t mesh_lpn_friend_poll (uint32_t delay_ms)
 Initiate a Friend Poll. More...
 
uint32_t mesh_lpn_poll_interval_set (uint32_t poll_interval_ms)
 Set the poll interval. More...
 
uint32_t mesh_lpn_friendship_terminate (void)
 Terminate the active friendship. More...
 
bool mesh_lpn_is_in_friendship (void)
 Get the state of the LPN. More...
 

Detailed Description

Macro Definition Documentation

◆ MESH_LPN_FRIEND_REQUEST_TIMEOUT_MIN_MS

#define MESH_LPN_FRIEND_REQUEST_TIMEOUT_MIN_MS   100

Minimum Friend Request timeout (in milliseconds).

Note
The timeout starts counting from the time the Friend Request is sent. The device does not start scanning until 100 milliseconds have passed from the Friend Request. See Mesh Profile specification v1.0, section 3.6.6.4.1.

Definition at line 58 of file mesh_lpn.h.

◆ MESH_LPN_POLL_TIMEOUT_MAX_MS

#define MESH_LPN_POLL_TIMEOUT_MAX_MS   345599900

Maximum supported poll timeout (in milliseconds).

This translates to slightly less than 96 hours (0x34BBFF * 100 ms). The valid range is defined in Table 3.26, section 3.6.5.3 of the Mesh Profile specification v1.0.

Definition at line 66 of file mesh_lpn.h.

◆ MESH_LPN_POLL_SEPARATION_INTERVAL_MS

#define MESH_LPN_POLL_SEPARATION_INTERVAL_MS   50

The minimum interval between two individual consecutive polls.


Definition at line 87 of file mesh_lpn.h.

Function Documentation

◆ mesh_lpn_friend_request()

uint32_t mesh_lpn_friend_request ( mesh_lpn_friend_request_t  friend_params,
uint32_t  request_timeout_ms 
)

Initiate the friendship establishment procedure.

Calling this API can generate the following events:

Parameters
[in]friend_paramsFriend request parameters. See mesh_lpn_friend_request_t for documentation of the individual parameters.
[in]request_timeout_msThe duration to scan for incoming Friend Offers. After this duration, the LPN will stop scanning and the event NRF_MESH_EVT_LPN_FRIEND_REQUEST_TIMEOUT will be generated. The timeout must be greater than MESH_LPN_FRIEND_REQUEST_TIMEOUT_MIN_MS and less or equal to MESH_LPN_FRIEND_REQUEST_TIMEOUT_MAX_MS.
Return values
NRF_SUCCESSSuccessfully initiated the friendship establishment procedure.
NRF_ERROR_INVALID_STATEAlready in an active friendship.
NRF_ERROR_INVALID_PARAMFriend request parameters outside of valid ranges.

◆ mesh_lpn_friend_accept()

uint32_t mesh_lpn_friend_accept ( const nrf_mesh_evt_lpn_friend_offer_t p_friend_offer)

Accept a Friend Offer.

Calling this API can generate the following events:

Note
This API is called as a response to the event NRF_MESH_EVT_LPN_FRIEND_OFFER. In case of a successful return, the friendship is not established until the event NRF_MESH_EVT_FRIENDSHIP_ESTABLISHED is received.
Calling the API is valid from the time of the mesh_lpn_friend_request() call until the event NRF_MESH_EVT_LPN_FRIEND_REQUEST_TIMEOUT is received. The API can be called while handling the event. This allows the LPN to wait for multiple Friend Requests before deciding which Friend node to choose.
Parameters
[in]p_friend_offerFriend Offer to be accepted, as provided by NRF_MESH_EVT_LPN_FRIEND_OFFER.
Return values
NRF_SUCCESSSuccessfully accepted the Friend Offer.
NRF_ERROR_NULLThe p_friend_offer parameter was NULL.
NRF_ERROR_INVALID_STATENot in a valid state to accept a Friend Offer.
NRF_ERROR_INVALID_PARAMInvalid parameter values in the Friend Offer.

◆ mesh_lpn_friend_poll()

uint32_t mesh_lpn_friend_poll ( uint32_t  delay_ms)

Initiate a Friend Poll.

Calling this API can generate the following events:

Parameters
[in]delay_msNumber of milliseconds until the Friend Poll is to be sent out.
Return values
NRF_SUCCESSSuccessfully initiated the Friend Poll procedure.
NRF_ERROR_INVALID_PARAMThe delay_ms cannot exceed the poll timeout. If it does, the friendship will be terminated.
NRF_ERROR_INVALID_STATENot in an active friendship.

◆ mesh_lpn_poll_interval_set()

uint32_t mesh_lpn_poll_interval_set ( uint32_t  poll_interval_ms)

Set the poll interval.

The poll interval is the interval between two separate Friend Poll actions. This is the interval between each time the node wakes up to empty the Friend Queue. The interval must be set in a way that the LPN is able to complete as many retry attempts as possible before the poll timeout expires. This means that it must satisfy the following equation:

Note
A low poll_timeout_ms and long receive_delay_ms and receive_window_ms can make it impossible to reach the MESH_LPN_POLL_RETRY_COUNT.
The new poll interval will change after the next poll. To poll immediately, use the API mesh_lpn_friend_poll().
Return values
NRF_SUCCESSSuccessfully set the new poll interval.
NRF_ERROR_INVALID_PARAMThe provided poll_interval_ms is out of range for the current poll timeout, receive delay, and Receive Window.
NRF_ERROR_INVALID_STATENot in an active friendship.

◆ mesh_lpn_friendship_terminate()

uint32_t mesh_lpn_friendship_terminate ( void  )

Terminate the active friendship.

Calling this API can generate the following events:

Note
The friendship is not terminated until the event NRF_MESH_EVT_FRIENDSHIP_TERMINATED is received. After friendship termination, the scanner is switched off.
Return values
NRF_SUCCESSSuccessfully started the friendship termination.
NRF_ERROR_INVALID_STATENot in an active friendship.

◆ mesh_lpn_is_in_friendship()

bool mesh_lpn_is_in_friendship ( void  )

Get the state of the LPN.

Returns
true if the friendship is active.
mesh_lpn_friend_request_t
Friend Request parameters.
Definition: mesh_lpn.h:105
mesh_lpn_friend_request_t::poll_timeout_ms
uint32_t poll_timeout_ms
Poll timeout (in milliseconds).
Definition: mesh_lpn.h:120
MESH_LPN_POLL_RETRY_COUNT
#define MESH_LPN_POLL_RETRY_COUNT
The number of times the LPN will retry polling the Friend before regarding the friendship as terminat...
Definition: mesh_lpn.h:77
mesh_lpn_friend_request_t::receive_delay_ms
uint32_t receive_delay_ms
Requested receive delay (in milliseconds).
Definition: mesh_lpn.h:108
nrf_mesh_evt_lpn_friend_offer_t
Definition: nrf_mesh_events.h:364
nrf_mesh_evt_lpn_friend_offer_t::receive_window_ms
uint8_t receive_window_ms
Receive window supported by the Friend node.
Definition: nrf_mesh_events.h:374
nrf_mesh_evt_lpn_friend_offer_t::offer
struct nrf_mesh_evt_lpn_friend_offer_t::@12 offer
Friend Offer parameters.