wms_data.h File Reference

Detailed Description

The Data library contains functions for sending and receiving data packets. Also contained within are functions for sending and receiving app config data, which is a small bit of data that gets distributed to all nodes on the network. Any new nodes will receive app config data quickly during joining process to the network. App config very lightweight and can also be considered as 'network persistent data'.

Library services are accessed via lib_data handle.

Definition in file wms_data.h.

Go to the source code of this file.

Typedefs
typedef uint16_t	app_lib_data_tracking_id_t
	Type of tracking ID for data packets. More...
typedef app_lib_data_receive_res_e(*	app_lib_data_data_received_cb_f) (const app_lib_data_received_t *data)
	Data reception callback. More...
typedef void(*	app_lib_data_data_sent_cb_f) (const app_lib_data_sent_status_t *status)
	Sent packet tracking callback. More...
typedef void(*	app_lib_data_new_app_config_cb_f) (const uint8_t *bytes, uint8_t seq, uint16_t interval)
	Type of the new app config callback function. More...
typedef app_res_e(*	app_lib_data_set_data_received_cb_f) (app_lib_data_data_received_cb_f cb)
	Set data reception callback. More...
typedef app_res_e(*	app_lib_data_set_data_sent_cb_f) (app_lib_data_data_sent_cb_f cb)
	Set data sent tracking callback. More...
typedef app_res_e(*	app_lib_data_set_new_app_config_cb_f) (app_lib_data_new_app_config_cb_f cb)
	Set the callback function to be called when new app config data is received. More...
typedef app_lib_data_data_size_t(*	app_lib_data_get_data_max_num_bytes_f) (void)
	Return the maximum number of bytes per data packet or data segment. More...
typedef size_t(*	app_lib_data_get_num_buffers_f) (void)
	Get total number of packet buffers. More...
typedef app_res_e(*	app_lib_data_get_num_free_buffers_f) (size_t *num_buffers_p)
	Get number of currently available buffers. More...
typedef app_lib_data_send_res_e(*	app_lib_data_send_data_f) (const app_lib_data_to_send_t *data)
	Send data. More...
typedef void(*	app_lib_data_allow_reception_f) (bool allow)
	Allow or block reception The application may temporarily tell the stack to not call the reception data reception callbacks (set with service lib_data->setDataReceivedCb()), if an external interface is not responding, for example. The stack will then keep the received packets in its internal buffers until reception is allowed again. More...
typedef app_lib_data_app_config_res_e(*	app_lib_data_read_app_config_f) (uint8_t *bytes, uint8_t *seq, uint16_t *interval)
	Read app config. More...
typedef size_t(*	app_lib_data_get_app_config_num_bytes_f) (void)
	Get size of app config. More...
typedef app_res_e(*	app_lib_data_set_max_msg_queuing_time_f) (app_lib_data_qos_e priority, uint16_t time)
	Set maximum queuing time for messages. More...
typedef app_res_e(*	app_lib_data_get_max_msg_queuing_time_f) (app_lib_data_qos_e priority, uint16_t *time_p)
	Get maximum queuing time of messages. More...
typedef app_lib_data_app_config_res_e(*	app_lib_data_write_app_config_data_f) (const uint8_t *bytes)
	Write app config DATA. More...
typedef app_lib_data_app_config_res_e(*	app_lib_data_write_diagnostic_interval_f) (uint16_t interval)
	Write Diagnostic interval. More...
typedef app_res_e(*	app_lib_data_set_local_mc_f) (const app_lib_data_local_mc_info_t *info)
	Set local multicast functionality. More...
typedef app_res_e(*	app_lib_data_set_fragmented_mode_f) (const app_lib_data_fragmented_mode_e mode)
	Set the fragmentation behavior for RX packets. More...

Data Structures
struct	app_lib_data_fragment_t
	Fragmentation information. More...
struct	app_lib_data_received_t
	Struct passed to data reception callback functions. More...
struct	app_lib_data_to_send_t
	A struct for lib_data->sendData(). More...
struct	app_lib_data_sent_status_t
	Struct to tracking callback function. More...
struct	app_lib_data_data_size_t
struct	app_lib_data_local_mc_info_t
	Information on setting local multicast functionality. To be used with service lib_data->setLocalMulticastInfo(). More...
struct	app_lib_data_t
	List of library services. More...

Enumerations
enum	app_lib_data_qos_e { APP_LIB_DATA_QOS_NORMAL = 0, APP_LIB_DATA_QOS_HIGH = 1 }
	Data quality of service class. Used when sending and receiving data packets. More...
enum	app_lib_data_send_flags_e {   APP_LIB_DATA_SEND_FLAG_NONE = 0, APP_LIB_DATA_SEND_FLAG_TRACK = 1, APP_LIB_DATA_SEND_SET_HOP_LIMITING = 4, APP_LIB_DATA_SEND_FLAG_UNACK_CSMA_CA = 8,   APP_LIB_DATA_SEND_NW_CH_ONLY = 16, APP_LIB_DATA_SEND_FRAGMENTED_PACKET = 32 }
	Flags to use with lib_data->sendData(). More...
