Go to the source code of this file.

Typedefs
typedef bool(*	provisioning_end_cb_f) (provisioning_res_e result)
	The end provisioning callback. This function is called at the end of the provisioning process. More...

typedef void(*	provisioning_user_data_cb_f) (uint32_t id, CborType type, uint8_t *data, uint8_t len)
	Received User provisioning data callback. Provisioning data is received as a map of id:data. This function is callback for each id that are not reserved by Wirepas. More...

typedef bool(*	provisioning_proxy_start_cb_f) (const uint8_t uid, uint8_t uid_len, provisioning_method_e method, provisioning_proxy_net_param_t net_param)
	The proxy received START packet callback. This function is called when the proxy receives a valid START packet from a new node. More...

Functions
provisioning_ret_e	Provisioning_init (provisioning_conf_t *conf)
	Initialize the provisioning process. More...

provisioning_ret_e	Provisioning_start (void)
	Start the provisioning process. More...

provisioning_ret_e	Provisioning_stop (void)
	Stops the provisioning process. More...

provisioning_ret_e	Provisioning_Proxy_init (provisioning_proxy_conf_t *conf)
	Initialize the provisioning proxy. More...

provisioning_ret_e	Provisioning_Proxy_start (void)
	Start sending joining beacons. Provisioning packets will be forwarded to provisioning server or treated locally if local provisioning is enabled. More...

provisioning_ret_e	Provisioning_Proxy_stop (void)
	Stops the provisioning proxy. More...

provisioning_ret_e	Provisioning_settings_write (const provisioning_settings_t *settings)
	Writes provisioning settings to the secure storage. More...

provisioning_ret_e	Provisioning_settings_read (provisioning_settings_t *settings)
	Reads provisioning settings from the secure storage. More...

provisioning_ret_e	Provisioning_init_from_storage (provisioning_conf_t *conf)
	Initialize the provisioning process with provisioning settings from the secure storage. More...

Data Structures
struct	provisioning_proxy_net_param_t
	This structure contains the network parameters sent by the provisioning proxy to the new node. More...

union	provisioning_uid_t

struct	provisioning_settings_t
	This structure contains the provisioning settings stored in the secure storage. More...

struct	provisioning_conf_t
	This structure contains all provisioning related parameters. More...

struct	provisioning_proxy_conf_t
	This structure holds the joining proxy parameters. More...

struct	provisioning_uid_t.__unnamed__

struct	provisioning_settings_t.prov_keys

Enumerations
enum	provisioning_ret_e { PROV_RET_OK = 0, PROV_RET_INVALID_STATE = 1, PROV_RET_INVALID_PARAM = 2, PROV_RET_INVALID_DATA = 3, PROV_RET_JOINING_LIB_ERROR = 4, PROV_RET_INTERNAL_ERROR = 5 }
	Return codes of provisioning functions. More...

enum	provisioning_res_e { PROV_RES_SUCCESS = 0, PROV_RES_TIMEOUT = 1, PROV_RES_NACK = 2, PROV_RES_INVALID_DATA = 3, PROV_RES_INVALID_PACKET = 4, PROV_RES_ERROR_SENDING_DATA = 5, PROV_RES_ERROR_SCANNING_BEACONS = 6, PROV_RES_ERROR_JOINING = 7, PROV_RES_ERROR_NO_ROUTE = 8, PROV_RES_STOPPED = 9, PROV_RES_ERROR_INTERNAL = 10, PROV_RES_ERROR_FAILSAFE = 11 }
	Provisioning result. More...

enum	provisioning_method_flag_e { PROV_METHOD_FLAG_SECURED = 0b0001, PROV_METHOD_FLAG_EXTENDED_UID = 0b0010, PROV_METHOD_FLAG_KEY_MGMT = 0b0100 }
	Supported provisioning method bit flags. More...

enum	provisioning_method_e { PROV_METHOD_UNSECURED = 0x0, PROV_METHOD_SECURED = PROV_METHOD_FLAG_SECURED, PROV_METHOD_EXTENDED_UID, PROV_METHOD_EXTENDED_UID_KEY_MGMT }
	Provisioning methods. More...

