Wirepas SDK
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
allowTrue 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
dataReceived 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
statusStatus 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:

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
priorityMessage priority which queuing time to be read
time_pPointer 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_pPointer 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
bytesNew app config data
seqNew app config data sequence number
intervalNew 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
bytesPointer to a buffer for app config data
seqPointer to app config sequence
intervalPointer 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_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
dataData 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(
{
if (data->dest_endpoint == GET_TEMPERATURE_EP)
{
//start_temperature_measurement();
}
}
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
cbThe 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
cbThe 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
modeMode 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
infoInformation 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
priorityMessage priority which queuing time to be set
timeQueuing 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
cbThe 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
bytesPointer 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:

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
intervalDiagnostic 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
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

Enumeration Type Documentation

◆ 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_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_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_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_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_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.

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.

APP_LIB_DATA_SEND_RES_OUT_OF_MEMORY
@ APP_LIB_DATA_SEND_RES_OUT_OF_MEMORY
Definition: wms_data.h:152
APP_LIB_DATA_SEND_FLAG_TRACK
@ APP_LIB_DATA_SEND_FLAG_TRACK
Definition: wms_data.h:104
app_lib_data_sent_status_t
Struct to tracking callback function.
Definition: wms_data.h:372
app_lib_data_send_res_e
app_lib_data_send_res_e
A result code returned from lib_data->sendData().
Definition: wms_data.h:141
APP_LIB_DATA_APP_CONFIG_RES_INVALID_ROLE
@ APP_LIB_DATA_APP_CONFIG_RES_INVALID_ROLE
Definition: wms_data.h:215
app_lib_data_qos_e
app_lib_data_qos_e
Data quality of service class. Used when sending and receiving data packets.
Definition: wms_data.h:85
APP_LIB_DATA_APP_CONFIG_RES_INVALID_SEQ
@ APP_LIB_DATA_APP_CONFIG_RES_INVALID_SEQ
Definition: wms_data.h:220
APP_LIB_DATA_SEND_FLAG_UNACK_CSMA_CA
@ APP_LIB_DATA_SEND_FLAG_UNACK_CSMA_CA
Definition: wms_data.h:124
APP_LIB_DATA_SEND_NW_CH_ONLY
@ APP_LIB_DATA_SEND_NW_CH_ONLY
Definition: wms_data.h:131
APP_LIB_DATA_SEND_RES_INVALID_QOS
@ APP_LIB_DATA_SEND_RES_INVALID_QOS
Definition: wms_data.h:148
APP_LIB_DATA_SEND_FLAG_NONE
@ APP_LIB_DATA_SEND_FLAG_NONE
Definition: wms_data.h:100
APP_LIB_DATA_APP_CONFIG_RES_INVALID_NULL_POINTER
@ APP_LIB_DATA_APP_CONFIG_RES_INVALID_NULL_POINTER
Definition: wms_data.h:224
APP_LIB_DATA_SEND_RES_INVALID_DEST_ADDRESS
@ APP_LIB_DATA_SEND_RES_INVALID_DEST_ADDRESS
Definition: wms_data.h:157
APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES
#define APP_LIB_DATA_MAX_APP_CONFIG_NUM_BYTES
size of app config
Definition: wms_data.h:75
app_lib_data_app_config_res_e
app_lib_data_app_config_res_e
Result of the app config.
Definition: wms_data.h:210
app_lib_data_data_size_t
Definition: wms_data.h:530
APP_LIB_DATA_RECEIVE_RES_HANDLED
@ APP_LIB_DATA_RECEIVE_RES_HANDLED
Definition: wms_data.h:192
APP_LIB_DATA_SEND_RES_RESERVED_ENDPOINT
@ APP_LIB_DATA_SEND_RES_RESERVED_ENDPOINT
Definition: wms_data.h:167
APP_LIB_DATA_SEND_RES_INVALID_FRAGMENT_INFO
@ APP_LIB_DATA_SEND_RES_INVALID_FRAGMENT_INFO
Definition: wms_data.h:178
app_lib_data_send_flags_e
app_lib_data_send_flags_e
Flags to use with lib_data->sendData().
Definition: wms_data.h:97
APP_LIB_DATA_SEND_FRAGMENTED_PACKET
@ APP_LIB_DATA_SEND_FRAGMENTED_PACKET
Definition: wms_data.h:134
APP_LIB_DATA_SEND_RES_OUT_OF_TRACKING_IDS
@ APP_LIB_DATA_SEND_RES_OUT_OF_TRACKING_IDS
Definition: wms_data.h:162
APP_LIB_DATA_SEND_RES_INVALID_HOP_LIMIT
@ APP_LIB_DATA_SEND_RES_INVALID_HOP_LIMIT
Definition: wms_data.h:174
APP_LIB_DATA_SEND_RES_INVALID_TRACKING_ID
@ APP_LIB_DATA_SEND_RES_INVALID_TRACKING_ID
Definition: wms_data.h:164
app_lib_data_receive_res_e
app_lib_data_receive_res_e
Return value of data reception callback.
Definition: wms_data.h:188
app_lib_data_received_t::dest_endpoint
uint8_t dest_endpoint
Definition: wms_data.h:300
APP_LIB_DATA_SEND_RES_ACCESS_DENIED
@ APP_LIB_DATA_SEND_RES_ACCESS_DENIED
Definition: wms_data.h:172
APP_LIB_DATA_RECEIVE_RES_NO_SPACE
@ APP_LIB_DATA_RECEIVE_RES_NO_SPACE
Definition: wms_data.h:200
APP_LIB_DATA_SEND_RES_INVALID_STACK_STATE
@ APP_LIB_DATA_SEND_RES_INVALID_STACK_STATE
Definition: wms_data.h:146
APP_LIB_DATA_APP_CONFIG_RES_INVALID_APP_CONFIG
@ APP_LIB_DATA_APP_CONFIG_RES_INVALID_APP_CONFIG
Definition: wms_data.h:218
app_global_functions_t
List of global functions, passed to App_entrypoint()
Definition: wms_app.h:157
APP_LIB_DATA_SEND_RES_INVALID_FLAGS
@ APP_LIB_DATA_SEND_RES_INVALID_FLAGS
Definition: wms_data.h:150
APP_LIB_DATA_QOS_HIGH
@ APP_LIB_DATA_QOS_HIGH
Definition: wms_data.h:91
APP_LIB_DATA_SEND_SET_HOP_LIMITING
@ APP_LIB_DATA_SEND_SET_HOP_LIMITING
Definition: wms_data.h:116
app_lib_data_received_t
Struct passed to data reception callback functions.
Definition: wms_data.h:283
app_lib_data_fragmented_mode_e
app_lib_data_fragmented_mode_e
Fragmentation mode. Use to specify if reassembly is done by stack or by application itself.
Definition: wms_data.h:234
APP_LIB_DATA_FRAGMENTED_MODE_ENABLED
@ APP_LIB_DATA_FRAGMENTED_MODE_ENABLED
Definition: wms_data.h:239
APP_LIB_DATA_APP_CONFIG_RES_INVALID_INTERVAL
@ APP_LIB_DATA_APP_CONFIG_RES_INVALID_INTERVAL
Definition: wms_data.h:222
APP_LIB_DATA_SEND_RES_UNINITIALIZED
@ APP_LIB_DATA_SEND_RES_UNINITIALIZED
Definition: wms_data.h:176
APP_LIB_DATA_RECEIVE_RES_NOT_FOR_APP
@ APP_LIB_DATA_RECEIVE_RES_NOT_FOR_APP
Definition: wms_data.h:195
APP_LIB_DATA_SEND_RES_SUCCESS
@ APP_LIB_DATA_SEND_RES_SUCCESS
Definition: wms_data.h:144
APP_LIB_DATA_SEND_RES_INVALID_NUM_BYTES
@ APP_LIB_DATA_SEND_RES_INVALID_NUM_BYTES
Definition: wms_data.h:159
APP_LIB_DATA_QOS_NORMAL
@ APP_LIB_DATA_QOS_NORMAL
Definition: wms_data.h:88
APP_LIB_DATA_APP_CONFIG_RES_SUCCESS
@ APP_LIB_DATA_APP_CONFIG_RES_SUCCESS
Definition: wms_data.h:213
APP_LIB_DATA_FRAGMENTED_MODE_DISABLED
@ APP_LIB_DATA_FRAGMENTED_MODE_DISABLED
Definition: wms_data.h:247