The access layer API is the main API for Mesh Models. More...

Modules
	Access layer API MSCs
	Access layer sequence diagrams.

	Defines
	Access layer defines.

	Types
	Access layer type definitions.

	Acknowledged messages
	Acknowledged message sending for the access layer.

	Utility functions
	Utility functions for access layer users.

Functions
void	access_init (void)
	Initializes the access layer.

void	access_clear (void)
	Clears the access layer states, and erases the persistent storage copy.

uint32_t	access_model_add (const access_model_add_params_t p_model_params, access_model_handle_t p_model_handle)
	Allocates, initializes and adds a model to the element at the given element index. More...

uint32_t	access_model_publish (access_model_handle_t handle, const access_message_tx_t *p_message)
	Publishes an access layer message to the publish address of the model. More...

uint32_t	access_model_reply (access_model_handle_t handle, const access_message_rx_t p_message, const access_message_tx_t p_reply)
	Replies to an access layer message. More...

uint32_t	access_model_element_index_get (access_model_handle_t handle, uint16_t *p_element_index)
	Returns the element index for the model handle. More...

Detailed Description

The access layer API is the main API for Mesh Models.

The access layer API provides a way for models to register into the device database, and send and receive messages on the mesh. See Creating new models for a walkthrough of the usage of the access layer API.

Function Documentation

◆ access_model_add()

uint32_t access_model_add	(	const access_model_add_params_t *	p_model_params,
		access_model_handle_t *	p_model_handle
	)

Allocates, initializes and adds a model to the element at the given element index.

Parameters

[in]	p_model_params	Pointer to model initialization parameter structure.
[out]	p_model_handle	Pointer to store allocated model handle.

Return values

NRF_SUCCESS	Successfully added model to the given element.
NRF_ERROR_NO_MEM	ACCESS_MODEL_COUNT number of models already allocated.
NRF_ERROR_NULL	One or more of the function parameters was NULL.
NRF_ERROR_FORBIDDEN	Multiple model instances per element are not allowed or changes to device composition are not allowed. Adding a new model after device is provisioned is not allowed.
NRF_ERROR_NOT_FOUND	Invalid access element index.
NRF_ERROR_INVALID_LENGTH	Number of opcodes was zero and pointer to the list of opcode handler callbacks is not NULL.
NRF_ERROR_INVALID_PARAM	One or more of the opcodes had an invalid format.

See also: access_opcode_t for documentation of the valid format.

◆ access_model_publish()

uint32_t access_model_publish	(	access_model_handle_t	handle,
		const access_message_tx_t *	p_message
	)

Publishes an access layer message to the publish address of the model.

Once the message is published and the Public Retransmit Count (see config_publication_state_t::retransmit_count) for the model is set to non-zero value, the message is queued for later re-transmissions. If there is not enough memory to publish the message during the re-transmission or if the previous transmission of the segmented message is still in progress, the re-transmission attempt will be skipped. If the next message is published before previous re-tranmissions are finished, the remaining re-transmissions attempts of the previous message will be skipped. the re-transmission attempt will be skipped.

Note

The message will be sent as a segmented message and reassembled on the peer side if one of the following conditions are true:

The length of the message is greater than NRF_MESH_UNSEG_PAYLOAD_SIZE_MAX.
The force_segmented field of p_message is true.
The transmic_size field of p_message is NRF_MESH_TRANSMIC_SIZE_LARGE.

Parameters

[in]	handle	Access handle for the model that wants to send data.
[in]	p_message	Access layer TX message parameter structure.

Return values

NRF_SUCCESS	Successfully queued packet for transmission.
NRF_ERROR_NULL	NULL pointer supplied to function.
NRF_ERROR_NO_MEM	Not enough memory available for message.
NRF_ERROR_NOT_FOUND	Invalid model handle or model not bound to element.
NRF_ERROR_INVALID_ADDR	The element index is greater than the number of local unicast addresses stored by the Device State Manager.
NRF_ERROR_INVALID_PARAM	Model not bound to appkey, publish address not set or wrong opcode format.
NRF_ERROR_INVALID_LENGTH	Attempted to send message larger than ACCESS_MESSAGE_LENGTH_MAX.
NRF_ERROR_FORBIDDEN	Failed to allocate a sequence number from network.
NRF_ERROR_INVALID_STATE	There's already a segmented packet that is being to sent to this destination. Wait for the transmission to finish before sending new segmented packets.

◆ access_model_reply()

uint32_t access_model_reply	(	access_model_handle_t	handle,
		const access_message_rx_t *	p_message,
		const access_message_tx_t *	p_reply
	)

Replies to an access layer message.

This function is intended to be used in pair with the opcode handle callbacks. The model gets a message through the opcode handler callback and replies to the incoming message by calling this function.

Note

The reply is sent as a segmented message and reassembled on the peer side if one of the following conditions is true:

The length of the message is greater than NRF_MESH_UNSEG_PAYLOAD_SIZE_MAX.
The force_segmented field of p_reply is true.
The transmic_size field of p_reply is NRF_MESH_TRANSMIC_SIZE_LARGE.

Parameters

[in]	handle	Access handle for the model that wants to send data.
[in]	p_message	Incoming message that the model is replying to.
[in]	p_reply	The reply data.

Return values

NRF_SUCCESS	Successfully queued packet for transmission.
NRF_ERROR_NULL	NULL pointer supplied to function.
NRF_ERROR_NO_MEM	Not enough memory available for message.
NRF_ERROR_NOT_FOUND	Invalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAM	Model not bound to appkey, publish address not set, or wrong opcode format.
NRF_ERROR_INVALID_LENGTH	Attempted to send message larger than ACCESS_MESSAGE_LENGTH_MAX.
NRF_ERROR_FORBIDDEN	Failed to allocate a sequence number from network.
NRF_ERROR_INVALID_STATE	There is already a segmented packet to this destination in progress. Wait for it to finish before sending new segmented packets.

◆ access_model_element_index_get()

uint32_t access_model_element_index_get	(	access_model_handle_t	handle,
		uint16_t *	p_element_index
	)

Returns the element index for the model handle.

This function is indended to be used inside the state transaction callbacks triggered by the model to quickly resolve the element index on which the message arrived.

Parameters

[in]	handle	Access handle for the model that wants to send data.
[out]	p_element_index	Pointer to the hold retrieved element index for the model handle

Return values

NRF_SUCCESS	Model handle is valid and `element_index` pointer is updated.
NRF_ERROR_NULL	NULL pointer supplied to function.
NRF_ERROR_NOT_FOUND	Invalid model handle or model not bound to element.

Modules

Functions

Detailed Description

Function Documentation

◆ access_model_add()

◆ access_model_publish()

◆ access_model_reply()

◆ access_model_element_index_get()