provisioning.h File Reference

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...

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

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 }
	Provisioning result. More...
enum	provisioning_method_e { PROV_METHOD_UNSECURED = 0, PROV_METHOD_SECURED = 1, PROV_METHOD_EXTENDED_UID = 3, PROV_METHOD_KEY_MGMT = 4 }
	supported provisioning methods 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 60 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 126 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 73 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.

Returns

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

Examples

provisioning_joining_node/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_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 96 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_conf_t

struct provisioning_conf_t

This structure holds the provisioning parameters.

Examples

provisioning_joining_node/app.c.

Definition at line 135 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.
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.
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.
app_lib_settings_key_management_configuration_t *	p_key_mgmt_config	Optional key management configuration for scalable key management.
uint16_t	timeout_s	Timeout in seconds (typ. 10sec for LL and 120sec for LE network)
const uint8_t *	uid	UID of the node
uint8_t	uid_len	Length of the UID buffer.
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 172 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.

Enumeration Type Documentation

provisioning_method_e

enum provisioning_method_e

supported provisioning methods

Enumerator
PROV_METHOD_UNSECURED	Unsecured provisioning method.
PROV_METHOD_SECURED	Secured provisioning method.
PROV_METHOD_EXTENDED_UID	Extended UID provisioning method.
PROV_METHOD_KEY_MGMT	Scalable key management method.

Definition at line 44 of file provisioning.h.

{
    PROV_METHOD_UNSECURED = 0, 
    PROV_METHOD_SECURED = 1, 
    PROV_METHOD_EXTENDED_UID = 3, 
    PROV_METHOD_KEY_MGMT = 4, 
} provisioning_method_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, ...).

Definition at line 27 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 
} 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 16 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;

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 90 of file provisioning.h.