Macros
#define	PROV_UUID_SIZE_BYTES 16

#define	PROV_KEY_SIZE_BYTES 16
	All security keys are 16 bytes long. More...

#define	PROV_UID_MAX_SIZE_BYTES 79
	Maximum size of provisioning UID. More...

#define	PROV_AUTH_UID_SIZE_BYTES 16
	Authenticator UID size. More...

#define	PROV_METHOD_IS_UNSECURED(x) ((x) == 0)
	Macro to check whether method is unsecured. More...

#define	PROV_METHOD_IS_SECURED(x) (((x) & PROV_METHOD_FLAG_SECURED) != 0)
	Macro to check whether method is secured. More...

#define	PROV_METHOD_IS_EXTENDED_UID(x) (((x) & PROV_METHOD_FLAG_EXTENDED_UID) != 0)
	Macro to check whether secure method uses extended UID. More...

#define	PROV_METHOD_IS_KEY_MGMT(x) (((x) & PROV_METHOD_FLAG_KEY_MGMT) != 0)
	Macro to check whether secure method uses scalable key management. More...

Variables
const typedef app_lib_joining_received_beacon_t (	provisioning_joining_beacon_cb_f )(const app_lib_joining_received_beacon_t *beacons)
	Selects which joining beacon to connect to at the end of a scan. More...

Typedef Documentation

◆ provisioning_end_cb_f

typedef bool(* provisioning_end_cb_f) (provisioning_res_e result)

The end provisioning callback. This function is called at the end of the provisioning process.

Parameters

result Result of the provisioning process.

Returns: True: Apply received network parameters and reboot; False: discard data and end provisioning process.

Definition at line 143 of file provisioning.h.

◆ provisioning_proxy_start_cb_f

typedef bool(* provisioning_proxy_start_cb_f) (const uint8_t *uid, uint8_t uid_len, provisioning_method_e method, provisioning_proxy_net_param_t *net_param)

The proxy received START packet callback. This function is called when the proxy receives a valid START packet from a new node.

Note: Local provisioning must be activated for the proxy to be able to receive provisioning packet in the application. Otherwise they are directly forwarded by the stack to the Sink.

Parameters

uid	A pointer to the node UID.
uid_len	The size in bytes of the UID
method	The provisioning method requested by the new node.
net_param	If returning true, the callback must fill this structure with the network parameters that will be sent to the new node.

Returns: true: Send provisioning data to this node; false: discard the node request and reply with a NACK.

Definition at line 209 of file provisioning.h.

◆ provisioning_user_data_cb_f

typedef void(* provisioning_user_data_cb_f) (uint32_t id, CborType type, uint8_t *data, uint8_t len)

Received User provisioning data callback. Provisioning data is received as a map of id:data. This function is callback for each id that are not reserved by Wirepas.

Parameters

id	Id of the received item.
data	Received data.
len	Length of the data.

Definition at line 156 of file provisioning.h.

Function Documentation

◆ Provisioning_init()

provisioning_ret_e Provisioning_init ( provisioning_conf_t * conf )

Initialize the provisioning process.

Note: If Provisioning is used, App_scheduler and Shared_data MUST BE initialized in App_Init of the application. Also lib_system->setShutdownCb() function offered by system library MUST NOT be used outside of this module. If Joining is used, lib_joining->startJoiningBeaconRx() function offered by Joining library and lib_state->setRouteCb() function offered by State library MUST NOT be used outside of this module.; When using provisioning application must use Shared_data instead of data library for sending and receiving packets.

Parameters

conf	Configuration for the provisioning. If conf is NULL, the library only registers the callbacks to receive provisioning configuration over Remote API and then returns with PROV_RET_INVALID_DATA.

Returns: Result code, PROV_RET_OK if provisioning is initialized. PROV_RET_INVALID_DATA if called with conf == NULL (to distinguish from other errors) See provisioning_ret_e for other return codes.

Examples: provisioning_joining_node/app.c.

◆ Provisioning_init_from_storage()

