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 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_depracated_f) (void)
	This service has been DEPRACATED! 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 size_t(*	app_lib_data_get_data_max_num_bytes_f) (void)
	Return the maximum number of bytes per data packet. 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 services lib_data->setDataReceivedCb() and lib_data->setBcastDataReceivedCb()), 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 app_lib_data_app_config_res_e(*	app_lib_data_write_app_config_f) (const uint8_t *bytes, uint8_t seq, uint16_t interval)
	Write 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...

Data Structures
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_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 }
	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 }
	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...

Macros
#define	APP_LIB_DATA_NAME 0x0003f161
	Library symbolic name More...

#define	APP_LIB_DATA_VERSION 0x209
	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...

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 services lib_data->setDataReceivedCb() and lib_data->setBcastDataReceivedCb()), 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 608 of file 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() or lib_data->setBcastDataReceivedCb().

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 362 of file 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 374 of file data.h.

◆ app_lib_data_depracated_f

typedef app_res_e(* app_lib_data_depracated_f) (void)

This service has been DEPRACATED!

Returns: APP_RES_RESOURCE_UNAVAILABLE

Definition at line 449 of file 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 707 of file data.h.

◆ app_lib_data_get_data_max_num_bytes_f

typedef size_t(* app_lib_data_get_data_max_num_bytes_f) (void)

Return the maximum number of bytes per data packet.

Different platforms have differently sized radio packets, so this value varies by platform.

Example:

size_t maxlen;

maxlen = lib_data->getDataMaxNumBytes();

Returns: Maximum size of data packet in bytes

Definition at line 511 of file 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 757 of file 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 534 of file 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 563 of file 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 393 of file 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 633 of file 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 580 of file 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. There are two distinct callbacks: one for receiving unicast data is data that is addressed directly to a specific node (calling lib_data->setDataReceivedCb()) and another one for receiving multicast and broadcasts (calling lib_data->setBcastDataReceivedCb()). 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);
    lib_data->setBcastDataReceivedCb(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 442 of file 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 480 of file 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 737 of file 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 494 of file 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.

Examples: inventory_app_tag/app.c.

Definition at line 52 of file 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 785 of file data.h.

◆ app_lib_data_write_app_config_f

typedef app_lib_data_app_config_res_e(* app_lib_data_write_app_config_f) (const uint8_t *bytes, uint8_t seq, uint16_t interval)

Write app config.

Parameters

bytes	Pointer to app config data to write. The format can be decided by the application.
seq	Sequence number for filtering old and already received application configuration data packets at the nodes. The sequence number must be increment by 1 every time new configuration is written, i.e. new diagnostic data interval and/or new application configuration data is updated. A sequence number that is the current value of existing application configuration data is invalid. A value of 255 is invalid. Therefore, after value of 254, the next valid value is 0.
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 configuration data is not written too often, as new configuration data 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.; This service is deprecated and has been replaced by writeAppConfigData and writeDiagnosticInterval that manages sequence increment automatically.

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);
 
// Use otherwise same appconfig but set diagnostics to 30s
appconfig_seq++;
if (appconfig_seq == 255)
{
    appconfig_seq = 0;
}
lib_data->writeAppConfig(&appconfig[0],
                        &appconfig_seq,
                        30);

Definition at line 693 of file 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 812 of file data.h.

Data Structure Documentation

◆ 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() and lib_data->setBcastDataReceivedCb().

Examples: basic_interrupt/app.c, ble_scanner/app.c, ble_tx/app.c, custom_app/app.c, inventory_app_router/app.c, inventory_app_tag/app.c, and shared_data/app.c.

Definition at line 244 of file 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
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, inventory_app_router/app.c, inventory_app_tag/app.c, ruuvi_evk/app.c, and shared_data/app.c.

Definition at line 288 of file 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
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: dualmcu_app/app.c, inventory_app_router/app.c, inventory_app_tag/app.c, and shared_data/app.c.

Definition at line 325 of file 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_t

struct app_lib_data_t

List of library services.

Definition at line 817 of file 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_depracated_f	reserved
app_lib_data_send_data_f	sendData
app_lib_data_set_data_received_cb_f	setBcastDataReceivedCb
app_lib_data_set_data_received_cb_f	setDataReceivedCb
app_lib_data_set_data_sent_cb_f	setDataSentCb
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_f	writeAppConfig
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 206 of file 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_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() and lib_data->setBcastDataReceivedCb().

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 87 of file 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() and lib_data->setBcastDataReceivedCb().

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 184 of file 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 tracking of packet
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.

Definition at line 99 of file 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_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

Definition at line 140 of file 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_e;

Macro Definition Documentation

◆ 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 data.h.

◆ APP_LIB_DATA_NAME

#define APP_LIB_DATA_NAME 0x0003f161

Library symbolic name

"DATA"

Definition at line 29 of file 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, basic_interrupt/app.c, ble_scanner/app.c, ble_tx/app.c, custom_app/app.c, inventory_app_tag/app.c, and ruuvi_evk/app.c.

Definition at line 60 of file 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() and lib_data->setBcastDataReceivedCb().

Definition at line 234 of file data.h.

◆ APP_LIB_DATA_VERSION

#define APP_LIB_DATA_VERSION 0x209

Maximum supported library version.

Definition at line 32 of file data.h.

Detailed Description

Typedefs

Data Structures

Enumerations

Macros

Typedef Documentation

◆ app_lib_data_allow_reception_f

◆ app_lib_data_data_received_cb_f

◆ app_lib_data_data_sent_cb_f

◆ app_lib_data_depracated_f

◆ app_lib_data_get_app_config_num_bytes_f

◆ app_lib_data_get_data_max_num_bytes_f

◆ app_lib_data_get_max_msg_queuing_time_f

◆ app_lib_data_get_num_buffers_f

◆ app_lib_data_get_num_free_buffers_f

◆ app_lib_data_new_app_config_cb_f

◆ app_lib_data_read_app_config_f

◆ app_lib_data_send_data_f

◆ app_lib_data_set_data_received_cb_f

◆ app_lib_data_set_data_sent_cb_f

◆ app_lib_data_set_max_msg_queuing_time_f

◆ app_lib_data_set_new_app_config_cb_f

◆ app_lib_data_tracking_id_t

◆ app_lib_data_write_app_config_data_f

◆ app_lib_data_write_app_config_f

◆ app_lib_data_write_diagnostic_interval_f

Data Structure Documentation

◆ app_lib_data_received_t

◆ app_lib_data_to_send_t

◆ app_lib_data_sent_status_t

◆ app_lib_data_t

Enumeration Type Documentation

◆ app_lib_data_app_config_res_e

◆ app_lib_data_qos_e

◆ app_lib_data_receive_res_e

◆ app_lib_data_send_flags_e

◆ app_lib_data_send_res_e

Macro Definition Documentation

◆ APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES

◆ APP_LIB_DATA_NAME

◆ APP_LIB_DATA_NO_TRACKING_ID

◆ APP_LIB_DATA_RX_HOPS_UNDETERMINED

◆ APP_LIB_DATA_VERSION