Thread commissioning API. More...

Data Structures
struct	thread_commissioning_link_configuration
	Interfaces needed for native commissioner. More...
Typedefs
typedef int(	thread_commissioning_status_cb )(int8_t interface_id, uint16_t commissioner_session_id, commissioning_state_e state)
	Commissioning petition response callback.
typedef int(	thread_commissioning_joiner_finalisation_cb )(int8_t interface_id, uint8_t EUI64[8], uint8_t *message_ptr, uint16_t message_len)
	Callback received when a new device is completing the joining process.
typedef struct thread_commissioning_link_configuration	thread_commissioning_link_configuration_s
	Interfaces needed for native commissioner.
typedef void	thread_commissioning_native_select_cb (int8_t interface_id, uint8_t count, thread_commissioning_link_configuration_s *link_ptr)
	Native commissioner network scan result callback.
Enumerations
enum	commissioning_state_e
	/enum commissioning_state_e /brief Commissioning states. More...
Functions
int	thread_commissioning_register (int8_t interface_id, uint8_t PSKc[16])
	Register the commissioner interface.
int	thread_commissioning_unregister (int8_t interface_id)
	Unregister the commissioner interface.
int	thread_commissioning_petition_start (int8_t interface_id, char commissioner_id_ptr, thread_commissioning_status_cb status_cb_ptr)
	Start the commissioning petition.
int	thread_commissioning_petition_keep_alive (int8_t interface_id, commissioning_state_e state)
	Send petition keep alive.
int	thread_commissioning_device_add (int8_t interface_id, bool short_eui64, uint8_t EUI64[8], uint8_t PSKd_ptr, uint8_t PSKd_len, thread_commissioning_joiner_finalisation_cb joining_device_cb_ptr)
	Add a device to commission to the Thread network.
int	thread_commissioning_device_delete (int8_t interface_id, uint8_t EUI64[8])
	Delete a device to commission to the Thread network.
void *	thread_commission_device_get_next (void ptr, int8_t interface_id, bool short_eui64, uint8_t EUI64[8], uint8_t PSKd[32], uint8_t *PSKd_len)
	Get next added device details.
int	thread_commissioning_native_commissioner_start (int8_t interface_id, thread_commissioning_native_select_cb *cb_ptr)
	Native commissioner network scan start.
int	thread_commissioning_native_commissioner_stop (int8_t interface_id)
	Native commissioner network scan stop.
int	thread_commissioning_native_commissioner_connect (int8_t interface_id, thread_commissioning_link_configuration_s *link_ptr)
	Native commissioner connect.
int	thread_commissioning_native_commissioner_get_connection_info (int8_t interface_id, uint8_t address_ptr, uint16_t port)
	Get the address of the native commissioner parent and the commissioning port for the connection.
int8_t	thread_commissioning_get_management_id (int8_t interface_id)
	Get the management instance ID from the commissioner interface.

Detailed Description

Thread commissioning API.

This is a public API used for creating a commissioning device. You can create an on-mesh commissioner and a native commissioner.

Definition in file thread_commissioning_api.h.

Typedef Documentation

typedef int( thread_commissioning_joiner_finalisation_cb)(int8_t interface_id, uint8_t EUI64[8], uint8_t *message_ptr, uint16_t message_len)

Callback received when a new device is completing the joining process.

The message may include the following meshcop TLV fields: * State TLV * Vendor Name TLV * Vendor Model TLV * Vendor SW Version TLV * Vendor Data TLV * Vendor Stack * Version TLV * Provisioning URL TLV

Parameters:

interface_id	Network interface ID. The request comes from this ID.
EUI64	The client identifier.
message_ptr	A message including the meshcop TLV set. This message can be parsed using thread_meshcop_lib.h.
message_len	The length of the message.

Returns:: 0 Device accepted.; Any other value, device rejected.

Definition at line 124 of file thread_commissioning_api.h.

typedef struct thread_commissioning_link_configuration thread_commissioning_link_configuration_s

Interfaces needed for native commissioner.

current design:

The application configures the interface to scan available Thread networks to join
- Time passes and the user wants to start scanning for native commissioner networks.
The application configures the interface to begin native commissioner interface scans.
The application selects a network to connect to.
The stack connects to that network -> interface UP event sent.
The application starts using Commissioning API to send COMM_PET.req message triggering a DTLS handshake.
- Commission API queries the leader address and native info and uses the one that works.

typedef void thread_commissioning_native_select_cb(int8_t interface_id, uint8_t count, thread_commissioning_link_configuration_s *link_ptr)

Native commissioner network scan result callback.

This callback is called when networks that allow native commissioner to join are found. Pointers are valid during this call.

Parameters:

interface_id	Interface ID of this Thread instance.
count	Count of link configurations
link_ptr	Poiner to Commissioning link configuration

Definition at line 194 of file thread_commissioning_api.h.

typedef int( thread_commissioning_status_cb)(int8_t interface_id, uint16_t commissioner_session_id, commissioning_state_e state)

Commissioning petition response callback.

Parameters:

interface_id	Network interface ID. The request comes from this ID.
commissioner_session_id	Commissioner session ID.
state	State of the commissioning.

Returns:: 0 success, other values failure.

Definition at line 53 of file thread_commissioning_api.h.

Enumeration Type Documentation

enum commissioning_state_e

/enum commissioning_state_e /brief Commissioning states.

Definition at line 38 of file thread_commissioning_api.h.

Function Documentation

void* thread_commission_device_get_next	(	void *	ptr,
		int8_t	interface_id,
		bool *	short_eui64,
		uint8_t	EUI64[8],
		uint8_t	PSKd[32],
		uint8_t *	PSKd_len
	)

Get next added device details.

Parameters:

