nRF5 SDK for Mesh v3.2.0  08c60f6
Model configuration

Configuration of model parameters. More...

Functions

uint32_t access_model_publish_address_set (access_model_handle_t handle, dsm_handle_t address_handle)
 Changes the publish address for the given model. More...
 
uint32_t access_model_publication_stop (access_model_handle_t handle)
 Stops the publication with the resetting of states for the given model. More...
 
uint32_t access_model_publication_by_appkey_stop (dsm_handle_t appkey_handle)
 Stops the publication with the resetting of states for all models which are bound to the appkey_handle application key. More...
 
uint32_t access_model_publish_address_get (access_model_handle_t handle, dsm_handle_t *p_address_handle)
 Gets the current publish address for the given model. More...
 
uint32_t access_model_publish_retransmit_set (access_model_handle_t handle, access_publish_retransmit_t retransmit_params)
 Sets the publish retransmit parameters for the given model. More...
 
uint32_t access_model_publish_retransmit_get (access_model_handle_t handle, access_publish_retransmit_t *p_retransmit_params)
 Gets the current publish retransmit parameters for the given model. More...
 
uint32_t access_model_publish_period_divisor_set (access_model_handle_t handle, uint16_t publish_divisor)
 Sets the publish period divisor. More...
 
uint32_t access_model_publish_period_set (access_model_handle_t handle, access_publish_resolution_t resolution, uint8_t step_number)
 Sets the publish period for the given model. More...
 
uint32_t access_model_publish_period_get (access_model_handle_t handle, access_publish_resolution_t *p_resolution, uint8_t *p_step_number)
 Gets the publish period for the given model. More...
 
uint32_t access_model_subscription_add (access_model_handle_t handle, dsm_handle_t address_handle)
 Adds a subscription to a model. More...
 
uint32_t access_model_subscription_remove (access_model_handle_t handle, dsm_handle_t address_handle)
 Removes a subscription from a model. More...
 
uint32_t access_model_subscriptions_get (access_model_handle_t handle, dsm_handle_t *p_address_handles, uint16_t *p_count)
 Gets the address handles for the subscription addresses bound to a model. More...
 
uint32_t access_model_application_bind (access_model_handle_t handle, dsm_handle_t appkey_handle)
 Binds an application key to a model. More...
 
uint32_t access_model_application_unbind (access_model_handle_t handle, dsm_handle_t appkey_handle)
 Unbinds an application key from a model. More...
 
uint32_t access_model_applications_get (access_model_handle_t handle, dsm_handle_t *p_appkey_handles, uint16_t *p_count)
 Gets the applications bound to a model. More...
 
uint32_t access_model_publish_application_set (access_model_handle_t handle, dsm_handle_t appkey_handle)
 Sets the application key to be used when publishing for the given model. More...
 
uint32_t access_model_publish_application_get (access_model_handle_t handle, dsm_handle_t *p_appkey_handle)
 Gets the application key used when publishing for the given model. More...
 
uint32_t access_model_publish_friendship_credential_flag_set (access_model_handle_t handle, bool flag)
 Sets the friendship credentials flag value for the given model. More...
 
uint32_t access_model_publish_friendship_credential_flag_get (access_model_handle_t handle, bool *p_flag)
 Gets the friendship credentials flag value for the given model. More...
 
uint32_t access_model_publish_ttl_set (access_model_handle_t handle, uint8_t ttl)
 Sets the default publication TTL value for the given model. More...
 
uint32_t access_model_publish_ttl_get (access_model_handle_t handle, uint8_t *p_ttl)
 Gets the default publication TTL value for the given model. More...
 
uint32_t access_model_id_get (access_model_handle_t handle, access_model_id_t *p_model_id)
 Gets the model ID of for the given model. More...
 
uint32_t access_model_p_args_get (access_model_handle_t handle, void **pp_args)
 Gets the generic argument pointer bound to the given model. More...
 
uint32_t access_model_subscription_list_alloc (access_model_handle_t handle)
 Allocates a subscription list for a model. More...
 
uint32_t access_model_subscription_list_dealloc (access_model_handle_t handle)
 De-allocates a subscription list for a model. More...
 
uint32_t access_model_subscription_lists_share (access_model_handle_t owner, access_model_handle_t other)
 Shares the subscription lists for two models. More...
 

Detailed Description

