RA Flexible Software Package Documentation  Release v5.2.0

 
BLE Mesh Network Provision (rm_ble_mesh_provision)

Functions

fsp_err_t RM_BLE_MESH_PROVISION_Open (rm_ble_mesh_provision_ctrl_t *const p_ctrl, rm_ble_mesh_provision_cfg_t const *const p_cfg)
 
fsp_err_t RM_BLE_MESH_PROVISION_Close (rm_ble_mesh_provision_ctrl_t *const p_ctrl)
 
fsp_err_t RM_BLE_MESH_PROVISION_Setup (rm_ble_mesh_provision_ctrl_t *const p_ctrl, rm_ble_mesh_provision_role_t role, rm_ble_mesh_provision_device_info_t info, uint16_t timeout)
 
fsp_err_t RM_BLE_MESH_PROVISION_Bind (rm_ble_mesh_provision_ctrl_t *const p_ctrl, rm_ble_mesh_provision_device_info_t info, uint8_t attention, rm_ble_mesh_provision_handle_t *const p_handle)
 
fsp_err_t RM_BLE_MESH_PROVISION_SendPdu (rm_ble_mesh_provision_ctrl_t *const p_ctrl, rm_ble_mesh_provision_handle_t const *const p_handle, rm_ble_mesh_provision_pdu_type_t type, rm_ble_mesh_buffer_t pdu_data)
 
fsp_err_t RM_BLE_MESH_PROVISION_SetAuthVal (rm_ble_mesh_provision_ctrl_t *const p_ctrl, rm_ble_mesh_provision_handle_t const *const p_handle, rm_ble_mesh_buffer_t auth_value)
 
fsp_err_t RM_BLE_MESH_PROVISION_Abort (rm_ble_mesh_provision_ctrl_t *const p_ctrl, rm_ble_mesh_provision_handle_t const *const p_handle, rm_ble_mesh_provision_link_close_reason_t reason)
 
fsp_err_t RM_BLE_MESH_PROVISION_GetLocalPublicKey (rm_ble_mesh_provision_ctrl_t *const p_ctrl, uint8_t *const p_public_key)
 
fsp_err_t RM_BLE_MESH_PROVISION_SetLocalPublicKey (rm_ble_mesh_provision_ctrl_t *const p_ctrl, uint8_t const *const p_public_key)
 
fsp_err_t RM_BLE_MESH_PROVISION_GenerateRandomizedNumber (rm_ble_mesh_provision_ctrl_t *const p_ctrl, uint8_t *const p_key)
 
fsp_err_t RM_BLE_MESH_PROVISION_SetOobPublicKey (rm_ble_mesh_provision_ctrl_t *const p_ctrl, uint8_t const *const p_key, uint8_t size)
 
fsp_err_t RM_BLE_MESH_PROVISION_SetOobAuthInfo (rm_ble_mesh_provision_ctrl_t *const p_ctrl, uint8_t const *const p_auth_info, uint8_t size)
 
fsp_err_t RM_BLE_MESH_PROVISION_GenerateEcdhKey (rm_ble_mesh_provision_ctrl_t *const p_ctrl, uint8_t *const p_public_key)
 

Detailed Description

Overview

Target Devices

The BLE Mesh Network Provision module supports the following devices.

Configuration

Build Time Configurations for rm_ble_mesh_provision

The following build time configurations are defined in fsp_cfg/rm_ble_mesh_provision_cfg.h:

ConfigurationOptionsDefaultDescription

Configurations for Networking > BLE Mesh Network modules > BLE Mesh Provision (rm_ble_mesh_provision)

This module can be added to the Stacks tab via New Stack > Networking > BLE Mesh Network modules > BLE Mesh Provision (rm_ble_mesh_provision).

ConfigurationOptionsDefaultDescription
General
NameName Must Be a Valid C Symbolg_rm_ble_mesh_provision0 Module name.
Provision Capabilities
Number of ElementsInvalid Number of Elements1 Provision capabilities number of elements.
Supported AlgorithmsInvalid Supported Algorithms0 Provision capabilities supported algorithms.
Public Key TypeInvalid Public Key Type0 Provision capabilities public key type.
Static OOB TypeInvalid Static OOB Type0 Provision capabilities static OOB type.
Output OOB ActionInvalid Output OOB Action0 Provision capabilities output OOB action.
Output OOB SizeInvalid Output OOB Size0 Provision capabilities output OOB size.
Input OOB ActionInvalid Input OOB Action0 Provision capabilities input OOB action.
Input OOB SizeInvalid Input OOB Size0 Provision capabilities iutput OOB size.
Channel NumberInvalid Channel Number0 Select channel corresponding to the channel number of the hardware.
Provision CallbackName Must Be a Valid C Symbol.NULL Provision callback function name.

Data Structures

struct  rm_ble_mesh_provision_instance_ctrl_t
 

Data Structure Documentation

◆ rm_ble_mesh_provision_instance_ctrl_t

struct rm_ble_mesh_provision_instance_ctrl_t