enum	app_lib_data_send_res_e {   APP_LIB_DATA_SEND_RES_SUCCESS = 0, APP_LIB_DATA_SEND_RES_INVALID_STACK_STATE = 1, APP_LIB_DATA_SEND_RES_INVALID_QOS = 2, APP_LIB_DATA_SEND_RES_INVALID_FLAGS = 3,   APP_LIB_DATA_SEND_RES_OUT_OF_MEMORY = 4, APP_LIB_DATA_SEND_RES_INVALID_DEST_ADDRESS = 5, APP_LIB_DATA_SEND_RES_INVALID_NUM_BYTES = 6, APP_LIB_DATA_SEND_RES_OUT_OF_TRACKING_IDS = 7,   APP_LIB_DATA_SEND_RES_INVALID_TRACKING_ID = 8, APP_LIB_DATA_SEND_RES_RESERVED_ENDPOINT = 9, APP_LIB_DATA_SEND_RES_ACCESS_DENIED = 10, APP_LIB_DATA_SEND_RES_INVALID_HOP_LIMIT = 11,   APP_LIB_DATA_SEND_RES_UNINITIALIZED = 12, APP_LIB_DATA_SEND_RES_INVALID_FRAGMENT_INFO = 13 }
	A result code returned from lib_data->sendData(). More...
enum	app_lib_data_receive_res_e { APP_LIB_DATA_RECEIVE_RES_HANDLED = 0, APP_LIB_DATA_RECEIVE_RES_NOT_FOR_APP = 1, APP_LIB_DATA_RECEIVE_RES_NO_SPACE = 2 }
	Return value of data reception callback. More...
enum	app_lib_data_app_config_res_e {   APP_LIB_DATA_APP_CONFIG_RES_SUCCESS = 0, APP_LIB_DATA_APP_CONFIG_RES_INVALID_ROLE = 1, APP_LIB_DATA_APP_CONFIG_RES_INVALID_APP_CONFIG = 2, APP_LIB_DATA_APP_CONFIG_RES_INVALID_SEQ = 3,   APP_LIB_DATA_APP_CONFIG_RES_INVALID_INTERVAL = 4, APP_LIB_DATA_APP_CONFIG_RES_INVALID_NULL_POINTER = 5 }
	Result of the app config. More...
enum	app_lib_data_fragmented_mode_e { APP_LIB_DATA_FRAGMENTED_MODE_ENABLED = 0, APP_LIB_DATA_FRAGMENTED_MODE_DISABLED = 1 }
	Fragmentation mode. Use to specify if reassembly is done by stack or by application itself. More...

Macros
#define	APP_LIB_DATA_NAME   0x0003f161
	Library symbolic name More...
#define	APP_LIB_DATA_VERSION   0x20B
	Maximum supported library version. More...
#define	APP_LIB_DATA_NO_TRACKING_ID   (app_lib_data_tracking_id_t)(-1)
	When sending data and no tracking of packet is requested, this ID may be used. More...
#define	APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES   80
	size of app config More...
#define	APP_LIB_DATA_RX_HOPS_UNDETERMINED   0
	Unable to determine hop count. More...
#define	APP_DATA_DISABLE_LOCAL_MULTICAST   0
	Dedicated value to disable local multicast functionality. To be used with service lib_data->setLocalMulticastInfo(). More...

Typedef Documentation

app_lib_data_allow_reception_f

typedef void(* app_lib_data_allow_reception_f) (bool allow)

Allow or block reception The application may temporarily tell the stack to not call the reception data reception callbacks (set with service lib_data->setDataReceivedCb()), if an external interface is not responding, for example. The stack will then keep the received packets in its internal buffers until reception is allowed again.

If the reception callback returns APP_LIB_DATA_RECEIVE_RES_NO_SPACE, it is the same as calling lib_data->allowReception(false).

Example of use:

lib_data->allowReception(true);

Parameters

allow

True if it is OK to call the reception callback, false otherwise

Note

If reception is not allowed and there is buffered data, calling this function with a parameter of true will cause the reception callback to be called right away

Definition at line 652 of file wms_data.h.

app_lib_data_data_received_cb_f

typedef app_lib_data_receive_res_e(* app_lib_data_data_received_cb_f) (const app_lib_data_received_t *data)

Data reception callback.

The application sets a data reception callback by calling either lib_data->setDataReceivedCb().

The received packet is represented as a pointer to app_lib_data_received_t struct. Depending on the return value, the stack either keeps or discards the packet.

Parameters

data	Received data

Returns

Result code, app_lib_data_receive_res_e

Definition at line 408 of file wms_data.h.

app_lib_data_data_sent_cb_f

typedef void(* app_lib_data_data_sent_cb_f) (const app_lib_data_sent_status_t *status)

Sent packet tracking callback.

The application sets a tracking callback by calling lib_data->setDataSentCb().

Parameters

status

Status of the sent packet

Definition at line 420 of file wms_data.h.

app_lib_data_get_app_config_num_bytes_f

typedef size_t(* app_lib_data_get_app_config_num_bytes_f) (void)

Get size of app config.

Returns

App config size in bytes