Configuration of model parameters.

Function Documentation

◆ access_model_publish_address_set()

uint32_t access_model_publish_address_set ( access_model_handle_t  handle,
dsm_handle_t  address_handle 
)

Changes the publish address for the given model.

Parameters
[in]handleAccess model handle.
[in]address_handleAddress to set as the current publish address.
Return values
NRF_SUCCESSSuccessfully set the publish address.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMInvalid address handle.

◆ access_model_publication_stop()

uint32_t access_model_publication_stop ( access_model_handle_t  handle)

Stops the publication with the resetting of states for the given model.

Parameters
[in]handleAccess model handle.
Return values
NRF_SUCCESSSuccess.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publication_by_appkey_stop()

uint32_t access_model_publication_by_appkey_stop ( dsm_handle_t  appkey_handle)

Stops the publication with the resetting of states for all models which are bound to the appkey_handle application key.

Parameters
[in]appkey_handleApplication key handle.
Return values
NRF_SUCCESSSuccess.
NRF_ERROR_INVALID_PARAMApplication key handle invalid.

◆ access_model_publish_address_get()

uint32_t access_model_publish_address_get ( access_model_handle_t  handle,
dsm_handle_t p_address_handle 
)

Gets the current publish address for the given model.

Note
The address handle return may be DSM_HANDLE_INVALID if the publish address for the model isn't set.
Parameters
[in]handleAccess model handle.
[out]p_address_handlePointer to store the current publish address handle.
Return values
NRF_SUCCESSSuccessfully returned the address handle.
NRF_ERROR_NULLNull pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publish_retransmit_set()

uint32_t access_model_publish_retransmit_set ( access_model_handle_t  handle,
access_publish_retransmit_t  retransmit_params 
)

Sets the publish retransmit parameters for the given model.

Parameters
[in]handleAccess model handle.
[in]retransmit_paramsRetransmit parameters to be set.
Return values
NRF_SUCCESSSuccessfully set the retransmit params.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publish_retransmit_get()

uint32_t access_model_publish_retransmit_get ( access_model_handle_t  handle,
access_publish_retransmit_t p_retransmit_params 
)

Gets the current publish retransmit parameters for the given model.

Parameters
[in]handleAccess model handle.
[out]p_retransmit_paramsPointer to store the current publish retransmit params.
Return values
NRF_SUCCESSSuccessfully returned the publish retransmit params.
NRF_ERROR_NULLNull pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publish_period_divisor_set()

uint32_t access_model_publish_period_divisor_set ( access_model_handle_t  handle,
uint16_t  publish_divisor 
)

Sets the publish period divisor.

Access layer will divide a publish period by the publish_divisor value. If publication is already active, its period will be modified immediately with the new value of publish_divisor.

Parameters
[in]handleAccess model handle.
[in]publish_divisorA divisor value to divide the model publication period with. This value should not be zero.
Return values
NRF_SUCCESSSuccessfully updated the publish period.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMThe publish_divisor value is invalid.

◆ access_model_publish_period_set()

uint32_t access_model_publish_period_set ( access_model_handle_t  handle,
access_publish_resolution_t  resolution,
uint8_t  step_number 
)

Sets the publish period for the given model.

Note
The publish period is calculated according to
period = resolution *
            step_number
Thus, setting the step_number to 0, will disable periodic publishing.
Parameters
[in]handleAccess model handle.
[in]resolutionResolution of each step. Most not be larger than ACCESS_PUBLISH_RESOLUTION_MAX.
[in]step_numberNumber of steps. Must not be larger than ACCESS_PUBLISH_PERIOD_STEP_MAX.
Return values
NRF_SUCCSESSuccessfully set the publish period.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMPublish step and/or resolution out of range.
NRF_ERROR_NOT_SUPPORTEDPeriodic publishing not supported for this model.

◆ access_model_publish_period_get()

uint32_t access_model_publish_period_get ( access_model_handle_t  handle,
access_publish_resolution_t p_resolution,
uint8_t *  p_step_number 
)

Gets the publish period for the given model.

Parameters
[in]handleAccess model handle.
[out]p_resolutionPointer to store the resolution.
[out]p_step_numberPointer to store the step number.
Return values
NRF_SUCCESSSuccessfully stored the publish period.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_subscription_add()

