Mesh modules that implement the Friend feature. More...

#define	MESH_FRIEND_RECEIVE_WINDOW_MIN_MS (1)
	Shortest receive window supported by the Friend node. More...

#define	MESH_FRIEND_RECEIVE_WINDOW_MAX_MS (255)
	Longest receive window supported by the Friend node. More...

#define	MESH_FRIEND_RECEIVE_WINDOW_DEFAULT_MS (5)
	Default receive window offered by the Friend node. More...

uint32_t	mesh_friend_init (void)
	Initializes the Friend feature. More...

void	mesh_friend_enable (void)
	Enables the Friend feature. More...

void	mesh_friend_disable (void)
	Disables the Friend feature. More...

bool	mesh_friend_is_enabled (void)
	Gets the state of the Friend feature. More...

uint32_t	mesh_friend_friendship_terminate (const mesh_friendship_t *p_friendship)
	Terminates the friendship with the given LPN. More...

uint32_t	mesh_friend_friendship_terminate_all (void)
	Terminates all active friendships. More...

uint32_t	mesh_friend_receive_window_set (uint8_t receive_window_ms)
	Sets the receive window offered in the Friend Offer. More...

uint32_t	mesh_friend_friendships_get (const mesh_friendship_t *pp_friendships, uint8_t p_count)
	Gets all the current active friendships. More...

uint32_t	mesh_friend_stats_get (const mesh_friendship_t p_friendship, mesh_friend_stats_t p_stats)
	Gets the structures of statistics for the given friendship. More...

Detailed Description

Mesh modules that implement the Friend feature.

The APIs for the Friend role are used internally by the mesh stack. The Friend feature for the application can be enabled by setting MESH_FEATURE_FRIEND_ENABLED define to 1.

Macro Definition Documentation

◆ MESH_FRIEND_RECEIVE_WINDOW_MIN_MS

#define MESH_FRIEND_RECEIVE_WINDOW_MIN_MS (1)

Shortest receive window supported by the Friend node.

Definition at line 54 of file mesh_friend.h.

◆ MESH_FRIEND_RECEIVE_WINDOW_MAX_MS

#define MESH_FRIEND_RECEIVE_WINDOW_MAX_MS (255)

Longest receive window supported by the Friend node.

Definition at line 56 of file mesh_friend.h.

◆ MESH_FRIEND_RECEIVE_WINDOW_DEFAULT_MS

#define MESH_FRIEND_RECEIVE_WINDOW_DEFAULT_MS (5)

Default receive window offered by the Friend node.

Note: You can later change this with mesh_friend_receive_window_set().

Definition at line 61 of file mesh_friend.h.

Function Documentation

◆ mesh_friend_init()

uint32_t mesh_friend_init ( void )

Initializes the Friend feature.

Return values

NRF_SUCCESS	Successfully initialized the Friend feature.
NRF_ERROR_INVALID_STATE	Friend feature has already been initialized.

◆ mesh_friend_enable()

void mesh_friend_enable ( void )

Enables the Friend feature.

Note: After the Friend feature has been enabled, the Friend is required to respond to any Friend Request from a Low Power node (see the Bluetooth Mesh Profile Specification (MshPRFv1.0.1), section 3.6.6.3.1).

The application can receive any of the following events after this API has been called:

◆ mesh_friend_disable()

void mesh_friend_disable ( void )

Disables the Friend feature.

Disabling the Friend feature will terminate all active friendships.

◆ mesh_friend_is_enabled()

bool mesh_friend_is_enabled ( void )

Gets the state of the Friend feature.

Return values

true	Friend feature is enabled.
false	Friend feature is disabled.

◆ mesh_friend_friendship_terminate()

uint32_t mesh_friend_friendship_terminate ( const mesh_friendship_t * p_friendship )

Terminates the friendship with the given LPN.

Note: This API may be used to deny a friendship request.

When the friendship is considered terminated, an NRF_MESH_EVT_FRIENDSHIP_TERMINATED event will be generated. If the API is used to deny a Friend Request, no event will be generated.

Parameters

[in] p_friendship Friendship context pointer corresponding to the friendship that is to be terminated.

Return values

NRF_SUCCESS	Successfully terminated the friendship.
NRF_ERROR_PARAM	No known friendship is associated with the given context.

◆ mesh_friend_friendship_terminate_all()

uint32_t mesh_friend_friendship_terminate_all ( void )

Terminates all active friendships.

An NRF_MESH_EVT_FRIENDSHIP_TERMINATED will be generated for each of the established friendships.

Return values

NRF_SUCCESS Successfully terminated all active friendships.

◆ mesh_friend_receive_window_set()

uint32_t mesh_friend_receive_window_set ( uint8_t receive_window_ms )

Sets the receive window offered in the Friend Offer.

The new receive window is only valid for new friendships. Calling this function will have no effect on existing friendships.

Parameters

[in] receive_window_ms Receive window in milliseconds.

Return values

NRF_SUCCESS	Successfully set the receive window.
NRF_ERROR_INVALID_PARAM	`receive_window_ms` is not between MESH_FRIEND_RECEIVE_WINDOW_MIN_MS and MESH_FRIEND_RECEIVE_WINDOW_MAX_MS.

◆ mesh_friend_friendships_get()

uint32_t mesh_friend_friendships_get	(	const mesh_friendship_t **	pp_friendships,
		uint8_t *	p_count
	)

Gets all the current active friendships.

Usage:

const mesh_friendship_t * friendships[MESH_FRIEND_FRIENDSHIP_COUNT];
uint8_t count = MESH_FRIEND_FRIENDSHIP_COUNT;
uint32_t error_code = mesh_friend_friendships_get(&friendships[0], &count);

Parameters

[in,out]	pp_friendships	Array of const mesh_friendship_t pointers.
[in,out]	p_count	In: Number of elements in `pp_friendships`. Out: Number of elements stored in `pp_friendships`.

Return values

NRF_SUCCESS	Successfully retrieved all active friendships.
NRF_ERROR_NULL	One or more of the function arguments were `NULL`.

◆ mesh_friend_stats_get()

uint32_t mesh_friend_stats_get	(	const mesh_friendship_t *	p_friendship,
		mesh_friend_stats_t *	p_stats
	)

Gets the structures of statistics for the given friendship.

Friendship statistics are only gathered if FRIEND_DEBUG is enabled.

Parameters

[in]	p_friendship	Friendship to get the statistics for.
[in,out]	p_stats	Statistics structure to fill.

Return values

NRF_SUCCESS	Structure of statistics successfully populated.
NRF_ERROR_NULL	One or more of the function arguments were `NULL`.
NRF_ERROR_NOT_FOUND	No known friendship is associated with the given context.
NRF_ERROR_NOT_SUPPORTED	Gathering of Friend statistics not enabled.