RM_BLE_MESH_PROVISION private control block. DO NOT MODIFY. Initialization occurs when RM_BLE_MESH_PROVISION_Open() is called.

Function Documentation

◆ RM_BLE_MESH_PROVISION_Open()

fsp_err_t RM_BLE_MESH_PROVISION_Open ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
rm_ble_mesh_provision_cfg_t const *const  p_cfg 
)

Open access middleware. This function registers the provisioning capabilities of the application along with the application callback to notify events during the provisioning procedure.

Implements rm_ble_mesh_provision_api_t::open.

Example:

/* Open the module. */
err = RM_BLE_MESH_PROVISION_Open(&g_ble_mesh_provision0_ctrl, &g_ble_mesh_provision0_cfg);
Return values
FSP_SUCCESSModule opened successfully.
FSP_ERR_ASSERTIONPointer to control block or configuration structure is NULL.
FSP_ERR_ALREADY_OPENModule is already open.
FSP_ERR_INVALID_STATELower layer is invalid state.

◆ RM_BLE_MESH_PROVISION_Close()

fsp_err_t RM_BLE_MESH_PROVISION_Close ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl)

Close access middleware. Implements rm_ble_mesh_provision_api_t::close.

Example:

/* Close the module. */
err = RM_BLE_MESH_PROVISION_Close(&g_ble_mesh_provision0_ctrl);
Return values
FSP_SUCCESSModule successfully closed.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_STATELower layer is invalid state.

◆ RM_BLE_MESH_PROVISION_Setup()

fsp_err_t RM_BLE_MESH_PROVISION_Setup ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
rm_ble_mesh_provision_role_t  role,
rm_ble_mesh_provision_device_info_t  info,
uint16_t  timeout 
)

Setup the device for provisioning. This function configures the device to get in a provisionable state by specifying the role, bearer and creating a context.

Implements rm_ble_mesh_provision_api_t::setup.

Example:

/* Setup the device for provisioning. */
err = RM_BLE_MESH_PROVISION_Setup(&g_ble_mesh_provision0_ctrl, role, info, timeout);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_POINTERThe parameter info->p_device is NULL.
FSP_ERR_OUT_OF_MEMORYMemory allocation is failed.
FSP_ERR_OVERFLOWTX queue is full.
FSP_ERR_INVALID_ARGUMENTInput parameter is invalid.
FSP_ERR_INVALID_STATELower layer is invalid state.

◆ RM_BLE_MESH_PROVISION_Bind()

fsp_err_t RM_BLE_MESH_PROVISION_Bind ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
rm_ble_mesh_provision_device_info_t  info,
uint8_t  attention,
rm_ble_mesh_provision_handle_t *const  p_handle 
)

Bind to the peer device for provisioning. This function establishes a provisioning link with the peer device and exchanges the capabilities for provisioning.

Implements rm_ble_mesh_provision_api_t::bind.

Example:

/* Bind to the peer device for provisioning. */
err = RM_BLE_MESH_PROVISION_Bind(&g_ble_mesh_provision0_ctrl, info, attention, &provision_handle);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_POINTERThe parameter p_handle is NULL.
FSP_ERR_OUT_OF_MEMORYMemory allocation is failed.
FSP_ERR_OVERFLOWTX queue is full.
FSP_ERR_INVALID_ARGUMENTInput parameter is invalid.
FSP_ERR_INVALID_STATELower layer is invalid state.

◆ RM_BLE_MESH_PROVISION_SendPdu()

fsp_err_t RM_BLE_MESH_PROVISION_SendPdu ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
rm_ble_mesh_provision_handle_t const *const  p_handle,
rm_ble_mesh_provision_pdu_type_t  type,
rm_ble_mesh_buffer_t  pdu_data 
)

Send provisioning PDUs to the peer. This function is used by the provisioning application to send the provisioning PDUs to the peer device during the procedure.

Implements rm_ble_mesh_provision_api_t::sendPdu.

Example:

/* Send provisioning PDUs to the peer. */
err = RM_BLE_MESH_PROVISION_SendPdu(&g_ble_mesh_provision0_ctrl, &provision_handle, type, pdu_data);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_POINTERThe parameter p_handle is NULL.
FSP_ERR_UNSUPPORTEDThe pdu type is not supported.
FSP_ERR_INVALID_ARGUMENTInput parameter is invalid.

◆ RM_BLE_MESH_PROVISION_SetAuthVal()

fsp_err_t RM_BLE_MESH_PROVISION_SetAuthVal ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
rm_ble_mesh_provision_handle_t const *const  p_handle,
rm_ble_mesh_buffer_t  auth_value 
)

Set the display authval. This function shall be used by the provisioning application to set the authval being displayed to the user on receiving RM_BLE_MESH_PROVISION_EVENT_TYPE_OOB_DISPLAY event with the respective OOB Action and Size.

Implements rm_ble_mesh_provision_api_t::setAuthVal.

Example:

rm_ble_mesh_buffer_t auth_value = {.payload = NULL, .length = 0};;
/* Set the display authval. */
err = RM_BLE_MESH_PROVISION_SetAuthVal(&g_ble_mesh_provision0_ctrl, &provision_handle, auth_value);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_handle is NULL.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_BLE_MESH_PROVISION_Abort()