uint32_t access_model_subscription_add ( access_model_handle_t  handle,
dsm_handle_t  address_handle 
)

Adds a subscription to a model.

Parameters
[in]handleAccess model handle.
[in]address_handleAddress to add to the model's subscription list.
Return values
NRF_SUCCESSSuccessfully added the subscription.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_NOT_SUPPORTEDSubscriptions not supported for this model.
NRF_ERROR_INVALID_PARAMInvalid address handle.

◆ access_model_subscription_remove()

uint32_t access_model_subscription_remove ( access_model_handle_t  handle,
dsm_handle_t  address_handle 
)

Removes a subscription from a model.

Parameters
[in]handleAccess model handle.
[in]address_handleAddress to remove from the model's subscription list.
Return values
NRF_SUCCESSSuccessfully removed the subscription.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_NOT_SUPPORTEDSubscriptions not supported for this model.
NRF_ERROR_INVALID_PARAMInvalid address handle.

◆ access_model_subscriptions_get()

uint32_t access_model_subscriptions_get ( access_model_handle_t  handle,
dsm_handle_t p_address_handles,
uint16_t *  p_count 
)

Gets the address handles for the subscription addresses bound to a model.

Parameters
[in]handleAccess model handle.
[out]p_address_handlesPointer to array for storing address handles.
[in,out]p_countPointer to number of available handles in p_address_handles. The number of written handles is returned
Return values
NRF_SUCCESSSuccessfully stored the address handles.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_NOT_SUPPORTEDSubscriptions are not supported by this model.
NRF_ERROR_INVALID_LENGTHSize of p_address_handles too small for storing all the bound keys.

◆ access_model_application_bind()

uint32_t access_model_application_bind ( access_model_handle_t  handle,
dsm_handle_t  appkey_handle 
)

Binds an application key to a model.

Parameters
[in]handleAccess model handle.
[in]appkey_handleApplication handle to add to the model.
Return values
NRF_SUCCESSSuccessfully added the application key.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMInvalid application key handle.

◆ access_model_application_unbind()

uint32_t access_model_application_unbind ( access_model_handle_t  handle,
dsm_handle_t  appkey_handle 
)

Unbinds an application key from a model.

Parameters
[in]handleAccess model handle.
[in]appkey_handleApplication handle to remove from the model.
Return values
NRF_SUCCESSSuccessfully removed the application key.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMInvalid application key handle.

◆ access_model_applications_get()

uint32_t access_model_applications_get ( access_model_handle_t  handle,
dsm_handle_t p_appkey_handles,
uint16_t *  p_count 
)

Gets the applications bound to a model.

Parameters
[in]handleAccess model handle.
[out]p_appkey_handlesPointer to array where the DSM handles will be stored.
[in,out]p_countPointer to number of handles available in p_appkey_handles. The number of written handles will be returned in p_count.
Return values
NRF_SUCCESSSuccessfully stored the application handles.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_INVALID_PARAMInvalid access model handle.
NRF_ERROR_INVALID_LENGTHSize of p_appkey_handles too small for storing all the bound keys.

◆ access_model_publish_application_set()

uint32_t access_model_publish_application_set ( access_model_handle_t  handle,
dsm_handle_t  appkey_handle 
)

Sets the application key to be used when publishing for the given model.

Note
To unbind the application key, set appkey_handle to DSM_HANDLE_INVALID.
Parameters
[in]handleAccess model handle.
[in]appkey_handleApplication handle to bind with model.
Return values
NRF_SUCCESSSuccessfully set the application key used for publishing.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMInvalid application key handle.

◆ access_model_publish_application_get()

uint32_t access_model_publish_application_get ( access_model_handle_t  handle,
dsm_handle_t p_appkey_handle 
)

Gets the application key used when publishing for the given model.

Parameters
[in]handleAccess model handle.
[out]p_appkey_handlePointer to store the application handle.
Return values
NRF_SUCCESSSuccessfully stored the application key used for publishing.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publish_friendship_credential_flag_set()

uint32_t access_model_publish_friendship_credential_flag_set ( access_model_handle_t  handle,
bool  flag 
)

Sets the friendship credentials flag value for the given model.

Parameters
[in]handleAccess model handle.
[in]flagNew friendship credentials flag value.
Return values
NRF_SUCCESSSuccessfully set the default publication TTL value.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publish_friendship_credential_flag_get()

