wms_joining.h File Reference

Detailed Description

Application library for sending and receiving joining beacons

Library services are accessed via lib_joining handle.

Definition in file wms_joining.h.

Go to the source code of this file.

Typedefs
typedef void(*	app_lib_joining_beacon_rx_cb_f) (app_lib_joining_rx_status_e status, const app_lib_joining_received_beacon_t *beacons, size_t num_beacons)
	Function type for joining beacon RX callback. More...
typedef app_res_e(*	app_lib_joining_start_joining_beacon_tx_f) (const app_lib_joining_beacon_tx_param_t *param)
	Start transmitting joining beacons. More...
typedef app_res_e(*	app_lib_joining_stop_joining_beacon_tx_f) (void)
	Stop transmitting joining beacons. More...
typedef app_res_e(*	app_lib_joining_start_joining_beacon_rx_f) (const app_lib_joining_beacon_rx_param_t *param)
	Start receiving joining beacons. More...
typedef app_res_e(*	app_lib_joining_stop_joining_beacon_rx_f) (void)
	Stop receiving joining beacons. More...
typedef app_res_e(*	app_lib_joining_start_joining_process_f) (app_lib_settings_net_addr_t addr, app_lib_settings_net_channel_t channel)
	Start the joining process by joining a cluster as a joining member. More...
typedef app_res_e(*	app_lib_joining_stop_joining_process_f) (void)
	Stop the joining process and restore network address and channel. More...
typedef app_res_e(*	app_lib_joining_enable_remote_api_f) (bool enable)
	Enable or disable Remote API control for transmitting joining beacons. More...
typedef app_res_e(*	app_lib_joining_enable_proxy_f) (bool enable)
	Enable or disable built-in proxy for handling joining data packets. More...

Data Structures
struct	app_lib_joining_beacon_tx_param_t
	Parameters for sending joining beacons. More...
struct	app_lib_joining_received_beacon_t
	Received joining beacon. More...
struct	app_lib_joining_beacon_rx_param_t
	Parameters for receiving joining beacons. More...
struct	app_lib_joining_t
	List of library functions. More...

Enumerations
enum	app_lib_joining_rx_status_e { APP_LIB_JOINING_RX_STATUS_DONE = 0, APP_LIB_JOINING_RX_STATUS_STOPPED = 1, APP_LIB_JOINING_RX_STATUS_INTERRUPTED = 2, APP_LIB_JOINING_RX_STATUS_OUT_OF_SPACE = 3 }
	Status values for beacon reception callback. More...

Macros
#define	APP_LIB_JOINING_NAME   0x000a2336
	Library symbolic name More...
#define	APP_LIB_JOINING_VERSION   0x201
	Maximum supported library version. More...
#define	APP_LIB_JOINING_MIN_INTERVAL   100
	Minimum joining beacon interval, in milliseconds. More...
#define	APP_LIB_JOINING_MAX_INTERVAL   8000
	Maximum joining beacon interval, in milliseconds. More...
#define	APP_LIB_JOINING_MIN_TIMEOUT   100
	Minimum joining beacon interval, in milliseconds. More...
#define	APP_LIB_JOINING_MAX_TIMEOUT   10000
	Maximum joining beacon interval, in milliseconds. More...
#define	APP_LIB_JOINING_MAX_PAYLOAD_NUM_BYTES   64
	Maximum number of payload bytes in a joining beacon. More...

Typedef Documentation

app_lib_joining_beacon_rx_cb_f

typedef void(* app_lib_joining_beacon_rx_cb_f) (app_lib_joining_rx_status_e status, const app_lib_joining_received_beacon_t *beacons, size_t num_beacons)

Function type for joining beacon RX callback.

Parameters

status	Status of joining beacon RX process
beacons	Pointer to first received beacon (read-only) or NULL
num_beacons	Number of received joining beacons

Definition at line 172 of file wms_joining.h.

app_lib_joining_enable_proxy_f

typedef app_res_e(* app_lib_joining_enable_proxy_f) (bool enable)

Enable or disable built-in proxy for handling joining data packets.

Returns

Result code, always APP_RES_OK

Note

Built-in proxy is enabled by default

Definition at line 307 of file wms_joining.h.

app_lib_joining_enable_remote_api_f

typedef app_res_e(* app_lib_joining_enable_remote_api_f) (bool enable)

Enable or disable Remote API control for transmitting joining beacons.

Returns

Result code, always APP_RES_OK

Note

Remote API control is enabled by default

Definition at line 300 of file wms_joining.h.

app_lib_joining_start_joining_beacon_rx_f

typedef app_res_e(* app_lib_joining_start_joining_beacon_rx_f) (const app_lib_joining_beacon_rx_param_t *param)

Start receiving joining beacons.

Parameters

param

Joining beacon reception parameters

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is not running, APP_RES_INVALID_CONFIGURATION if the node is a sink, APP_RES_INVALID_NULL_POINTER if param, cb or beacons is NULL, APP_RES_INVALID_VALUE if max_exec_time_us, addr, channel, timeout, beacon_num_bytes or max_num_beacons is invalid or APP_RES_RESOURCE_UNAVAILABLE if network beacon scan or joining beacon transmission or reception is ongoing

