wms_advertiser.h File Reference

Detailed Description

Application library for direct advertiser functionality.

Library services are accessed via lib_advertiser handle.

For examples on how to use these services, check out example application

Definition in file wms_advertiser.h.

Go to the source code of this file.

Typedefs
typedef bool(*	app_llhead_acklistener_f) (const ack_gen_input_t *in, ack_gen_output_t *out)
	Callback function type used with lib_advertiser->setRouterAckGenCb(). More...
typedef void(*	app_lib_advertiser_ackdatacb_f) (app_llhead_acklistener_f callback)
	Sets callback function to be called when ack is generated as a response for advertiser device transmission (in other devices in the network). More...
typedef app_res_e(*	app_lib_advertiser_set_queuing_time_f) (uint16_t time_ms)
	Set maximum queueing time for advertiser data packets. More...
typedef app_res_e(*	app_lib_advertiser_set_options_f) (adv_option_t *option)
	Set options for advertiser. More...

Data Structures
struct	ack_gen_input_t
	Input data structure for callback function set by lib_advertiser->setRouterAckGenCb(). More...
struct	ack_gen_output_t
	Output structure for for callback function set by lib_advertiser->setRouterAckGenCb(). More...
struct	adv_option_t
	Option flags to be used with advertiser. More...
struct	app_lib_advertiser_t
	List of library functions. More...

Macros
#define	APP_LIB_ADVERTISER_NAME   0x06cc5e24
	Library symbolic name More...
#define	APP_LIB_ADVERTISER_VERSION   0x205
	Maximum supported library version. More...
#define	DIRADV_EP_SRC_ACK   249
	Headnode acknowledges the packet by using this source endpoint. More...
#define	DIRADV_EP_DEST   248
	Headnode acknowledges the packet by using this destination endpoint. More...
#define	DIRADV_MAX_ACK_LEN   102
	Absolute maximum size of the ACK message. More...
#define	DIRADV_DEFAULT_QUEUE_TIME   250
	Default value used with lib_advertiser->setQueuingTimeHp(). More...

Typedef Documentation

app_lib_advertiser_ackdatacb_f

typedef void(* app_lib_advertiser_ackdatacb_f) (app_llhead_acklistener_f callback)

Sets callback function to be called when ack is generated as a response for advertiser device transmission (in other devices in the network).

Parameters

callback

Callback function to be used. NULL to disable

Note