uint32_t access_model_publish_friendship_credential_flag_get ( access_model_handle_t  handle,
bool *  p_flag 
)

Gets the friendship credentials flag value for the given model.

Parameters
[in]handleAccess model handle.
[in]p_flagPointer to store the friendship credentials flag value.
Return values
NRF_SUCCESSSuccessfully retrived the friendship credentials flag value.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_publish_ttl_set()

uint32_t access_model_publish_ttl_set ( access_model_handle_t  handle,
uint8_t  ttl 
)

Sets the default publication TTL value for the given model.

Parameters
[in]handleAccess model handle.
[in]ttlNew default TTL value.
Return values
NRF_SUCCESSSuccessfully set the default publication TTL value.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_PARAMTTL value has to be less than NRF_MESH_TTL_MAX.

◆ access_model_publish_ttl_get()

uint32_t access_model_publish_ttl_get ( access_model_handle_t  handle,
uint8_t *  p_ttl 
)

Gets the default publication TTL value for the given model.

Parameters
[in]handleAccess model handle.
[out]p_ttlPointer to store the default TTL value.
Return values
NRF_SUCCESSSuccessfully retrived the default publication TTL value.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_id_get()

uint32_t access_model_id_get ( access_model_handle_t  handle,
access_model_id_t p_model_id 
)

Gets the model ID of for the given model.

Parameters
[in]handleAccess model handle.
[out]p_model_idPointer to store the model ID.
Return values
NRF_SUCCESSSuccessfully got the model ID.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDInvalid access handle.

◆ access_model_p_args_get()

uint32_t access_model_p_args_get ( access_model_handle_t  handle,
void **  pp_args 
)

Gets the generic argument pointer bound to the given model.

Parameters
[in]handleAccess model handle.
[out]pp_argsDouble pointer to return the generic argument pointer.
Return values
NRF_SUCCESSSuccessfully returned the generic argument pointer.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_NOT_FOUNDAccess handle invalid.

◆ access_model_subscription_list_alloc()

uint32_t access_model_subscription_list_alloc ( access_model_handle_t  handle)

Allocates a subscription list for a model.

Allocating a subscription list for a model that already has one allocated results in Success and does not cause changes to the already allocated subscription list.

Parameters
[in]handleModel handle to allocate list for.
Return values
NRF_SUCCESSSuccessfully allocated subscription list.
NRF_ERROR_NO_MEMNo more subscription lists available in memory pool.
See also
ACCESS_SUBSCRIPTION_LIST_COUNT.
Return values
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_INVALID_STATEA subscription list is already allocated for model.
NRF_ERROR_FORBIDDENModel configuration is frozen and changes to model subscription list are not allowed.

◆ access_model_subscription_list_dealloc()

uint32_t access_model_subscription_list_dealloc ( access_model_handle_t  handle)

De-allocates a subscription list for a model.

This function is intended to be used during the initialization of the extended models. De-allocating a subscription list for a model that does not have any list allocated yet results in Success. It is not allowed to de-allocate the subscription list once the model-subscription list configuration is written in the flash or when access layer data is being stored to the flash.

Parameters
[in]handleModel handle to de-allocate list for.
Return values
NRF_SUCCESSSuccessfully de-allocated subscription list.
NRF_ERROR_NOT_FOUNDAccess handle invalid.
NRF_ERROR_FORBIDDENModel configuration is frozen and changes to model subscription list are not allowed.

◆ access_model_subscription_lists_share()

uint32_t access_model_subscription_lists_share ( access_model_handle_t  owner,
access_model_handle_t  other 
)

Shares the subscription lists for two models.

This function is used with models that operate on bound states and need to share a single subscription list. Subscription list of the owner will be shared with other. If the other model already has a subscription list allocated, this API will de-allocate it before sharing the list of the owner.

Parameters
[in]ownerThe owner of the subscription list (the model handle that has allocated a subscription list).
[in]otherThe model that will share the owner's subscription list.
Return values
NRF_SUCCESSSuccessfully shared the subscription list.
NRF_ERROR_NOT_FOUNDAccess handle invalid for one or more of the models.
NRF_ERROR_INVALID_STATEInvalid parameter combination. The owner must have a subscription list allocated.
NRF_ERROR_FORBIDDENModel configuration is frozen and changes to model subscription list are not allowed.