ptr	A pointer for internal looping. First, use NULL pointer, after that use return pointer.
interface_id	Network interface ID. The request comes from this ID.
short_eui64	A boolean value indicating that short EUI version is used for bloom filter generation. Can be NULL when no result wanted.
EUI64	A pointer to EUI64 buffer. Can be NULL when no result wanted.
PSKd	A pointer to PSKd buffer. Can be NULL when no result wanted.
PSKd_len	Length of data in PSKd.

Returns:: >NULL for next iteration.; NULL when end of list.

int thread_commissioning_device_add	(	int8_t	interface_id,
		bool	short_eui64,
		uint8_t	EUI64[8],
		uint8_t *	PSKd_ptr,
		uint8_t	PSKd_len,
		thread_commissioning_joiner_finalisation_cb *	joining_device_cb_ptr
	)

Add a device to commission to the Thread network.

Parameters:

interface_id	Network interface ID. The request comes from this ID.
short_eui64	A boolean value indicating that short EUI version is used for bloom filter generation.
EUI64	A pointer to EUI64 buffer.
PSKd_ptr	A pointer to PSKd buffer.
PSKd_len	PSKd string length, current validity check is 1-32 bytes.
joining_device_cb_ptr	A callback function indicating the result of the operation. Can be NULL if no result code needed.

Returns:: 0 success, other values failure

int thread_commissioning_device_delete	(	int8_t	interface_id,
		uint8_t	EUI64[8]
	)

Delete a device to commission to the Thread network.

Parameters:

interface_id	Network interface ID. The request comes from this ID.
EUI64	A pointer to EUI64 buffer.

Returns:: 0 success, other values failure.

int8_t thread_commissioning_get_management_id ( int8_t interface_id )

Get the management instance ID from the commissioner interface.

Parameters:

interface_id Network interface ID.

Returns:: > 0 Instance ID.; <= 0 fail.

int thread_commissioning_native_commissioner_connect	(	int8_t	interface_id,
		thread_commissioning_link_configuration_s *	link_ptr
	)

Native commissioner connect.

Connects to a specific Thread network to become an active native commissioner.

This function can be called in any time. When the network scan is completed, the available native commissioner networks are listed using the callback.

If the connection fails, network scan keeps looking for a new network. After a successful connection, the interface up event is sent. TODO do we need backup timers or blacklist if PSKc fails. who is responsible for triggering new scans?

Matching of thread network is made using Network name, Xpanid, panid, TODO channel?? or not? gives channel flexibility

Parameters:

interface_id	Interface ID of this Thread instance.
link_ptr	Pointer to Commissioning link configuration.

Returns:: 0 success, other values failure.

int thread_commissioning_native_commissioner_get_connection_info	(	int8_t	interface_id,
		uint8_t *	address_ptr,
		uint16_t *	port
	)

Get the address of the native commissioner parent and the commissioning port for the connection.

Parameters:

interface_id	Network interface ID.
address_ptr	A pointer to address buffer (16 bytes) for the commission messages.
port	Return the port for the commissioner.

Returns:: 0, address OK.; <0 fail.

int thread_commissioning_native_commissioner_start	(	int8_t	interface_id,
		thread_commissioning_native_select_cb *	cb_ptr
	)

Native commissioner network scan start.

Starts the network scan mode to find networks where the device can become a native commissioner. This stops the normal Thread joining process and informs the application of available networks.

Parameters:

interface_id	Interface ID of this Thread instance.
cb_ptr	Callback function

Returns:: 0 success, other values failure.

int thread_commissioning_native_commissioner_stop ( int8_t interface_id )

Native commissioner network scan stop.

Stops the network scan mode and continues the normal joining process.

Parameters:

interface_id Interface ID of this Thread instance.

Returns:: 0 success, other values failure.

int thread_commissioning_petition_keep_alive	(	int8_t	interface_id,
		commissioning_state_e	state
	)

Send petition keep alive.

This function must be called in 40 second intervals. TODO rethink if this should be automatic.

Parameters:

interface_id	Network interface ID. The request comes from this ID.
state	Commissioning state.

Returns:: 0 success, other values failure.

int thread_commissioning_petition_start	(	int8_t	interface_id,
		char *	commissioner_id_ptr,
		thread_commissioning_status_cb *	status_cb_ptr
	)

Start the commissioning petition.

If the commissioner is insecure, you need to scan the networks and select the Thread network where you want to be a commissioner.

Parameters:

interface_id	Network interface ID. The request comes from this ID.
commissioner_id_ptr	NUL terminated commissioner ID string.
status_cb_ptr	A callback function indicating the result of the operation. Can be NULL if no result code needed.

Returns:: 0 Indicates success.; -1 The client needs to scan the network to become an insecure commissioner.; Any other value indicates other failures.

int thread_commissioning_register	(	int8_t	interface_id,
		uint8_t	PSKc[16]
	)

Register the commissioner interface.

If the network interface is up, the commissioner functionality is started within the Thread network. If there is no interface, the network needs to be scanned first. When the network is found you can add an insecure commissioner, attach to it and start using a different communication method with the border router.

Parameters:

interface_id	Interface ID where the request was made.
PSKc	Pre-shared key between the commissioner and the Thread network.

Returns:: 0 success, other values failure.

int thread_commissioning_unregister ( int8_t interface_id )

Unregister the commissioner interface.

This cleans up all the commissioner data from the device and disconnects it from the Thread network if an insecure commissioner was used.

Parameters:

interface_id Network interface ID. The request comes from this ID.

Returns:: 0 success, other values failure.

Type:	Program
Mbed OS support:	Mbed OS
Created:	23 Feb 2019
Imports:	43
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	0
Followers:	1

thread_commissioning_api.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

thread_commissioning_api.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning