nRF5 SDK for Mesh v3.2.0  08c60f6
Access layer API

Modules

 Access layer API MSCs
 Access layer sequence diagrams.
 
 Defines
 Access layer defines.
 
 Types
 Access layer type definitions.
 
 Reliable messages
 
 Utility functions
 

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_paramsPointer to model initialization parameter structure.
[out]p_model_handlePointer to store allocated model handle.
Return values
NRF_SUCCESSSuccessfully added model to the given element.
NRF_ERROR_NO_MEMACCESS_MODEL_COUNT number of models already allocated.
NRF_ERROR_NULLOne or more of the function parameters was NULL.
NRF_ERROR_FORBIDDENEither multiple model instances per element is not allowed or changes to device composition are not allowed.
NRF_ERROR_NOT_FOUNDInvalid access element index.
NRF_ERROR_INVALID_LENGTHNumber of opcodes was zero and pointer to the list of opcode handler callbacks is not NULL.
NRF_ERROR_INVALID_PARAMOne 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:
Parameters
[in]handleAccess handle for the model that wants to send data.
[in]p_messageAccess layer TX message parameter structure.
Return values
NRF_SUCCESSSuccessfully queued packet for transmission.
NRF_ERROR_NULLNULL pointer supplied to function.
NRF_ERROR_NO_MEMNot enough memory available for message.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.
NRF_ERROR_INVALID_ADDRThe element index is greater than the number of local unicast addresses stored by the Device State Manager.
NRF_ERROR_INVALID_PARAMModel not bound to appkey, publish address not set or wrong opcode format.
NRF_ERROR_INVALID_LENGTHAttempted to send message larger than ACCESS_MESSAGE_LENGTH_MAX.
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.

◆ 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 message will be sent as a segmented message and reassembled on the peer side if one of the following conditions are true:
Parameters
[in]handleAccess handle for the model that wants to send data.
[in]p_messageIncoming message that the model is replying to.
[in]p_replyThe reply data.
Return values
NRF_SUCCESSSuccessfully queued packet for transmission.
NRF_ERROR_NULLNULL pointer supplied to function.
NRF_ERROR_NO_MEMNot enough memory available for message.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAMModel not bound to appkey, publish address not set or wrong opcode format.
NRF_ERROR_INVALID_LENGTHAttempted to send message larger than ACCESS_MESSAGE_LENGTH_MAX.
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.

◆ 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]handleAccess handle for the model that wants to send data.
[out]p_element_indexPointer to the hold retrieved element index for the model handle
Return values
NRF_SUCCESSModel handle is valid and element_index pointer is updated.
NRF_ERROR_NULLNULL pointer supplied to function.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.