Note

While beacon reception is ongoing, all other network activity is paused

It is not possible to start receiving joining beacons if normal network beacon scanning is ongoing. In that case, this function has to be tried again a few seconds later.

Definition at line 247 of file wms_joining.h.

app_lib_joining_start_joining_beacon_tx_f

typedef app_res_e(* app_lib_joining_start_joining_beacon_tx_f) (const app_lib_joining_beacon_tx_param_t *param)

Start transmitting joining beacons.

Parameters

param

Joining beacon transmission parameters

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is not running, APP_RES_RESOURCE_UNAVAILABLE if joining beacon reception is ongoing, APP_RES_INVALID_VALUE if addr, channel or interval is invalid, APP_RES_INVALID_NULL_POINTER if payload pointer is NULL and payload_num_bytes > 0

Note

Power is rounded to the closest possible value and the value pointed by tx_power_p is modified to the used value

This function can be called even if already transmitting joining beacons. The transmissions continue with the new parameters

Definition at line 220 of file wms_joining.h.

app_lib_joining_start_joining_process_f

typedef app_res_e(* app_lib_joining_start_joining_process_f) (app_lib_settings_net_addr_t addr, app_lib_settings_net_channel_t channel)

Start the joining process by joining a cluster as a joining member.

Parameters

addr	Network address (radio address) of the network to try joining
channel	Network channel of the network to try joining

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is not running, APP_RES_INVALID_VALUE if addr or channel is invalid, APP_RES_INVALID_CONFIGURATION if joining beacon transmission or reception is ongoing, or if the node is a sink

Note

A network scan is automatically started. After the scan the node will join one of the cluster heads currently transmitting joining beacons. The cluster head will not change during the joining process.

The joining process can be restarted with other addr and channel parameters by calling this function again

Definition at line 277 of file wms_joining.h.

app_lib_joining_stop_joining_beacon_rx_f

typedef app_res_e(* app_lib_joining_stop_joining_beacon_rx_f) (void)

Stop receiving joining beacons.

Returns

Result code, always APP_RES_OK

Note

If beacon reception is currently ongoing, Reception callback will be called with status APP_LIB_JOINING_RX_STATUS_STOPPED some time after this function returns with APP_RES_OK

Definition at line 257 of file wms_joining.h.

app_lib_joining_stop_joining_beacon_tx_f

typedef app_res_e(* app_lib_joining_stop_joining_beacon_tx_f) (void)

Stop transmitting joining beacons.

Returns

Result code, always APP_RES_OK

Definition at line 227 of file wms_joining.h.

app_lib_joining_stop_joining_process_f

typedef app_res_e(* app_lib_joining_stop_joining_process_f) (void)

Stop the joining process and restore network address and channel.

Returns

Result code, always APP_RES_OK

Note

The function can be used to cancel the joining process and return to normal operation. It is also permissible to call function app_lib_joining_start_joining_process_f(). again with new parameters, without calling this function first

A network scan is automatically started. After the scan the node will join a network as a regular member, if a network is available

Definition at line 293 of file wms_joining.h.

---

Data Structure Documentation

app_lib_joining_beacon_tx_param_t

struct app_lib_joining_beacon_tx_param_t

Parameters for sending joining beacons.

Used in service lib_joining->startJoiningBeaconTx().

Definition at line 104 of file wms_joining.h.

Data Fields
app_lib_settings_net_addr_t	addr	Network address (radio address) to use for sending joining beacons
app_lib_settings_net_channel_t	channel	Radio channel to use for sending joining beacons
uint32_t	interval	Interval of joining beacons, in milliseconds
const void *	payload	Optional payload, ignored if payload_num_bytes == 0
size_t	payload_num_bytes	Number of payload bytes
int8_t	tx_power	Transmission power to use for sending joining beacons, in dBm
uint32_t	type	A 32-bit type field for early filtering of received joining beacons

app_lib_joining_received_beacon_s

struct app_lib_joining_received_beacon_s

Received joining beacon.

Used in beacon reception callback set with service lib_joining->startJoiningBeaconRx().

Definition at line 129 of file wms_joining.h.

Data Fields
app_lib_settings_net_addr_t	addr	Network address of found network
app_lib_settings_net_channel_t	channel	Network channel of found network
struct app_lib_joining_received_beacon_s *	next	Pointer to next joining beacon or NULL
size_t	num_bytes	Size of this joining beacon structure in bytes, including the next and num_bytes fields
uint8_t *	old_payload	Old payload pointer for backwards compatibility
uint8_t	payload[64]	Payload
size_t	payload_num_bytes	Number of payload bytes
uint8_t	reserved	To align the header structure to 32 bits for backwards compatibility
int8_t	rssi	Signal strength of received joining beacon, in dBm
app_lib_time_timestamp_coarse_t	time	Time when beacon received, as coarse timestamp
int8_t	tx_power	Transmission power of joining beacon, in dBm
uint32_t	type	A 32-bit protocol type identifier of received joining beacon