provisioning_ret_e Provisioning_init_from_storage ( provisioning_conf_t * conf )

Initialize the provisioning process with provisioning settings from the secure storage.

Parameters

conf	Configuration defining callback functions for provisioning.

Returns: Result code, PROV_RET_OK if provisioning is initialized. See provisioning_ret_e for other return codes.

Examples: dualmcu_app/app.c.

◆ Provisioning_Proxy_init()

provisioning_ret_e Provisioning_Proxy_init ( provisioning_proxy_conf_t * conf )

Initialize the provisioning proxy.

Note: If Provisioning Proxy is used, Shared_data MUST BE initialized in App_Init of the application.; If local provisioning is enabled, provisioning request sent by new node will be treated locally by this library instead of being forwarded to the provisioning server.

Parameters

conf	Configuration for the provisioning proxy.

Returns: Result code, PROV_RET_OK if proxy is initialized. See provisioning_ret_e for other return codes.

Examples: provisioning_proxy/app.c.

◆ Provisioning_Proxy_start()

provisioning_ret_e Provisioning_Proxy_start ( void )

Start sending joining beacons. Provisioning packets will be forwarded to provisioning server or treated locally if local provisioning is enabled.

Returns: Result code, PROV_RET_OK if proxy has started. See provisioning_ret_e for other return codes.

Examples: provisioning_proxy/app.c.

◆ Provisioning_Proxy_stop()

provisioning_ret_e Provisioning_Proxy_stop ( void )

Stops the provisioning proxy.

Note: All packet filter callbacks are freed.

Returns: Result code, PROV_RET_OK if proxy has stopped. See provisioning_ret_e for other return codes.

Examples: provisioning_proxy/app.c.

◆ Provisioning_settings_read()

provisioning_ret_e Provisioning_settings_read ( provisioning_settings_t * settings )

Reads provisioning settings from the secure storage.

Parameters

settings Pointer to provisioning settings structure for storing read configuration.

Returns: Result code, PROV_RET_OK if configuration has been read successfully, PROV_RET_INVALID_PARAM otherwise.

◆ Provisioning_settings_write()

provisioning_ret_e Provisioning_settings_write ( const provisioning_settings_t * settings )

Writes provisioning settings to the secure storage.

Parameters

settings Pointer to provisioning settings structure to be written to the secure storage.

Returns: Result code, PROV_RET_OK if configuration has been written successfully, PROV_RET_INVALID_PARAM otherwise.

◆ Provisioning_start()

provisioning_ret_e Provisioning_start ( void )

Start the provisioning process.

Returns: Result code, PROV_RET_OK if provisioning has started. See provisioning_ret_e for other return codes.

Examples: provisioning_joining_node/app.c.

◆ Provisioning_stop()

provisioning_ret_e Provisioning_stop ( void )

Stops the provisioning process.

Note: All taken callback, packet received filter and tasks are freed.; Stop is not immediate, it takes approximately 100ms.

Returns: Result code, PROV_RET_OK if provisioning has stopped. See provisioning_ret_e for other return codes.

Data Structure Documentation

◆ provisioning_proxy_net_param_t

struct provisioning_proxy_net_param_t

This structure contains the network parameters sent by the provisioning proxy to the new node.

Examples: provisioning_proxy/app.c.

Definition at line 179 of file provisioning.h.

Data Fields
uint8_t	auth_key[APP_LIB_SETTINGS_AES_KEY_NUM_BYTES]	The network authentication key.
uint8_t	enc_key[APP_LIB_SETTINGS_AES_KEY_NUM_BYTES]	The network encryption key.
app_lib_settings_net_addr_t	net_addr	The network address.
app_lib_settings_net_channel_t	net_chan	The network channel.

◆ provisioning_uid_t

union provisioning_uid_t

Examples: provisioning_proxy/app.c.

Definition at line 215 of file provisioning.h.

Data Fields
struct provisioning_uid_t	__unnamed__
uint8_t	uid[79]

◆ provisioning_settings_t

struct provisioning_settings_t

This structure contains the provisioning settings stored in the secure storage.