Example of use:

size_t app_config_size = lib_data->getAppConfigNumBytes();

Definition at line 691 of file wms_data.h.

app_lib_data_get_data_max_num_bytes_f

typedef app_lib_data_data_size_t(* app_lib_data_get_data_max_num_bytes_f) (void)

Return the maximum number of bytes per data packet or data segment.

Different platforms may have different radio packet size, so these values may vary.

Example:

app_lib_data_data_size_t max_lengths;
max_lengths = lib_data->getDataMaxNumBytes();

Returns

Maximum size of data packet in bytes

Definition at line 556 of file wms_data.h.

app_lib_data_get_max_msg_queuing_time_f

typedef app_res_e(* app_lib_data_get_max_msg_queuing_time_f) (app_lib_data_qos_e priority, uint16_t *time_p)

Get maximum queuing time of messages.

Parameters

priority	Message priority which queuing time to be read
time_p	Pointer where to store maximum queuing time

Returns

Result code, APP_RES_OK if ok, APP_RES_INVALID_VALUE if unsupported message priority, APP_RES_INVALID_NULL_POINTER if time_p is null

Example:

uint16_t qos_normal_qt;
lib_data->getMaxMsgQueuingTime(APP_LIB_DATA_QOS_NORMAL, &qos_normal_qt);

Definition at line 741 of file wms_data.h.

app_lib_data_get_num_buffers_f

typedef size_t(* app_lib_data_get_num_buffers_f) (void)

Get total number of packet buffers.

Return the total number of packet buffers for sent data that are tracked. See lib_data->getNumFreeBuffers() for reading the number of available buffers. This function applies for transmitted packets that are tracked.

Example to use:

size_t total_tracked = lib_data->getNumBuffers();

Returns

Total number of data packets that can be buffered

Note

When packets are send with lib_data->sendData() without tracking (tracking_id == APP_LIB_DATA_NO_TRACKING_ID), there are plenty of more buffers available than with tracking enabled. For tracking enabled, there is only 16 buffers available.

Definition at line 579 of file wms_data.h.

app_lib_data_get_num_free_buffers_f

typedef app_res_e(* app_lib_data_get_num_free_buffers_f) (size_t *num_buffers_p)

Get number of currently available buffers.

Query the number of currently available buffers for sending data with tracking enabled. If there are no buffers left, sending data is not possible. Function lib_data->getNumBuffers() returns the maximum number of buffers available. This function applies for transmitted packets that are tracked.

Example:

size_t num_buffers;
lib_data->getNumBuffers(@num_buffers);

Parameters

num_buffers_p

Pointer to a value where the number of data packets that can be buffered will be stored

Returns

Result code, APP_RES_OK if stack is running, otherwise APP_RES_INVALID_STACK_STATE

Note

When packets are send with lib_data->sendData() without tracking (tracking_id == APP_LIB_DATA_NO_TRACKING_ID), there are plenty of more buffers available than with tracking enabled. For tracking enabled, there is only 16 buffers available.

Definition at line 608 of file wms_data.h.

app_lib_data_new_app_config_cb_f

typedef void(* app_lib_data_new_app_config_cb_f) (const uint8_t *bytes, uint8_t seq, uint16_t interval)

Type of the new app config callback function.

New app config callback is called whenever new app config is received and when the node first joins a network. There is no return value from the callback.

The application sets a new app config callback by calling lib_data->setNewAppConfigCb().

Parameters

bytes	New app config data
seq	New app config data sequence number
interval	New app config data diagnostic interval, in seconds

Definition at line 439 of file wms_data.h.

app_lib_data_read_app_config_f

typedef app_lib_data_app_config_res_e(* app_lib_data_read_app_config_f) (uint8_t *bytes, uint8_t *seq, uint16_t *interval)

Read app config.

Parameters

bytes	Pointer to a buffer for app config data
seq	Pointer to app config sequence
interval	Pointer to diagnostic interval in seconds

Returns

Result code, APP_LIB_DATA_APP_CONFIG_RES_SUCCESS if successful. See app_lib_data_app_config_res_e for other result codes.

Example:

uint8_t appconfig[APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES];
uint8_t appconfig_seq;
uint16_t appconfig_interval;
lib_data->readAppConfig(&appconfig[0],
                        &appconfig_seq,
                        &appconfig_interval);

Definition at line 677 of file wms_data.h.

app_lib_data_send_data_f

typedef app_lib_data_send_res_e(* app_lib_data_send_data_f) (const app_lib_data_to_send_t *data)

Send data.

The packet to send is represented as app_lib_data_to_send_t struct.

Example: See example application custom_app

Parameters

data	Data to send

Returns

Result code, APP_LIB_DATA_SEND_RES_SUCCESS means that data was accepted for sending. See app_lib_data_send_res_e for other result codes.

Definition at line 625 of file wms_data.h.

app_lib_data_set_data_received_cb_f

typedef app_res_e(* app_lib_data_set_data_received_cb_f) (app_lib_data_data_received_cb_f cb)

Set data reception callback.

Set the callback function to be called when new data is received (unicast, multicast or broadcast)). If NULL is passed, the callback is disabled.