app_lib_joining_beacon_rx_param_t

struct app_lib_joining_beacon_rx_param_t

Parameters for receiving joining beacons.

Used in lib_joining->startJoiningBeaconRx() service.

Definition at line 183 of file wms_joining.h.

Data Fields
app_lib_settings_net_addr_t	addr	Network address to use for receiving joining beacons
void *	buffer	A buffer for collecting joining beacons
app_lib_joining_beacon_rx_cb_f	cb	Function to call after joining beacon reception ends for any reason
app_lib_settings_net_channel_t	channel	Network channel to use for receiving joining beacons
uint32_t	max_exec_time_us	Maximum time for the callback function to execute in microseconds
size_t	max_num_beacons	Maximum number of joining beacons to receive
size_t	num_bytes	Size of beacon buffer in bytes
uint32_t	timeout	Joining beacon reception duration in milliseconds

app_lib_joining_t

struct app_lib_joining_t

List of library functions.

Definition at line 312 of file wms_joining.h.

Data Fields
app_lib_joining_enable_proxy_f	enableProxy
app_lib_joining_enable_remote_api_f	enableRemoteApi
app_lib_joining_start_joining_beacon_rx_f	startJoiningBeaconRx
app_lib_joining_start_joining_beacon_tx_f	startJoiningBeaconTx
app_lib_joining_start_joining_process_f	startJoiningProcess
app_lib_joining_stop_joining_beacon_rx_f	stopJoiningBeaconRx
app_lib_joining_stop_joining_beacon_tx_f	stopJoiningBeaconTx
app_lib_joining_stop_joining_process_f	stopJoiningProcess

Enumeration Type Documentation

app_lib_joining_rx_status_e

enum app_lib_joining_rx_status_e

Status values for beacon reception callback.

Used in beacon reception callback set with service lib_joining->startJoiningBeaconRx().

Enumerator
APP_LIB_JOINING_RX_STATUS_DONE	Reception timeout elapsed or requested number of beacons received
APP_LIB_JOINING_RX_STATUS_STOPPED	Beacon reception stopped by calling lib_joining->stopJoiningBeaconRx()
APP_LIB_JOINING_RX_STATUS_INTERRUPTED	A higher priority radio event (e.g. network beacon scan) interrupted the joining beacon reception
APP_LIB_JOINING_RX_STATUS_OUT_OF_SPACE	No space in buffer for any more joining beacons

Definition at line 82 of file wms_joining.h.

{
    APP_LIB_JOINING_RX_STATUS_DONE = 0,
    APP_LIB_JOINING_RX_STATUS_STOPPED = 1,
    APP_LIB_JOINING_RX_STATUS_INTERRUPTED = 2,
    APP_LIB_JOINING_RX_STATUS_OUT_OF_SPACE = 3
} app_lib_joining_rx_status_e;

Macro Definition Documentation

APP_LIB_JOINING_MAX_INTERVAL

#define APP_LIB_JOINING_MAX_INTERVAL   8000

Maximum joining beacon interval, in milliseconds.

Used when defining interval of joining beacons in lib_joining->startJoiningBeaconTx() service.

Definition at line 48 of file wms_joining.h.

APP_LIB_JOINING_MAX_PAYLOAD_NUM_BYTES

#define APP_LIB_JOINING_MAX_PAYLOAD_NUM_BYTES   64

Maximum number of payload bytes in a joining beacon.

Used when defining payload bytes of joining beacons in lib_joining->startJoiningBeaconTx() service.

Definition at line 73 of file wms_joining.h.

APP_LIB_JOINING_MAX_TIMEOUT

#define APP_LIB_JOINING_MAX_TIMEOUT   10000

Maximum joining beacon interval, in milliseconds.

Used when defining timeout of joining beacon reception in lib_joining->startJoiningBeaconRx() service.

Definition at line 64 of file wms_joining.h.

APP_LIB_JOINING_MIN_INTERVAL

#define APP_LIB_JOINING_MIN_INTERVAL   100

Minimum joining beacon interval, in milliseconds.

Used when defining interval of joining beacons in lib_joining->startJoiningBeaconTx() service.

Definition at line 40 of file wms_joining.h.

APP_LIB_JOINING_MIN_TIMEOUT

#define APP_LIB_JOINING_MIN_TIMEOUT   100

Minimum joining beacon interval, in milliseconds.

Used when defining timeout of joining beacon reception in lib_joining->startJoiningBeaconRx() service.

Definition at line 56 of file wms_joining.h.

APP_LIB_JOINING_NAME

#define APP_LIB_JOINING_NAME   0x000a2336

Library symbolic name

"JOIN"

Definition at line 29 of file wms_joining.h.

APP_LIB_JOINING_VERSION

#define APP_LIB_JOINING_VERSION   0x201

Maximum supported library version.

Definition at line 32 of file wms_joining.h.