Device must have APP_LIB_SETTINGS_ROLE_FLAG_LL in device role (service lib_settings->setNodeRole() in order for callback to be active.

Definition at line 133 of file wms_advertiser.h.

app_lib_advertiser_set_options_f

typedef app_res_e(* app_lib_advertiser_set_options_f) (adv_option_t *option)

Set options for advertiser.

Parameters

option

Options to set

Returns

Result code, normally APP_RES_OK. If option==NULL, APP_RES_INVALID_NULL_POINTER. If role is not APP_LIB_SETTINGS_ROLE_ADVERTISER , APP_RES_INVALID_CONFIGURATION

Definition at line 193 of file wms_advertiser.h.

app_lib_advertiser_set_queuing_time_f

typedef app_res_e(* app_lib_advertiser_set_queuing_time_f) (uint16_t time_ms)

Set maximum queueing time for advertiser data packets.

Parameters

time_ms

Time in milliseconds how soon packet should be transmitted 0 to disable the feature

Returns

Result code, always APP_RES_OK or APP_RES_INVALID_CONFIGURATION if device is not configured as APP_LIB_SETTINGS_ROLE_ADVERTISER

Operation lib_data->setMaxMsgQueuingTime() only allows setting the TTL value in second precision. In CSMA-CA networks, the granularity of that service is not enough. By using this service, advertiser can set the higher-precision TTL and when advertiser sends data to CSMA-CA device, this TTL is also checked (in addition to normal, second-granularity TTL set by lib_data->setMaxMsgQueuingTime()). For time-slotted mode networks, this value has no impact due to nature of the time-slotted mode transmission. Neither this service has impact if device is not advertiser.

Default value used is DIRADV_DEFAULT_QUEUE_TIME

Recommendation is to use values larger than 80 ms. Smaller values than that will cause failed transmission even in normal operation conditions due to the time periods when transmission is forbidden.

Note

Using time_ms with value 0 to disabling the feature may have quite a large impact on power consumption. This means that device may make lot of transmission attempts to target instead of giving up and trying another , alternative, target and thus resulting high power consumption. This could happen, for example, when target device is doing network scan.

Definition at line 168 of file wms_advertiser.h.

app_llhead_acklistener_f

typedef bool(* app_llhead_acklistener_f) (const ack_gen_input_t *in, ack_gen_output_t *out)

Callback function type used with lib_advertiser->setRouterAckGenCb().

Parameters

[in]	in	Information about received advertiser packet
[out]	out	Generated acknowledgement

Returns

true: output generated, false: use default acknowledgement

Definition at line 118 of file wms_advertiser.h.

---

Data Structure Documentation

ack_gen_input_t

struct ack_gen_input_t

Input data structure for callback function set by lib_advertiser->setRouterAckGenCb().

Definition at line 71 of file wms_advertiser.h.

Data Fields
uint8_t	ack_length	Max len of the ack payload supported by transmitter whom the ack is sent
void *	data	Pointer to data payload sent by advertiser
uint8_t	dest_endpoint	Destination endpoint of packet. Used to distinguish different applications sending advertiser packets.
size_t	num_bytes	Amount of data
app_addr_t	sender	Address of the sender (advertiser)
uint8_t	src_endpoint	Source endpoint of packet. Used to distinguish different applications sending advertiser packets.

ack_gen_output_t

struct ack_gen_output_t

Output structure for for callback function set by lib_advertiser->setRouterAckGenCb().

Definition at line 97 of file wms_advertiser.h.

Data Fields
void *	data	Acknowledgement payload. Payload can be allocated by DIRADV_MAX_ACK_LEN definition.
uint8_t	length	length of the acknowledgement (maximum size is limited to supported ack length bytes)

adv_option_t

struct adv_option_t

Option flags to be used with advertiser.

Definition at line 173 of file wms_advertiser.h.

Data Fields
bool	follow_network

app_lib_advertiser_t

struct app_lib_advertiser_t

List of library functions.

Definition at line 199 of file wms_advertiser.h.

Data Fields
app_lib_advertiser_set_options_f	setOptions
app_lib_advertiser_set_queuing_time_f	setQueuingTimeHp
app_lib_advertiser_ackdatacb_f	setRouterAckGenCb

Macro Definition Documentation

APP_LIB_ADVERTISER_NAME

#define APP_LIB_ADVERTISER_NAME   0x06cc5e24

Library symbolic name

"ADVERT"

Definition at line 27 of file wms_advertiser.h.

APP_LIB_ADVERTISER_VERSION

#define APP_LIB_ADVERTISER_VERSION   0x205

Maximum supported library version.

Definition at line 30 of file wms_advertiser.h.

DIRADV_DEFAULT_QUEUE_TIME

#define DIRADV_DEFAULT_QUEUE_TIME   250

Default value used with lib_advertiser->setQueuingTimeHp().

Definition at line 64 of file wms_advertiser.h.

DIRADV_EP_DEST

#define DIRADV_EP_DEST   248

Headnode acknowledges the packet by using this destination endpoint.

Used in headnode callback function set with lib_advertiser->setBeaconDataAckListenCb() and receiving packet in advertiser in callback function set with lib_data->setDataReceivedCb()

Definition at line 49 of file wms_advertiser.h.

DIRADV_EP_SRC_ACK

#define DIRADV_EP_SRC_ACK   249

Headnode acknowledges the packet by using this source endpoint.

Used in headnode callback function set with lib_advertiser->setBeaconDataAckListenCb() and receiving packet in advertiser in callback function set with lib_data->setDataReceivedCb()

Definition at line 40 of file wms_advertiser.h.

DIRADV_MAX_ACK_LEN

#define DIRADV_MAX_ACK_LEN   102

Absolute maximum size of the ACK message.

This can be used for allocating memory structures for callback function set with lib_advertiser->setBeaconDataAckListenCb().

Definition at line 58 of file wms_advertiser.h.