Example on use. Application handles destination endpoint of 12 as incoming data and triggers temperature measurement.

#define GET_TEMPERATURE_EP  12
 
static app_lib_data_receive_res_e dataReceivedCb(
    const app_lib_data_received_t * data)
{
    if (data->dest_endpoint == GET_TEMPERATURE_EP)
    {
        //start_temperature_measurement();
        return APP_LIB_DATA_RECEIVE_RES_HANDLED;
    }
 
    return APP_LIB_DATA_RECEIVE_RES_NOT_FOR_APP;
}
 
void App_init(const app_global_functions_t * functions)
{
    // Register for unicast, multicast & broadcast messages
    lib_data->setDataReceivedCb(dataReceivedCb);
 
    // Start the stack
    lib_state->startStack();
}

Parameters

cb	The function to be executed, or NULL to unset

Returns

Result code, always APP_RES_OK

Definition at line 483 of file wms_data.h.

app_lib_data_set_data_sent_cb_f

typedef app_res_e(* app_lib_data_set_data_sent_cb_f) (app_lib_data_data_sent_cb_f cb)

Set data sent tracking callback.

Set the callback function to be called when a packet has gone through local processing and has finally been sent or discarded. If NULL is passed, the callback is disabled

Example:

static void cb_data_ack(const app_lib_data_sent_status_t * status)
{
    (void) status;
    // Here add operation to track when packet has been sent
}
 
void App_init(const app_global_functions_t* functions)
{
    lib_data->setDataSentCb(cb_data_ack);
    // When lib_data->sendData is called with tracking, callback is called
    // start the stack
    lib_state->startStack();
}

Parameters

cb	The function to be executed, or NULL to unset

Returns

Result code, always APP_RES_OK

Definition at line 514 of file wms_data.h.

app_lib_data_set_fragmented_mode_f

typedef app_res_e(* app_lib_data_set_fragmented_mode_f) (const app_lib_data_fragmented_mode_e mode)

Set the fragmentation behavior for RX packets.

Parameters

mode	Mode to use for fragmentation behavior

Returns

APP_RES_OK if mode is accepted.

Definition at line 844 of file wms_data.h.

app_lib_data_set_local_mc_f

typedef app_res_e(* app_lib_data_set_local_mc_f) (const app_lib_data_local_mc_info_t *info)

Set local multicast functionality.

Parameters

info	Information on local multicast configuration

Returns

APP_RES_OK if value is fine. APP_RES_INVALID_NULL_POINTER or APP_RES_INVALID_VALUE if hops left value is too large to be represented

Local multicast is the feature where propagation of multicast packets shall be limited when reaching outside target multicast group. This will decrease propagation of the packet in such areas, decreasing caused traffic load to network. When packet reaches device which does not belong to target multicast group, propagation of the packet is limited to amount of hops left defined in info. When packet is transmitted inside target multicast group, propagation is not affected.

Definition at line 836 of file wms_data.h.

app_lib_data_set_max_msg_queuing_time_f

typedef app_res_e(* app_lib_data_set_max_msg_queuing_time_f) (app_lib_data_qos_e priority, uint16_t time)

Set maximum queuing time for messages.

Parameters

priority	Message priority which queuing time to be set
time	Queuing time in seconds. Accepted range: 2 - 65534s. Select queuing time carefully, too short value might cause unnecessary message drops and too big value filling up message queues. For consistent performance it is recommended to use the same queuing time in the whole network.

Note

Minimum queuing time shall be bigger than access cycle interval in time-slotted mode networks. It is recommended to use multiples of access cycle interval (+ extra) to give time for message repetitions, higher priority messages taking over the access slot etc. Access cycle is not limiting the minimum value in CSMA-CA networks.

Returns

Result code, APP_RES_OK if successful APP_RES_INVALID_VALUE if unsupported message priority or time

Example:

// Set queueing time for low priority to 5 seconds
lib_data->setMaxMsgQueuingTime(APP_LIB_DATA_QOS_NORMAL, 5);

Definition at line 721 of file wms_data.h.

app_lib_data_set_new_app_config_cb_f

typedef app_res_e(* app_lib_data_set_new_app_config_cb_f) (app_lib_data_new_app_config_cb_f cb)

Set the callback function to be called when new app config data is received.

Example: see example application appconfig_app

Parameters

cb	The function to be executed, or NULL to unset

Returns

Result code, always APP_RES_OK

Definition at line 528 of file wms_data.h.

app_lib_data_tracking_id_t

typedef uint16_t app_lib_data_tracking_id_t

Type of tracking ID for data packets.

A type of tracking ID for sent data packets, to keep track of packets sent through local processing, until packet is finally sent or discarded. The valid range for this id is [0, 65534 (0xFFFF -1) ]. The value 65535 (0xFFFF) is used to disable the id tracking (APP_LIB_DATA_NO_TRACKING_ID).

Note

Tracking ID is used only locally for the communication between the application layer and the stack. These are not actually transmitted on the network. Only 16 requests where tracking is active are allowed at the same time. Without tracking, there is room for plenty of more requests simultaneously.