fsp_err_t RM_BLE_MESH_PROVISION_Abort ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
rm_ble_mesh_provision_handle_t const *const  p_handle,
rm_ble_mesh_provision_link_close_reason_t  reason 
)

Abort the provisioning procedure. This API can be used by the application to abort the ongoing provisioning procedure. This routine closes the provisioning link with the reason as specified.

Implements rm_ble_mesh_provision_api_t::abort.

Example:

/* Abort the provisioning procedure. */
err = RM_BLE_MESH_PROVISION_Abort(&g_ble_mesh_provision0_ctrl, &provision_handle, reason);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_handle is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_ARGUMENTInput parameter is invalid.
FSP_ERR_INVALID_STATELower layer is invalid state.

◆ RM_BLE_MESH_PROVISION_GetLocalPublicKey()

fsp_err_t RM_BLE_MESH_PROVISION_GetLocalPublicKey ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
uint8_t *const  p_public_key 
)

Utility API to get current ECDH public key to be used for provisioning. This API can be used by the application to fetch the current ECDH P256 Public Key which is to be used for the Provisioning Procedure.

Implements rm_ble_mesh_provision_api_t::getLocalPublicKey.

Example:

/* Get current ECDH Public Key to be used for Provisioning. */
err = RM_BLE_MESH_PROVISION_GetLocalPublicKey(&g_ble_mesh_provision0_ctrl, &public_key);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_public_key is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_ARGUMENTInput parameter is invalid.

◆ RM_BLE_MESH_PROVISION_SetLocalPublicKey()

fsp_err_t RM_BLE_MESH_PROVISION_SetLocalPublicKey ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
uint8_t const *const  p_public_key 
)

Utility API to set current ECDH public key to be used for provisioning. This API can be used by the application to fetch the current ECDH P256 Public Key which is to be used for the Provisioning Procedure.

Implements rm_ble_mesh_provision_api_t::setLocalPublicKey.

Example:

/* Set current ECDH Public Key to be used for Provisioning. */
err = RM_BLE_MESH_PROVISION_SetLocalPublicKey(&g_ble_mesh_provision0_ctrl, &public_key);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_public_key is NULL.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_ARGUMENTInput parameter is invalid.

◆ RM_BLE_MESH_PROVISION_GenerateRandomizedNumber()

fsp_err_t RM_BLE_MESH_PROVISION_GenerateRandomizedNumber ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
uint8_t *const  p_key 
)

Utility API to generate 128bits (16 bytes) randomized number to be used for provisioning. The randomized number can be used for UUID, Net Key and Application Key.

Implements rm_ble_mesh_provision_api_t::generateRandomizedNumber.

Example:

/* Generate 128bits (16 bytes) randomized number. */
err = RM_BLE_MESH_PROVISION_GenerateRandomizedNumber(&g_ble_mesh_provision0_ctrl, p_net_key);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_key is NULL.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_BLE_MESH_PROVISION_SetOobPublicKey()

fsp_err_t RM_BLE_MESH_PROVISION_SetOobPublicKey ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
uint8_t const *const  p_key,
uint8_t  size 
)

Utility API to set device out of band public key for provisioning.

Implements rm_ble_mesh_provision_api_t::setOobPublicKey.

Example:

/* Set device out of band public key. */
err = RM_BLE_MESH_PROVISION_SetOobPublicKey(&g_ble_mesh_provision0_ctrl, p_public_key, size);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_key is NULL.
FSP_ERR_INVALID_ARGUMENTThe parameter size is more than 64.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_BLE_MESH_PROVISION_SetOobAuthInfo()

fsp_err_t RM_BLE_MESH_PROVISION_SetOobAuthInfo ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
uint8_t const *const  p_auth_info,
uint8_t  size 
)

Utility API to set device out of band authentication information for provisioning.

Implements rm_ble_mesh_provision_api_t::setOobAuthInfo.

Example:

/* Set device out of band authentication information. */
err = RM_BLE_MESH_PROVISION_SetOobAuthInfo(&g_ble_mesh_provision0_ctrl, p_auth_info, size);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_auth_info is NULL.
FSP_ERR_INVALID_ARGUMENTThe parameter size is more than 16.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_BLE_MESH_PROVISION_GenerateEcdhKey()

fsp_err_t RM_BLE_MESH_PROVISION_GenerateEcdhKey ( rm_ble_mesh_provision_ctrl_t *const  p_ctrl,
uint8_t *const  p_public_key 
)

Utility API to generate ECDH public key to be used for provisioning.

Implements rm_ble_mesh_provision_api_t::generateEcdhKey.

Example:

/* Generate ECDH Public Key for Provisioning. */
err = RM_BLE_MESH_PROVISION_GenerateEcdhKey(&g_ble_mesh_provision0_ctrl, &public_key);
Return values
FSP_SUCCESSOperation succeeded.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_INVALID_POINTERThe parameter p_public_key is NULL.
FSP_ERR_NOT_OPENModule is not open.