Definition at line 236 of file provisioning.h.

Data Fields
provisioning_method_e	method	The provisioning method that the node wants to use.
uint8_t	nb_retry	How many retries are allowed to receive provisioning data.
struct provisioning_settings_t	prov_keys	Key used for provisioning, [16B AK][16B EK] for Secured method. This implementation of the provisioning protocol only supports the factory key.
provisioning_uid_t	prov_uid	UID of the node
uint8_t	prov_uid_len	Length of the UID buffer.
uint16_t	timeout_s	Timeout in seconds (typ. 10sec for LL and 120sec for LE network)

◆ provisioning_conf_t

struct provisioning_conf_t

This structure contains all provisioning related parameters.

Examples: dualmcu_app/app.c, and provisioning_joining_node/app.c.

Definition at line 263 of file provisioning.h.

Data Fields
provisioning_joining_beacon_cb_f	beacon_joining_cb	Beacon joining callback. Needed if use_joining is true.
provisioning_end_cb_f	end_cb	End provisioning callback.
provisioning_settings_t	settings	Provisioning settings.
provisioning_user_data_cb_f	user_data_cb	Data provisioning callback.

◆ provisioning_proxy_conf_t

struct provisioning_proxy_conf_t

This structure holds the joining proxy parameters.

Note: Local provisioning is enabled if unsecured or secured method is allowed. When local provisioning is enabled the provisioning packets are treated locally by the proxy and are not forwarded anymore to the Sink / Provisioning server.

Examples: provisioning_proxy/app.c.

Definition at line 282 of file provisioning.h.

Data Fields
bool	is_local_sec_allowed	Is local secured provisioning method allowed.
bool	is_local_unsec_allowed	Is local unsecured provisioning method allowed.
const uint8_t *	key	Key used for provisioning, [16B AK][16B EK] for Secured method. This implementation of the provisioning protocol only supports the factory key.
uint8_t	key_len	Length of the key. Secure method expects 32 bytes keys.
uint8_t	num_bytes	Joining beacons payload number of bytes.
uint8_t *	payload	Joining beacons payload.
provisioning_proxy_start_cb_f	start_cb	The received START packet callback.
int8_t	tx_power	Transmission power to use for sending joining beacons, in dBm.

◆ provisioning_uid_t.unnamed

struct provisioning_uid_t.__unnamed__

Definition at line 218 of file provisioning.h.

Data Fields
uint8_t	authenticator_uid[16]	Authenticator UID (used when PROV_METHOD_FLAG_EXTENDED_UID is set in the prov method)
uint8_t	authenticator_uid_type	Authenticator UID type (used when PROV_METHOD_FLAG_EXTENDED_UID is set in the prov method)
uint8_t	node_uid[16]	Node UID (used when PROV_METHOD_FLAG_EXTENDED_UID is set in the prov method)
uint8_t	node_uid_type	Node UID type (used when PROV_METHOD_FLAG_EXTENDED_UID is set in the prov method)

◆ provisioning_settings_t.prov_keys

struct provisioning_settings_t.prov_keys

Key used for provisioning, [16B AK][16B EK] for Secured method. This implementation of the provisioning protocol only supports the factory key.

Definition at line 253 of file provisioning.h.

Data Fields
uint8_t	auth_key[16]	Authentication key
uint8_t	enc_key[16]	Encryption key

Enumeration Type Documentation

◆ provisioning_method_e

enum provisioning_method_e

Provisioning methods.

Enumerator
PROV_METHOD_UNSECURED	Unsecured provisioning, normal UID.
PROV_METHOD_SECURED	Secure provisioning, normal UID.
PROV_METHOD_EXTENDED_UID	Secure provisioning, extended UID.
PROV_METHOD_EXTENDED_UID_KEY_MGMT	Secure provisioning, extended UID and scalable key management.