In order for this to be activate, flag APP_LIB_DATA_SEND_FLAG_TRACK must be set in arguments when calling lib_data->sendData.

Definition at line 52 of file wms_data.h.

app_lib_data_write_app_config_data_f

typedef app_lib_data_app_config_res_e(* app_lib_data_write_app_config_data_f) (const uint8_t *bytes)

Write app config DATA.

Parameters

bytes

Pointer to app config data to write. The format can be decided by the application.

Returns

Result code, APP_LIB_DATA_APP_CONFIG_RES_SUCCESS if successful. See app_lib_data_app_config_res_e for other result codes.

Note

It is recommended that the app config data is not written too often, as new configuration is always written to the non- volatile memory of the sink and disseminated to the network. This can cause unnecessary wearing of the memory with devices that need to use the program memory to store persistent variables and unnecessary load to the network.

Example:

uint8_t appconfig[APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES];
 
lib_data->writeAppConfigData(&appconfig[0]);

Definition at line 769 of file wms_data.h.

app_lib_data_write_diagnostic_interval_f

typedef app_lib_data_app_config_res_e(* app_lib_data_write_diagnostic_interval_f) (uint16_t interval)

Write Diagnostic interval.

Parameters

interval

Diagnostic data transmission interval in seconds, i.e. how often the nodes on the network should send diagnostic PDUs. If the value is 0, diagnostic data transmission is disabled. Valid values are: 0 (default), 30, 60, 120, 300, 600 and 1800.

Returns

Result code, APP_LIB_DATA_APP_CONFIG_RES_SUCCESS if successful. See app_lib_data_app_config_res_e for other result codes.

Note

It is recommended that the diagnostic interval is not written too often, as new configuration is always written to the non- volatile memory of the sink and disseminated to the network. This can cause unnecessary wearing of the memory with devices that need to use the program memory to store persistent variables and unnecessary load to the network.

Example:

lib_data->writeDiagnosticInterval(30);

Definition at line 796 of file wms_data.h.

---

Data Structure Documentation

app_lib_data_fragment_t

struct app_lib_data_fragment_t

Fragmentation information.

Definition at line 266 of file wms_data.h.

Data Fields
uint16_t	fragment_offset	Offset of the fragment in bytes from the beginning of the the full message
bool	last_fragment	Is it last fragment of packet
uint16_t	packet_id	Id of the framented packet (only lowest 12 bits are used)

app_lib_data_received_t

struct app_lib_data_received_t

Struct passed to data reception callback functions.

This struct is passed to the data reception callback functions set with services lib_data->setDataReceivedCb()

Examples

basic_interrupt/app.c, ble_scanner/app.c, ble_tx/app.c, custom_app/app.c, and shared_data/app.c.

Definition at line 283 of file wms_data.h.

Data Fields
const uint8_t *	bytes	Received bytes
uint32_t	delay	End-to-end transmission delay, in 1 / 128 of seconds. This also includes the value set in the delay field for lib_data->sendData
uint32_t	delay_hp	End-to-end transmission delay, in 1 / 1024 of seconds. This also includes the value set in the delay field for lib_data->sendData
app_addr_t	dest_address	Destination address for reception. For unicast receptions, own address. For broadcast receptions, APP_ADDR_BROADCAST. For multicast receptions, group address (with APP_ADDR_MULTICAST bitmask set)
uint8_t	dest_endpoint	Destination endpoint of packet
app_lib_data_fragment_t *	fragment_info	Fragmentation information If NULL, packet is a full packet, otherwise it is a segment
uint8_t	hops	Amount of hops that were used when routing packet to the destination
app_addr_t	mac_src_address	Mac source address, i.e. previous hop of the packet. Which device transmitted the packet. tx_power and rssi fields apply for this device
size_t	num_bytes	Number of bytes received
app_lib_data_qos_e	qos	Packet quality of service class, see app_lib_data_qos_e
int8_t	rssi	received signal strength (in dBm). Note: if loopback message (transmission to itself), this is meaningless because packet is not sent via radio at all.
app_addr_t	src_address	Address of node that sent the packet
uint8_t	src_endpoint	Source endpoint of packet
int8_t	tx_power	transmit power in dBm (of previous hop). Note: if loopback message (transmission to itself), this is meaningless because packet is not sent via radio at all.

app_lib_data_to_send_t

struct app_lib_data_to_send_t

A struct for lib_data->sendData().

Examples

appconfig/app.c, basic_interrupt/app.c, ble_scanner/app.c, ble_tx/app.c, custom_app/app.c, ruuvi_evk/app.c, and shared_data/app.c.

Definition at line 331 of file wms_data.h.

