The access layer API is the main API for Mesh Models.
More...
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.
◆ access_model_add()
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()
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] | 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()
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:
- 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()
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. |