Definition at line 89 of file provisioning.h.

 {
     PROV_METHOD_UNSECURED = 0x0,
  
     PROV_METHOD_SECURED = PROV_METHOD_FLAG_SECURED,
  
     PROV_METHOD_EXTENDED_UID = PROV_METHOD_FLAG_SECURED |
                                PROV_METHOD_FLAG_EXTENDED_UID,
  
     PROV_METHOD_EXTENDED_UID_KEY_MGMT = PROV_METHOD_FLAG_SECURED      |
                                         PROV_METHOD_FLAG_EXTENDED_UID |
                                         PROV_METHOD_FLAG_KEY_MGMT,
 } provisioning_method_e;

◆ provisioning_method_flag_e

enum provisioning_method_flag_e

Supported provisioning method bit flags.

Enumerator
PROV_METHOD_FLAG_SECURED	First bit defines whether secured provisioning is used.
PROV_METHOD_FLAG_EXTENDED_UID	Second bit is set if extended UID is used.
PROV_METHOD_FLAG_KEY_MGMT	Third bit if scalable key management is used.

Definition at line 68 of file provisioning.h.

 {
     PROV_METHOD_FLAG_SECURED      = 0b0001,
  
     PROV_METHOD_FLAG_EXTENDED_UID = 0b0010,
  
     PROV_METHOD_FLAG_KEY_MGMT     = 0b0100,
 } provisioning_method_flag_e;

◆ provisioning_res_e

enum provisioning_res_e

Provisioning result.

Enumerator
PROV_RES_SUCCESS	Provisioning is a success.
PROV_RES_TIMEOUT	Timeout during provisioning.
PROV_RES_NACK	Provisioning server returned a NACK.
PROV_RES_INVALID_DATA	Received provisioning data is invalid.
PROV_RES_INVALID_PACKET	Received packet badly formatted.
PROV_RES_ERROR_SENDING_DATA	Problem when sending packet.
PROV_RES_ERROR_SCANNING_BEACONS	Error while scanning for joining beacons.
PROV_RES_ERROR_JOINING	Error during joining process.
PROV_RES_ERROR_NO_ROUTE	No route to host after joining network.
PROV_RES_STOPPED	Application called stop function.
PROV_RES_ERROR_INTERNAL	Internal error (no more task, ...).
PROV_RES_ERROR_FAILSAFE

Definition at line 48 of file provisioning.h.

 {
     PROV_RES_SUCCESS = 0, 
     PROV_RES_TIMEOUT = 1, 
     PROV_RES_NACK = 2, 
     PROV_RES_INVALID_DATA = 3, 
     PROV_RES_INVALID_PACKET = 4, 
     PROV_RES_ERROR_SENDING_DATA = 5, 
     PROV_RES_ERROR_SCANNING_BEACONS = 6, 
     PROV_RES_ERROR_JOINING = 7, 
     PROV_RES_ERROR_NO_ROUTE = 8, 
     PROV_RES_STOPPED = 9, 
     PROV_RES_ERROR_INTERNAL = 10, 
     PROV_RES_ERROR_FAILSAFE = 11
 } provisioning_res_e;

◆ provisioning_ret_e

enum provisioning_ret_e

Return codes of provisioning functions.

Enumerator
PROV_RET_OK	Operation is a success.
PROV_RET_INVALID_STATE	Provisioning not in a valid state.
PROV_RET_INVALID_PARAM	Invalid parameters.
PROV_RET_INVALID_DATA	Invalid data.
PROV_RET_JOINING_LIB_ERROR	Joining library error.
PROV_RET_INTERNAL_ERROR	Internal error (no more task, ...).

Definition at line 37 of file provisioning.h.

 {
     PROV_RET_OK = 0, 
     PROV_RET_INVALID_STATE = 1, 
     PROV_RET_INVALID_PARAM = 2, 
     PROV_RET_INVALID_DATA = 3, 
     PROV_RET_JOINING_LIB_ERROR = 4, 
     PROV_RET_INTERNAL_ERROR = 5, 
 } provisioning_ret_e;

Macro Definition Documentation

◆ PROV_AUTH_UID_SIZE_BYTES

#define PROV_AUTH_UID_SIZE_BYTES 16

Authenticator UID size.

Examples: provisioning_proxy/app.c.

Definition at line 34 of file provisioning.h.