Data Fields
const uint8_t *	bytes	Bytes to send
uint32_t	delay	Initial end-to-end transmission delay, in 1 / 128 seconds. This could be used, for example, to represent actual measurement time if done earlier but generated for transmission on later time moment.
app_addr_t	dest_address	Destination address of packet
uint8_t	dest_endpoint	Destination endpoint of packet
uint8_t	flags	Send flags, see app_lib_data_send_flags_e
app_lib_data_fragment_t	fragment_info	Fragmentation information Only read by stack if flags has flag APP_LIB_DATA_SEND_FRAGMENTED_PACKET set
uint8_t	hop_limit	Maximum amount of hops allowed for transmission. Requires also flag APP_LIB_DATA_SEND_SET_HOP_LIMITING to be set in flags field in order to be active. When used, value must be >0.
size_t	num_bytes	Number of bytes to send
app_lib_data_qos_e	qos	Packet quality of service class
uint8_t	src_endpoint	Source endpoint of packet
app_lib_data_tracking_id_t	tracking_id	Packet tracking ID

app_lib_data_sent_status_t

struct app_lib_data_sent_status_t

Struct to tracking callback function.

This struct is passed to the tracking callback function (set with service lib_data->setDataSentCb()) when a packet is either sent or discarded.

Examples

shared_data/app.c.

Definition at line 372 of file wms_data.h.

Data Fields
app_addr_t	dest_address	Destination address of packet
uint8_t	dest_endpoint	Destination endpoint of packet
uint32_t	queue_time	Time the packet spent in the local buffer, in 1 / 128 seconds. This also includes the value set in the delay field for lib_data->sendData.
uint8_t	src_endpoint	Source endpoint of packet
bool	success	True if packet was sent, false if packet was discarded
app_lib_data_tracking_id_t	tracking_id	Packet tracking ID to distinguish which packet was sent

app_lib_data_data_size_t

struct app_lib_data_data_size_t

Definition at line 530 of file wms_data.h.

Data Fields
size_t	max_data_size	Maximum size for data to be received or sent to stack
size_t	max_fragment_size	Maximum size for a fragment to be received or sent to stack if the fragmentation and reassembly is not used by stack

app_lib_data_local_mc_info_t

struct app_lib_data_local_mc_info_t

Information on setting local multicast functionality. To be used with service lib_data->setLocalMulticastInfo().

Definition at line 810 of file wms_data.h.

Data Fields
uint8_t	hops_left	Amount of hops left set when multicast packet goes out of target multicast group.

app_lib_data_t

struct app_lib_data_t

List of library services.

Definition at line 849 of file wms_data.h.

Data Fields
app_lib_data_allow_reception_f	allowReception
app_lib_data_get_app_config_num_bytes_f	getAppConfigNumBytes
app_lib_data_get_data_max_num_bytes_f	getDataMaxNumBytes
app_lib_data_get_max_msg_queuing_time_f	getMaxMsgQueuingTime
app_lib_data_get_num_buffers_f	getNumBuffers
app_lib_data_get_num_free_buffers_f	getNumFreeBuffers
app_lib_data_read_app_config_f	readAppConfig
app_lib_data_send_data_f	sendData
app_lib_data_set_data_received_cb_f	setDataReceivedCb
app_lib_data_set_data_sent_cb_f	setDataSentCb
app_lib_data_set_fragmented_mode_f	setFragmentMode
app_lib_data_set_local_mc_f	setLocalMulticastInfo
app_lib_data_set_max_msg_queuing_time_f	setMaxMsgQueuingTime
app_lib_data_set_new_app_config_cb_f	setNewAppConfigCb
app_lib_data_write_app_config_data_f	writeAppConfigData
app_lib_data_write_diagnostic_interval_f	writeDiagnosticInterval

Enumeration Type Documentation

app_lib_data_app_config_res_e

enum app_lib_data_app_config_res_e

Result of the app config.

A result code returned from lib_data->readAppConfig() and parameter for lib_data->writeAppConfig()

Enumerator
APP_LIB_DATA_APP_CONFIG_RES_SUCCESS	Reading or writing app config data was successful
APP_LIB_DATA_APP_CONFIG_RES_INVALID_ROLE	Error: cannot write app config data: node is not a sink
APP_LIB_DATA_APP_CONFIG_RES_INVALID_APP_CONFIG	Error: cannot read app config data: no app config data set or received
APP_LIB_DATA_APP_CONFIG_RES_INVALID_SEQ	Error: invalid sequence number parameter
APP_LIB_DATA_APP_CONFIG_RES_INVALID_INTERVAL	Error: invalid interval parameter
APP_LIB_DATA_APP_CONFIG_RES_INVALID_NULL_POINTER	Error: invalid NULL pointer parameter

Definition at line 210 of file wms_data.h.

{
    APP_LIB_DATA_APP_CONFIG_RES_SUCCESS              = 0,
    APP_LIB_DATA_APP_CONFIG_RES_INVALID_ROLE         = 1,
    APP_LIB_DATA_APP_CONFIG_RES_INVALID_APP_CONFIG   = 2,
    APP_LIB_DATA_APP_CONFIG_RES_INVALID_SEQ          = 3,
    APP_LIB_DATA_APP_CONFIG_RES_INVALID_INTERVAL     = 4,
    APP_LIB_DATA_APP_CONFIG_RES_INVALID_NULL_POINTER = 5,
} app_lib_data_app_config_res_e;

app_lib_data_fragmented_mode_e

enum app_lib_data_fragmented_mode_e

Fragmentation mode. Use to specify if reassembly is done by stack or by application itself.

