Mesh Low Power node (LPN)

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 Bluetooth Mesh Profile Specification (MshPRFv1.0.1) section 3.6.6.4.1.

Definition at line 58 of file mesh_lpn.h.

Maximum Friend Request timeout (in milliseconds).

Definition at line 60 of file mesh_lpn.h.

Minimum supported poll timeout (in milliseconds).

Definition at line 63 of file mesh_lpn.h.

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, Bluetooth Mesh Profile Specification (MshPRFv1.0.1) section 3.6.5.3

Definition at line 66 of file mesh_lpn.h.

Minimum allowed Receive Delay (in milliseconds).

Definition at line 70 of file mesh_lpn.h.

Maximum allowed Receive Delay (in milliseconds).

Definition at line 72 of file mesh_lpn.h.

The number of times the LPN will retry polling the Friend before regarding the friendship as terminated.

Definition at line 77 of file mesh_lpn.h.

The number of times the LPN will retry the friend request procedure until NRF_MESH_EVT_LPN_FRIEND_REQUEST_TIMEOUT.

Definition at line 82 of file mesh_lpn.h.

The minimum interval between two individual consecutive polls.

Definition at line 87 of file mesh_lpn.h.

Initialize the Low Power node.

Initiate the friendship establishment procedure.

Calling this API can generate the following events:

• NRF_MESH_EVT_LPN_FRIEND_OFFER
• NRF_MESH_EVT_LPN_FRIEND_REQUEST_TIMEOUT

Note

This API should not be called within the handler for the event NRF_MESH_EVT_FRIENDSHIP_TERMINATED. Doing this will cause NRF_ERROR_INVALID_STATE to be returned, and the friendship establishment procedure will not be initiated.

Parameters

[in]	friend_params	Friend request parameters. See mesh_lpn_friend_request_t for documentation of the individual parameters.
[in]	request_timeout_ms	The 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_SUCCESS	Successfully initiated the friendship establishment procedure.
NRF_ERROR_INVALID_STATE	Already in an active friendship.
NRF_ERROR_INVALID_PARAM	Friend request parameters outside of valid ranges.

Accept a Friend Offer.

Calling this API can generate the following events:

• NRF_MESH_EVT_FRIENDSHIP_ESTABLISHED
• NRF_MESH_EVT_LPN_FRIEND_POLL_COMPLETE

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_offer

Friend Offer to be accepted, as provided by NRF_MESH_EVT_LPN_FRIEND_OFFER.

Return values

NRF_SUCCESS	Successfully accepted the Friend Offer.
NRF_ERROR_NULL	The p_friend_offer parameter was NULL.
NRF_ERROR_INVALID_STATE	Not in a valid state to accept a Friend Offer.
NRF_ERROR_INVALID_PARAM	Invalid parameter values in the Friend Offer.

Initiate a Friend Poll.

Calling this API can generate the following events:

• NRF_MESH_EVT_LPN_FRIEND_POLL_COMPLETE

Parameters

[in]

delay_ms

Number of milliseconds until the Friend Poll is to be sent out.

Return values

NRF_SUCCESS	Successfully initiated the Friend Poll procedure.
NRF_ERROR_INVALID_PARAM	The delay_ms cannot exceed the poll timeout. If it does, the friendship will be terminated.
NRF_ERROR_INVALID_STATE	Not in an active friendship.

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:

poll_interval_ms < (mesh_lpn_friend_request_t.poll_timeout_ms -
                    (mesh_lpn_friend_request_t.receive_delay_ms +
                     nrf_mesh_evt_lpn_friend_offer_t.offer.receive_window_ms) * (MESH_LPN_POLL_RETRY_COUNT + 1))

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_SUCCESS	Successfully set the new poll interval.
NRF_ERROR_INVALID_PARAM	The provided poll_interval_ms is out of range for the current poll timeout, receive delay, and Receive Window.
NRF_ERROR_INVALID_STATE	Not in an active friendship.

Terminate the active friendship.

Calling this API can generate the following events:

• NRF_MESH_EVT_FRIENDSHIP_TERMINATED

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_SUCCESS	Successfully started the friendship termination.
NRF_ERROR_INVALID_STATE	Not in an active friendship.

Get the state of the LPN.

Returns

true if the friendship is active.