◆ PROV_KEY_SIZE_BYTES

#define PROV_KEY_SIZE_BYTES 16

All security keys are 16 bytes long.

Definition at line 24 of file provisioning.h.

◆ PROV_METHOD_IS_EXTENDED_UID

#define PROV_METHOD_IS_EXTENDED_UID ( x ) (((x) & PROV_METHOD_FLAG_EXTENDED_UID) != 0)

Macro to check whether secure method uses extended UID.

Examples: provisioning_proxy/app.c.

Definition at line 128 of file provisioning.h.

◆ PROV_METHOD_IS_KEY_MGMT

#define PROV_METHOD_IS_KEY_MGMT ( x ) (((x) & PROV_METHOD_FLAG_KEY_MGMT) != 0)

Macro to check whether secure method uses scalable key management.

Definition at line 133 of file provisioning.h.

◆ PROV_METHOD_IS_SECURED

#define PROV_METHOD_IS_SECURED ( x ) (((x) & PROV_METHOD_FLAG_SECURED) != 0)

Macro to check whether method is secured.

Definition at line 123 of file provisioning.h.

◆ PROV_METHOD_IS_UNSECURED

#define PROV_METHOD_IS_UNSECURED ( x ) ((x) == 0)

Macro to check whether method is unsecured.

Definition at line 118 of file provisioning.h.

◆ PROV_UID_MAX_SIZE_BYTES

#define PROV_UID_MAX_SIZE_BYTES 79

Maximum size of provisioning UID.

Definition at line 29 of file provisioning.h.

◆ PROV_UUID_SIZE_BYTES

#define PROV_UUID_SIZE_BYTES 16

UUID size in bytes as per RFC 4122 Section 4.1 "The UUID format is 16 octets"

Examples: provisioning_proxy/app.c.

Definition at line 19 of file provisioning.h.

Variable Documentation

◆ provisioning_joining_beacon_cb_f

const typedef app_lib_joining_received_beacon_t*(* provisioning_joining_beacon_cb_f) (const app_lib_joining_received_beacon_t *beacons)

Selects which joining beacon to connect to at the end of a scan.

Note: Joining network selection is up to the application. Any algorithm can be implemented for example by looking at the content of the beacon payload, or the network (address and channel) the node sending the beacons is connected to.

Parameters

beacons A buffer of joining beacons.

Returns: The selected beacon.

Definition at line 173 of file provisioning.h.

Typedefs

Functions

Data Structures

Enumerations

Macros

Variables

Typedef Documentation

◆ provisioning_end_cb_f

◆ provisioning_proxy_start_cb_f

◆ provisioning_user_data_cb_f

Function Documentation

◆ Provisioning_init()

◆ Provisioning_init_from_storage()

◆ Provisioning_Proxy_init()

◆ Provisioning_Proxy_start()

◆ Provisioning_Proxy_stop()

◆ Provisioning_settings_read()

◆ Provisioning_settings_write()

◆ Provisioning_start()

◆ Provisioning_stop()

Data Structure Documentation

◆ provisioning_proxy_net_param_t

◆ provisioning_uid_t

◆ provisioning_settings_t

◆ provisioning_conf_t

◆ provisioning_proxy_conf_t

◆ provisioning_uid_t.__unnamed__

◆ provisioning_settings_t.prov_keys

Enumeration Type Documentation

◆ provisioning_method_e

◆ provisioning_method_flag_e

◆ provisioning_res_e

◆ provisioning_ret_e

Macro Definition Documentation

◆ PROV_AUTH_UID_SIZE_BYTES

◆ PROV_KEY_SIZE_BYTES

◆ PROV_METHOD_IS_EXTENDED_UID

◆ PROV_METHOD_IS_KEY_MGMT

◆ PROV_METHOD_IS_SECURED

◆ PROV_METHOD_IS_UNSECURED

◆ PROV_UID_MAX_SIZE_BYTES

◆ PROV_UUID_SIZE_BYTES

Variable Documentation

◆ provisioning_joining_beacon_cb_f

◆ provisioning_uid_t.unnamed