Used with service lib_data->setFragmentMode() to specify the mode

Enumerator
APP_LIB_DATA_FRAGMENTED_MODE_ENABLED	Fragmented mode is enabled so any fragmented packet received by stack will be transmitted directly to app
APP_LIB_DATA_FRAGMENTED_MODE_DISABLED	Fragmented mode is disabled so fragmented packet received by stack will be reassembled by stack and sent to app as a single full packet to app. This mode will use quite a lot a RAM on stack side and is not recommended for a sink receiving a lot of traffic.

Definition at line 234 of file wms_data.h.

{
    APP_LIB_DATA_FRAGMENTED_MODE_ENABLED = 0,
    APP_LIB_DATA_FRAGMENTED_MODE_DISABLED  = 1,
} app_lib_data_fragmented_mode_e;

app_lib_data_qos_e

enum app_lib_data_qos_e

Data quality of service class. Used when sending and receiving data packets.

Used with service lib_data->sendData() and callback functions set with services lib_data->setDataReceivedCb().

Enumerator
APP_LIB_DATA_QOS_NORMAL	Normal quality of service
APP_LIB_DATA_QOS_HIGH	High quality of service, i.e. takes priority over APP_LIB_DATA_QOS_NORMAL quality of service packets

Definition at line 85 of file wms_data.h.

{
    APP_LIB_DATA_QOS_NORMAL = 0,
    APP_LIB_DATA_QOS_HIGH   = 1,
} app_lib_data_qos_e;

app_lib_data_receive_res_e

enum app_lib_data_receive_res_e

Return value of data reception callback.

This result code needs to be returned from the data reception callback functions set with services lib_data->setDataReceivedCb().

Enumerator
APP_LIB_DATA_RECEIVE_RES_HANDLED	Packet was for the application and it was handled successfully. Stack may now discard the packet.
APP_LIB_DATA_RECEIVE_RES_NOT_FOR_APP	Packet was not for the application. Stack may offer the packet to some other module, if present, or discard it.
APP_LIB_DATA_RECEIVE_RES_NO_SPACE	Packet was for the application, but the application cannot handle it right now. Stack is requested to keep the packet in its buffers, until lib_data->allowReception(true) is called.

Definition at line 188 of file wms_data.h.

{
    APP_LIB_DATA_RECEIVE_RES_HANDLED     = 0,
    APP_LIB_DATA_RECEIVE_RES_NOT_FOR_APP = 1,
    APP_LIB_DATA_RECEIVE_RES_NO_SPACE    = 2,
} app_lib_data_receive_res_e;

app_lib_data_send_flags_e

enum app_lib_data_send_flags_e

Flags to use with lib_data->sendData().

Enumerator
APP_LIB_DATA_SEND_FLAG_NONE	Default value, no flag
APP_LIB_DATA_SEND_FLAG_TRACK	Track packet through local processing, i.e. call tracking callback (see lib_data->setDataSentCb()) when packet is finally sent or discarded.
APP_LIB_DATA_SEND_SET_HOP_LIMITING	hop_limit field in transmission definition contains the value of hop limit to be used in sending. Hop limit sets the upper value to the number of hops executed for packet to reach the destination. By using hop limiting, it is possible to limit the distance how far the packet is transmitted to and avoiding causing unnecessary traffic to network. Hop limit value of 0 is used to disable the hop limiting. Hop limiting value does not have any impact when using APP_ADDR_ANYSINK address as destination node address but is discarded.
APP_LIB_DATA_SEND_FLAG_UNACK_CSMA_CA	The unacknowledged CSMA-CA transmission method can be used in a mixed network (i.e. network consisting of both CSMA-CA and time-slotted mode devices) by CSMA-CA device originated packets transmission only to CSMA-CA devices. The purpose of this method is to avoid a performance bottleneck by NOT transmitting to time-slotted mode devices. Note: when using this flag, transmission is always sent beyond sink routing tree
APP_LIB_DATA_SEND_NW_CH_ONLY	Send packet on network channel only. Note, when this is set, it overrides any hop limit definitions the packet otherwise has. These packets are never rerouted. When this flag is used, ONLY devices that are scanning at the moment will receive the packet. Could be used, for example, in asset tracking where devices are scanning network channel.
APP_LIB_DATA_SEND_FRAGMENTED_PACKET	The packet to send is a fragmented packet. When this flag is set, fragment_info from app_lib_data_to_send_t must be set too.

Definition at line 97 of file wms_data.h.

{
    APP_LIB_DATA_SEND_FLAG_NONE   = 0,
    APP_LIB_DATA_SEND_FLAG_TRACK = 1,
    APP_LIB_DATA_SEND_SET_HOP_LIMITING = 4,
    APP_LIB_DATA_SEND_FLAG_UNACK_CSMA_CA = 8,
    APP_LIB_DATA_SEND_NW_CH_ONLY = 16,
    APP_LIB_DATA_SEND_FRAGMENTED_PACKET = 32,
} app_lib_data_send_flags_e;

app_lib_data_send_res_e

enum app_lib_data_send_res_e

A result code returned from lib_data->sendData().

Enumerator
APP_LIB_DATA_SEND_RES_SUCCESS	Data was accepted in stack buffers
APP_LIB_DATA_SEND_RES_INVALID_STACK_STATE	Error: stack is not running
APP_LIB_DATA_SEND_RES_INVALID_QOS	Error: QoS parameter is invalid
APP_LIB_DATA_SEND_RES_INVALID_FLAGS	Error: flags parameter is invalid
APP_LIB_DATA_SEND_RES_OUT_OF_MEMORY	Error: there is no space for data in stack buffers
APP_LIB_DATA_SEND_RES_INVALID_DEST_ADDRESS	Error: destination address parameter is invalid. Special case is for advertiser role where device has tried to send uplink (APP_ADDR_ANYSINK) or tried to send unicast packet to target that is not known.
APP_LIB_DATA_SEND_RES_INVALID_NUM_BYTES	Error: number of bytes parameter is invalid
APP_LIB_DATA_SEND_RES_OUT_OF_TRACKING_IDS	Error: tracking ID already in use, or there are no more tracking IDs available
APP_LIB_DATA_SEND_RES_INVALID_TRACKING_ID	Tracking ID already in use or invalid ID
APP_LIB_DATA_SEND_RES_RESERVED_ENDPOINT	Error: one of the endpoints is invalid, reserved for stack internal use
APP_LIB_DATA_SEND_RES_ACCESS_DENIED	Error: data sending is forbidden, either: Disabled by feature lock bits Sending to prohibited end-point or destination, when joining a network via open joining
APP_LIB_DATA_SEND_RES_INVALID_HOP_LIMIT	Error: Hop limit value is invalid
APP_LIB_DATA_SEND_RES_UNINITIALIZED	Error: Library is uninitialized
APP_LIB_DATA_SEND_RES_INVALID_FRAGMENT_INFO	Error: Provided fragment info is invalid

Definition at line 141 of file wms_data.h.

{
    APP_LIB_DATA_SEND_RES_SUCCESS = 0,
    APP_LIB_DATA_SEND_RES_INVALID_STACK_STATE = 1,
    APP_LIB_DATA_SEND_RES_INVALID_QOS = 2,
    APP_LIB_DATA_SEND_RES_INVALID_FLAGS = 3,
    APP_LIB_DATA_SEND_RES_OUT_OF_MEMORY = 4,
    APP_LIB_DATA_SEND_RES_INVALID_DEST_ADDRESS = 5,
    APP_LIB_DATA_SEND_RES_INVALID_NUM_BYTES = 6,
    APP_LIB_DATA_SEND_RES_OUT_OF_TRACKING_IDS = 7,
    APP_LIB_DATA_SEND_RES_INVALID_TRACKING_ID = 8,
    APP_LIB_DATA_SEND_RES_RESERVED_ENDPOINT = 9,
    APP_LIB_DATA_SEND_RES_ACCESS_DENIED = 10,
    APP_LIB_DATA_SEND_RES_INVALID_HOP_LIMIT = 11,
    APP_LIB_DATA_SEND_RES_UNINITIALIZED = 12,
    APP_LIB_DATA_SEND_RES_INVALID_FRAGMENT_INFO = 13,
} app_lib_data_send_res_e;

Macro Definition Documentation

APP_DATA_DISABLE_LOCAL_MULTICAST

#define APP_DATA_DISABLE_LOCAL_MULTICAST   0

Dedicated value to disable local multicast functionality. To be used with service lib_data->setLocalMulticastInfo().

Definition at line 803 of file wms_data.h.

APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES

#define APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES   80

size of app config

This is a safe size to use for app config data static buffers. Use lib_data->getAppConfigNumBytes() to get actual app config data size in bytes, which may be smaller.

Used with services lib_data->readAppConfig(), lib_data->writeAppConfig() and in callback function set with function lib_data->setNewAppConfigCb().

Definition at line 75 of file wms_data.h.

APP_LIB_DATA_NAME

#define APP_LIB_DATA_NAME   0x0003f161

Library symbolic name

"DATA"

Definition at line 29 of file wms_data.h.

APP_LIB_DATA_NO_TRACKING_ID

#define APP_LIB_DATA_NO_TRACKING_ID   (app_lib_data_tracking_id_t)(-1)

When sending data and no tracking of packet is requested, this ID may be used.

Used with service lib_data->sendData.

Examples

appconfig/app.c, ble_tx/app.c, custom_app/app.c, and ruuvi_evk/app.c.

Definition at line 60 of file wms_data.h.

APP_LIB_DATA_RX_HOPS_UNDETERMINED

#define APP_LIB_DATA_RX_HOPS_UNDETERMINED   0

Unable to determine hop count.

This macro declares special value represented in hops- field of app_lib_data_received_t structure when device has been unable to determine the hop count.

Used in data reception callback functions set with services lib_data->setDataReceivedCb().

Definition at line 261 of file wms_data.h.

APP_LIB_DATA_VERSION

#define APP_LIB_DATA_VERSION   0x20B

Maximum supported library version.

Definition at line 32 of file wms_data.h.