Detailed Description

Application library for viewing and controlling stack runtime state

Library services are accessed via lib_state handle.

Definition in file state.h.

Typedefs
typedef void(*	app_lib_state_on_scan_nbors_cb_f) (void)
	Function type for a neighbor scan completion callback. More...

typedef void(*	app_lib_state_on_beacon_cb_f) (const app_lib_state_beacon_rx_t *beacon)
	Function type for a beacon reception callback. More...

typedef app_res_e(*	app_lib_state_start_stack_f) (void)
	Start the stack. More...

typedef app_res_e(*	app_lib_state_stop_stack_f) (void)
	Stop the stack. More...

typedef uint8_t(*	app_lib_state_get_stack_state_f) (void)
	Get the stack state. More...

typedef uint8_t(*	app_lib_state_get_route_count_f) (size_t *count_p)
	Get the number of routes this node has to a sink. More...

typedef uint16_t(*	app_lib_state_get_diag_interval_f) (void)
	Get diagnostics interval. More...

typedef app_res_e(*	app_lib_state_get_access_cycle_f) (uint16_t *ac_value_p)
	Get current access cycle. More...

typedef app_res_e(*	app_lib_state_set_on_scan_nbors_with_type_cb_f) (app_lib_state_on_scan_nbors_cb_f cb, app_lib_state_scan_nbors_type_e type)
	Set a callback to be called when neighbor scan is complete. More...

typedef app_res_e(*	app_lib_state_start_scan_nbors_f) (void)
	Start neighbor scan. More...

typedef app_res_e(*	app_lib_state_get_nbors_f) (app_lib_state_nbor_list_t *nbors_list)
	Get list of neighbors. More...

typedef app_res_e(*	app_lib_state_set_on_beacon_cb_f) (app_lib_state_on_beacon_cb_f cb)
	Set a callback to be called when a beacon is received. More...

typedef app_res_e(*	app_lib_state_get_energy_f) (uint8_t *energy_p)
	Get available energy. More...

typedef app_res_e(*	app_lib_state_set_energy_f) (uint8_t energy)
	Set available energy. More...

typedef app_res_e(*	app_lib_state_get_sink_cost_f) (uint8_t *cost_p)
	Query the currently set additional penalty for the sink usage. More...

typedef app_res_e(*	app_lib_state_set_sink_cost_f) (const uint8_t cost)
	Set additional penalty for the sink usage. More...

typedef void(*	app_lib_state_route_changed_cb_f) (void)
	Callback when route is changed. More...

typedef app_res_e(*	app_lib_state_get_route_f) (app_lib_state_route_info_t *info)
	Get route information. More...

typedef app_res_e(*	app_lib_state_set_route_cb_f) (const app_lib_state_route_changed_cb_f cb, uint32_t unused)
	Set callback for route change notification. More...

typedef uint8_t(*	app_lib_state_adjust_hops_cb_f) (const app_lib_state_hops_adjust_t *info)
	Function type for a adjusting hops left. More...

typedef app_res_e(*	app_lib_state_set_adjust_hops_cb_f) (app_lib_state_adjust_hops_cb_f cb)
	Set a callback to be called when rerouting packet and querying if 'hops left' should be modified (i.e. limiting the propagation of packet further) More...

typedef app_res_e(*	app_lib_state_set_scan_dur_f) (uint32_t duration_us)
	Set scan duration to be used. More...

typedef app_res_e(*	app_lib_state_scan_stop_f) (void)
	Stops ongoing scan operation before ended. More...

typedef app_res_e(*	app_lib_state_get_install_quality_f) (app_lib_state_install_quality_t *qual_out)
	Read installation quality, app_lib_state_install_quality_t. More...

Data Structures
struct	app_lib_state_nbor_info_t
	Neighbors info definition. More...

struct	app_lib_state_nbor_list_t
	Neighbors list definition. More...

struct	app_lib_state_beacon_rx_t
	Structure to hold the information about received beacons. More...

struct	app_lib_state_hops_adjust_t
	Structure for adjusting hops. More...

struct	app_lib_state_route_info_t
	Structure for route information. More...

struct	app_lib_state_install_quality_t
	Installation quality information. Contains information about the nodes installation location i.e. its quality indicated by a numeric value, as well as error codes if something is wrong with the location. More...

struct	app_lib_state_t
	List of library functions of v3 version (0x202) More...

Enumerations
enum	app_lib_state_nbor_type_e { APP_LIB_STATE_NEIGHBOR_IS_NEXT_HOP = 0, APP_LIB_STATE_NEIGHBOR_IS_MEMBER = 1, APP_LIB_STATE_NEIGHBOR_IS_CLUSTER = 2 }
	Neighbor type. More...

enum	app_lib_state_diradv_support_e { APP_LIB_STATE_DIRADV_SUPPORTED = 0, APP_LIB_STATE_DIRADV_NOT_SUPPORTED = 1, APP_LIB_STATE_DIRADV_UNKNOWN = 2 }
	Support type for directed advertiser, i.e. does neighbor support sending directed advertiser packets to it. More...

enum	app_lib_state_scan_nbors_type_e { APP_LIB_STATE_SCAN_NBORS_ALL = 0, APP_LIB_STATE_SCAN_NBORS_ONLY_REQUESTED = 1 }
	Scan neighbor type to specify the scans that trigger the callback. More...

enum	app_lib_state_stack_state_e { APP_LIB_STATE_STARTED = 0, APP_LIB_STATE_STOPPED = 1, APP_LIB_STATE_NODE_ADDRESS_NOT_SET = 2, APP_LIB_STATE_NETWORK_ADDRESS_NOT_SET = 4, APP_LIB_STATE_NETWORK_CHANNEL_NOT_SET = 8, APP_LIB_STATE_ROLE_NOT_SET = 16, APP_LIB_STATE_APP_CONFIG_DATA_NOT_SET = 32, APP_LIB_STATE_ACCESS_DENIED = 128 }
	Stack state flags. More...

enum	app_lib_state_route_state_e { APP_LIB_STATE_ROUTE_STATE_INVALID = 0, APP_LIB_STATE_ROUTE_STATE_PENDING = 1, APP_LIB_STATE_ROUTE_STATE_VALID = 2 }
	Route state. More...

enum	app_lib_state_beacon_type_e { APP_LIB_STATE_BEACON_TYPE_NB = 0, APP_LIB_STATE_BEACON_TYPE_CB = 1 }
	Type for beacons, passed in app_lib_state_beacon_rx_t. More...

enum	install_quality_error_code_e { APP_LIB_STATE_INSTALL_QUALITY_ERROR_NONE = 0x00, APP_LIB_STATE_INSTALL_QUALITY_ERROR_NOROUTE = 0x01, APP_LIB_STATE_INSTALL_QUALITY_ERROR_NONBORS = 0x02, APP_LIB_STATE_INSTALL_QUALITY_ERROR_BADRSSI = 0x04 }
	Error codes for installation quality, if an error code is active, corrective action regarding the installation location is required. More...

Macros
#define	APP_LIB_STATE_NAME 0x02f9c165
	Library symbolic name. More...

#define	APP_LIB_STATE_VERSION 0x20A
	Maximum supported library version. More...

#define	APP_LIB_STATE_INVALID_ROUTE_COST UINT8_MAX
	Macro for cost indicating "no route". Used in cost component in lib_state->getNbors() service. More...

#define	APP_LIB_STATE_COST_UNKNOWN 0
	Macro for cost being unknown. Used in cost component in lib_state->getNbors() service. More...

#define	APP_LIB_STATE_LINKREL_UNKNOWN 0
	Macro for link reliability being unknown. Used in link reliability component in lib_state->getNbors() service. More...

#define	APP_LIB_STATE_DEFAULT_SCAN 0
	Macro for using with lib_state->setScanDuration() to disable custom scan duration and use stack default scan duration. More...

Typedef Documentation

◆ app_lib_state_adjust_hops_cb_f

typedef uint8_t(* app_lib_state_adjust_hops_cb_f) (const app_lib_state_hops_adjust_t *info)

Function type for a adjusting hops left.

Parameters

info	Info about packet that is rerouted

Returns: Amount of hops left. If unmodified, use value info->hops_left.

Note: Either decrease or leave intact the return value. If amount of hops left is increased (from originally hop-limited transmission), value is discarded.

Usage: see documentation on lib_state->setHopsLeftCb() on how to use this callback.

Definition at line 596 of file state.h.

◆ app_lib_state_get_access_cycle_f

typedef app_res_e(* app_lib_state_get_access_cycle_f) (uint16_t *ac_value_p)

Get current access cycle.

Parameters

ac_value_p Pointer to store the current access cycle value in milliseconds Updated if return code is APP_RES_OK

Returns: Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack not running

Definition at line 404 of file state.h.

◆ app_lib_state_get_diag_interval_f

typedef uint16_t(* app_lib_state_get_diag_interval_f) (void)

Get diagnostics interval.

Returns: Diagnostics interval in seconds

Definition at line 394 of file state.h.

◆ app_lib_state_get_energy_f

typedef app_res_e(* app_lib_state_get_energy_f) (uint8_t *energy_p)

Get available energy.

Parameters

energy_p Pointer to store the available energy as a proportional value from 0 to 255

Returns: Result code, always APP_RES_NOT_IMPLEMENTED

Note: This is legacy service used in stack versions <5.1.0.

Definition at line 494 of file state.h.

◆ app_lib_state_get_install_quality_f

typedef app_res_e(* app_lib_state_get_install_quality_f) (app_lib_state_install_quality_t *qual_out)

Read installation quality, app_lib_state_install_quality_t.

Parameters

qual_out [out] The installation quality information is copied to this pointer

Returns: APP_RES_OK if value was read OK

Definition at line 717 of file state.h.

◆ app_lib_state_get_nbors_f

typedef app_res_e(* app_lib_state_get_nbors_f) (app_lib_state_nbor_list_t *nbors_list)

Get list of neighbors.

Parameters

nbors_list Pointer to store the information of list of neighbors.

Returns: Result code, always APP_RES_OK

This service can be used to tell the status of a node's neighbors. This information may be used for various purposes, for example to estimate where a node is located.

Example:

#define NBOR_LIST_SIZE   6
app_lib_state_nbor_info_t nbors[NBOR_LIST_SIZE];
app_lib_state_nbor_list_t nbors_list =
{
    .number_nbors = NBOR_LIST_SIZE,
    .nbors = &nbors[0]
};
...
lib_state->getNbors(&nbors_list);

Definition at line 474 of file state.h.

◆ app_lib_state_get_route_count_f

typedef uint8_t(* app_lib_state_get_route_count_f) (size_t *count_p)

Get the number of routes this node has to a sink.

Parameters

count_p Pointer to store the result. Whenever there is a route to sink, value is 1, otherwise 0.

Returns: Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack not running

Example:

size_t hasroute;

lib_state->getRouteCount(&hasroute);

Definition at line 388 of file state.h.

◆ app_lib_state_get_route_f

typedef app_res_e(* app_lib_state_get_route_f) (app_lib_state_route_info_t *info)

Get route information.

Parameters

info	[out] Route information is provided here

Returns: Result code, APP_RES_OK if successful

Definition at line 567 of file state.h.

◆ app_lib_state_get_sink_cost_f

typedef app_res_e(* app_lib_state_get_sink_cost_f) (uint8_t *cost_p)

Query the currently set additional penalty for the sink usage.

Parameters

cost_p Pointer to store the current initial cost

Returns: Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if node is not a sink, APP_RES_INVALID_NULL_POINTER if cost_p is NULL

Example:

uint8_t current_cost;

lib_state->getSinkCost(&current_cost);

Definition at line 525 of file state.h.

◆ app_lib_state_get_stack_state_f

typedef uint8_t(* app_lib_state_get_stack_state_f) (void)

Get the stack state.

Returns: Bit field of stack state, app_lib_state_stack_state_e

Service indicates whether the stack is running or not, and whether it can be started.

Example:

app_lib_state_stack_state_e state;

state = lib_state->getStackState();

Definition at line 372 of file state.h.

◆ app_lib_state_on_beacon_cb_f

typedef void(* app_lib_state_on_beacon_cb_f) (const app_lib_state_beacon_rx_t *beacon)

Function type for a beacon reception callback.

Parameters

beacon Information about received beacon

Definition at line 309 of file state.h.

◆ app_lib_state_on_scan_nbors_cb_f

typedef void(* app_lib_state_on_scan_nbors_cb_f) (void)

Function type for a neighbor scan completion callback.

Definition at line 301 of file state.h.

◆ app_lib_state_route_changed_cb_f

typedef void(* app_lib_state_route_changed_cb_f) (void)

Callback when route is changed.

Used with app_lib_state_set_route_cb_f Function prototype for a route information changed callback. The stack invokes this callback whenever anything in the route information structure has changed. This can be utilized to wake up the application to reach such information. Do not read the route information directly in this callback's context.

Definition at line 558 of file state.h.

◆ app_lib_state_scan_stop_f

typedef app_res_e(* app_lib_state_scan_stop_f) (void)

Stops ongoing scan operation before ended.

Returns: Normally APP_RES_OK. APP_RES_INVALID_CONFIGURATION if device is not APP_LIB_SETTINGS_ROLE_ADVERTISER nor APP_LIB_SETTINGS_ROLE_SUBNODE, APP_RES_RESOURCE_UNAVAILABLE if memory has ran out, APP_RES_INVALID_STACK_STATE if stack is not running.

This service aborts ongoing scan operation started with lib_state->startScanNbors().

Definition at line 708 of file state.h.

◆ app_lib_state_set_adjust_hops_cb_f

typedef app_res_e(* app_lib_state_set_adjust_hops_cb_f) (app_lib_state_adjust_hops_cb_f cb)

Set a callback to be called when rerouting packet and querying if 'hops left' should be modified (i.e. limiting the propagation of packet further)

Parameters

cb	Callback function to be called when querying hops left adjusting. NULL to disable callback function.

Returns: Result code, always APP_RES_OK

The mechanism is intended to be used with 'local multicast groups'. Then, the propagation of packet is limited to the edge of the multicast group. If following assumptions apply, this can be done: 1) Multicast group X is 'concise', i.e. ALL devices that belong to multicast group X are close to each other. 2) There are no devices that do not belong to multicast group X 'in middle' of multicast group X 3) Originator of the command is close to multicast group X.

If these apply, then following can be done:

If packet is transmitted to group X and routing device belongs to this group, do not modify the hops left.
If packet is transmitted to group X but routing device does NOT belong to this group, decrease hops left value. Note: do not set it immediately to 0 because that would lead to reliability problems at the edge of the group

Example:
// This device belongs to this group

#define OWN_GROUP (APP_ADDR_MULTICAST | 1)

bool group_query_cb(app_addr_t group_addr)

{

return (group_addr == OWN_GROUP);

}

uint8_t on_hopsleft_cb(const app_lib_state_hops_left_adjust_t * info)

{

if (group_query_cb(info->address))

{

// Belongs to a group, do not modify

return info->hops_left;

}

else

{

// Limit to 2 hops (max)

return 2;

}

}

void App_init(const app_global_functions_t * functions)

{

lib_settings->registerGroupQuery(group_query_cb);

lib_state->setHopsLeftCb(on_hopsleft_cb);

// ...

lib_state->startStack();

}

Note
This service is going to be deprecated in next feature release of Wirepas Mesh, i.e. 5.2.0 and later versions won't have this service supported.

Definition at line 661 of file state.h.

◆ app_lib_state_set_energy_f

typedef app_res_e(* app_lib_state_set_energy_f) (uint8_t energy)

Set available energy.

Parameters

energy

Available energy as a proportional value from 0 to 255

0 corresponds to a state where the node is almost out of energy
255 corresponds to a state where maximum amount of energy is available. Also if there is no means to evaluate remaining energy, this value should be used.

Returns: Result code, always APP_RES_NOT_IMPLEMENTED

Note: This is legacy service used in stack versions <5.1.0.

Definition at line 509 of file state.h.

◆ app_lib_state_set_on_beacon_cb_f

typedef app_res_e(* app_lib_state_set_on_beacon_cb_f) (app_lib_state_on_beacon_cb_f cb)

Set a callback to be called when a beacon is received.

Parameters

cb	The function to be executed, or NULL to unset

Returns: Result code, always APP_RES_OK

Definition at line 483 of file state.h.

◆ app_lib_state_set_on_scan_nbors_with_type_cb_f

typedef app_res_e(* app_lib_state_set_on_scan_nbors_with_type_cb_f) (app_lib_state_on_scan_nbors_cb_f cb, app_lib_state_scan_nbors_type_e type)

Set a callback to be called when neighbor scan is complete.

Parameters

cb	The function to be executed, or NULL to unset
type	The type of scan event app is interested (Unused if cb is NULL)

Returns: Result code

Example:

static void onScannedNborsCb(void)
{
   ...
}
 
...
lib_state->setOnScanNborsCb(onScannedNborsCb, APP_LIB_STATE_SCAN_NBORS_ALL);
...

Definition at line 429 of file state.h.

◆ app_lib_state_set_route_cb_f

typedef app_res_e(* app_lib_state_set_route_cb_f) (const app_lib_state_route_changed_cb_f cb, uint32_t unused)

Set callback for route change notification.

When route information changes, the application is notified via this handle.

Parameters

cb	Callback called on route change
unused	Unused parameter, always set to 0

Returns: Result code, APP_RES_OK if successful

Definition at line 581 of file state.h.

◆ app_lib_state_set_scan_dur_f

typedef app_res_e(* app_lib_state_set_scan_dur_f) (uint32_t duration_us)

Set scan duration to be used.

Parameters

duration_us Scan duration in microseconds. If duration_us is APP_LIB_STATE_DEFAULT_SCAN, use default-length value and perform similar length as standard stack scan operation

Returns: APP_RES_OK if values is ok, APP_RES_INVALID_VALUE if value is too large or small. APP_RES_INVALID_CONFIGURATION if device is not APP_LIB_SETTINGS_ROLE_ADVERTISER nor APP_LIB_SETTINGS_ROLE_SUBNODE.

Example:

uint32_t do_short_scan(void)
{
    // Perform scan of 0.5 seconds only
    lib_state->setScanDuration(500000);
    lib_state->startScanNbors();
    // Perform only once
    return APP_LIB_SYSTEM_STOP_PERIODIC;
}
 
void App_init(const app_global_functions_t * functions)
{
    // ...
    // Create short scan in 10 seconds
    lib_system->setPeriodicCb(do_short_scan, 10000000, 1000);
    lib_state->startStack();
}

Definition at line 695 of file state.h.

◆ app_lib_state_set_sink_cost_f

typedef app_res_e(* app_lib_state_set_sink_cost_f) (const uint8_t cost)

Set additional penalty for the sink usage.

This service can be used to inform the sink that the backend communication has problems. In order to keep the entire network operational, other nodes can be forced to use other sinks with working backend communication

Parameters

cost	Value of 0 means that connection is good and no additional penalty is sent to sink usage. Value of 254 includes maximum penalty

Returns: Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if node is not a sink

Example on use:

lib_state->setSinkCost(8);

Definition at line 546 of file state.h.

◆ app_lib_state_start_scan_nbors_f

typedef app_res_e(* app_lib_state_start_scan_nbors_f) (void)

Start neighbor scan.

This service can be used by the application to get fresh information about neighbors. Application can trigger to measurement all neighbors and once the measurement is done, application is informed it over API (see lib_state->setOnScanNborsCb service).

Returns: Result code, always APP_RES_OK unless stack is not running when APP_RES_INVALID_STACK_STATE is returned.

Example:

lib_state->startScanNbors();

Definition at line 448 of file state.h.

◆ app_lib_state_start_stack_f

typedef app_res_e(* app_lib_state_start_stack_f) (void)

Start the stack.

This is most commonly used in the end of the App_init() function to start the radio operation.

Example:

void App_init(const app_global_functions_t * functions)
{
    ...
    // Start the stack
    lib_state->startStack();
}

In order to start, the stack needs minimum of four following attributes to be configured: device role, device address, network address and network channel. These attributes can be set by the application thanks to the Single-MCU API during the initialization step. Device role, network address and network channel can be hardcoded in the application image.

Returns: Result code, APP_RES_OK if successful

Definition at line 339 of file state.h.

◆ app_lib_state_stop_stack_f

typedef app_res_e(* app_lib_state_stop_stack_f) (void)

Stop the stack.

Returns: Result code, APP_RES_OK if successful

Note: Stopping the stack will reboot the system. The system shutdown callback set with lib_system->setShutdownCb() is called just before rebooting. Node configuration may be done in this callback; This function never returns

Example:

lib_state->stopStack();

Definition at line 357 of file state.h.

Data Structure Documentation

◆ app_lib_state_nbor_info_t

struct app_lib_state_nbor_info_t

Neighbors info definition.

Definition at line 105 of file state.h.

Data Fields
uint32_t	address	Address of the neighbor node
uint8_t	channel	Radio channel used by the neighbor
uint8_t	cost	Route cost to the sink via this neighbor. Value of APP_LIB_STATE_INVALID_ROUTE_COST indicates that a neighbor has no route to a sink. Value of APP_LIB_STATE_COST_UNKNOWN states that cost is unknown for this neighbor.
uint8_t	diradv_support	Is directed advertiser supported, app_lib_state_diradv_support_e
uint16_t	last_update	Aount of seconds since these values were last updated.
uint8_t	link_reliability	Link reliability to the neighboring node. Scaled so that 0 = 0 %, 255 = 100 %. Value of APP_LIB_STATE_LINKREL_UNKNOWN tells that link reliability to this neighbor is unknown.
int8_t	norm_rssi	Received signal strength, compensated with transmission power, i.e. this value answers the question "what would the RSSI be, if the neighbor transmits with its maximum TX power". Larger value means better signal. rssi < receiver sensitivity + 10 dB : Insufficient signal level receiver sensitivity + 10 dB <= rssi < receiver_sensitivity + 20 dB : weak signal level rssi >= receiver sensitivity + 20 dB : Good signal level. Note weak signal level is likely to work in environments without interference but the probability for connection problems in networks having some background interference then increases
int8_t	rx_power	Transmission power used when neighbor sending to this device Note Only relevant for type having value of APP_LIB_STATE_NEIGHBOR_IS_NEXT_HOP or APP_LIB_STATE_NEIGHBOR_IS_MEMBER
int8_t	tx_power	Transmission power used when sending to neighbor. Note Only relevant for type having value of APP_LIB_STATE_NEIGHBOR_IS_NEXT_HOP or APP_LIB_STATE_NEIGHBOR_IS_MEMBER
uint8_t	type	Type of the neighbor. app_lib_state_nbor_type_e

◆ app_lib_state_nbor_list_t

struct app_lib_state_nbor_list_t

Neighbors list definition.

Definition at line 154 of file state.h.

Data Fields
app_lib_state_nbor_info_t *	nbors	Information of neighbors received
uint32_t	number_nbors	Input: Maximum amount of neighbors in nbors field. Output: Amount of neighbors filled

◆ app_lib_state_beacon_rx_t

struct app_lib_state_beacon_rx_t

Structure to hold the information about received beacons.

Examples: inventory_app_tag/app.c.

Definition at line 202 of file state.h.

Data Fields
app_addr_t	address	Address of the beacon sender.
uint8_t	cost	Cost of the device. 255==no route.
bool	is_da_support	Sender supports Directed Advertiser sending packets to it.
bool	is_ll	Device is LL.
bool	is_sink	Device is sink.
int8_t	rssi	RSSI in dBm. Larger value means better signal. rssi < receiver sensitivity + 10 dB : Insufficient signal level receiver sensitivity + 10 dB <= rssi < receiver_sensitivity + 20 dB : weak signal level rssi >= receiver sensitivity + 20 dB : Good signal level Note weak signal level is likely to work in environments without interference but the probability for connection problems in networks having some background interference then increases
int8_t	txpower	Tx power in dB This equals maximum transmission power that sender can transmit (which is used when transmitting beacons)
uint8_t	type	Type of beacon app_lib_state_nbor_type_e.

◆ app_lib_state_hops_adjust_t

struct app_lib_state_hops_adjust_t

Structure for adjusting hops.

Definition at line 236 of file state.h.

Data Fields
app_addr_t	address	Target address of the packet (multicast group, with APP_ADDR_MULTICAST bitmask set)
uint8_t	hops_left	Amount of hops left in this data packet.

◆ app_lib_state_route_info_t

struct app_lib_state_route_info_t

Structure for route information.

Definition at line 247 of file state.h.

Data Fields
app_lib_settings_net_channel_t	channel	Next hop's (logical) data (cluster) channel or 0 if no valid route
uint8_t	cost	Route cost or APP_LIB_STATE_INVALID_ROUTE_COST if no valid route
app_addr_t	next_hop	Next hop's unicast address or 0 if no valid route
app_addr_t	sink	Sink's unicast address or 0 if no valid route
app_lib_state_route_state_e	state	Route state: invalid, pending or valid

◆ app_lib_state_install_quality_t

struct app_lib_state_install_quality_t

Installation quality information. Contains information about the nodes installation location i.e. its quality indicated by a numeric value, as well as error codes if something is wrong with the location.

For more detailed information about the value(s) presented here, see application note about installation quality API, document reference: AN-XXX

Definition at line 287 of file state.h.

Data Fields
uint8_t	error_codes	Error codes, install_quality_error_code_e
uint8_t	quality	Quality reported as u8. Limits are as follows: Quality >= 127 : Good installation 127 > Quality > 63 : Average installation Quality <= 63 : Bad installation

◆ app_lib_state_t

struct app_lib_state_t

List of library functions of v3 version (0x202)

Definition at line 722 of file state.h.

Data Fields
app_lib_state_get_access_cycle_f	getAccessCycle
app_lib_state_get_diag_interval_f	getDiagInterval
app_lib_state_get_energy_f	getEnergy
app_lib_state_get_install_quality_f	getInstallQual
app_lib_state_get_nbors_f	getNbors
app_lib_state_get_route_count_f	getRouteCount
app_lib_state_get_route_f	getRouteInfo
app_lib_state_get_sink_cost_f	getSinkCost
app_lib_state_get_stack_state_f	getStackState
app_lib_state_set_energy_f	setEnergy
app_lib_state_set_adjust_hops_cb_f	setHopsLeftCb
app_lib_state_set_on_beacon_cb_f	setOnBeaconCb
app_lib_state_set_on_scan_nbors_with_type_cb_f	setOnScanNborsCb
app_lib_state_set_route_cb_f	setRouteCb
app_lib_state_set_scan_dur_f	setScanDuration
app_lib_state_set_sink_cost_f	setSinkCost
app_lib_state_start_scan_nbors_f	startScanNbors
app_lib_state_start_stack_f	startStack
app_lib_state_scan_stop_f	stopScanNbors
app_lib_state_stop_stack_f	stopStack

Enumeration Type Documentation

◆ app_lib_state_beacon_type_e

enum app_lib_state_beacon_type_e

Type for beacons, passed in app_lib_state_beacon_rx_t.

Enumerator
APP_LIB_STATE_BEACON_TYPE_NB	Network beacon.
APP_LIB_STATE_BEACON_TYPE_CB	Cluster beacon.

Definition at line 193 of file state.h.

 {
     APP_LIB_STATE_BEACON_TYPE_NB = 0,   
     APP_LIB_STATE_BEACON_TYPE_CB = 1,   
 } app_lib_state_beacon_type_e;

◆ app_lib_state_diradv_support_e

enum app_lib_state_diradv_support_e

Support type for directed advertiser, i.e. does neighbor support sending directed advertiser packets to it.

Enumerator
APP_LIB_STATE_DIRADV_SUPPORTED	Directed advertiser is supported by neighbor
APP_LIB_STATE_DIRADV_NOT_SUPPORTED	Sending not supported
APP_LIB_STATE_DIRADV_UNKNOWN	Unknown state. Maybe or maybe not supported

Definition at line 80 of file state.h.

 {
     APP_LIB_STATE_DIRADV_SUPPORTED      = 0,
     APP_LIB_STATE_DIRADV_NOT_SUPPORTED  = 1,
     APP_LIB_STATE_DIRADV_UNKNOWN        = 2,
 } app_lib_state_diradv_support_e;

◆ app_lib_state_nbor_type_e

enum app_lib_state_nbor_type_e

Neighbor type.

Note: Most reliable information is always from next hop and members Other entries might be very old

Enumerator
APP_LIB_STATE_NEIGHBOR_IS_NEXT_HOP	Neighbor is specifically a next hop cluster, i.e. used as a route to sink
APP_LIB_STATE_NEIGHBOR_IS_MEMBER	Neighbor is specifically a member of this node
APP_LIB_STATE_NEIGHBOR_IS_CLUSTER	Neighbor is heard from network scan

Definition at line 65 of file state.h.

 {
     APP_LIB_STATE_NEIGHBOR_IS_NEXT_HOP  = 0,
     APP_LIB_STATE_NEIGHBOR_IS_MEMBER    = 1,
     APP_LIB_STATE_NEIGHBOR_IS_CLUSTER   = 2,
 } app_lib_state_nbor_type_e;

◆ app_lib_state_route_state_e

enum app_lib_state_route_state_e

Route state.

Enumerator
APP_LIB_STATE_ROUTE_STATE_INVALID	No next hop / route.
APP_LIB_STATE_ROUTE_STATE_PENDING	Acquiring next hop / route.
APP_LIB_STATE_ROUTE_STATE_VALID	Valid next hop / route.

Definition at line 183 of file state.h.

 {
     APP_LIB_STATE_ROUTE_STATE_INVALID = 0,      
     APP_LIB_STATE_ROUTE_STATE_PENDING = 1,      
     APP_LIB_STATE_ROUTE_STATE_VALID = 2         
 } app_lib_state_route_state_e;

◆ app_lib_state_scan_nbors_type_e

enum app_lib_state_scan_nbors_type_e

Scan neighbor type to specify the scans that trigger the callback.

Enumerator
APP_LIB_STATE_SCAN_NBORS_ALL	All scans will trigger the registered callback
APP_LIB_STATE_SCAN_NBORS_ONLY_REQUESTED	Only explicitly requested scans from app will trigger the registered callback

Definition at line 93 of file state.h.

 {
     APP_LIB_STATE_SCAN_NBORS_ALL = 0,
     APP_LIB_STATE_SCAN_NBORS_ONLY_REQUESTED = 1,
 } app_lib_state_scan_nbors_type_e;

◆ app_lib_state_stack_state_e

enum app_lib_state_stack_state_e

Stack state flags.

Enumerator
APP_LIB_STATE_STARTED	Stack is started.
APP_LIB_STATE_STOPPED	Stack is stopped.
APP_LIB_STATE_NODE_ADDRESS_NOT_SET	Node address is not set.
APP_LIB_STATE_NETWORK_ADDRESS_NOT_SET	Network address is not set.
APP_LIB_STATE_NETWORK_CHANNEL_NOT_SET	Network channel is not set.
APP_LIB_STATE_ROLE_NOT_SET	Node role is not set.
APP_LIB_STATE_APP_CONFIG_DATA_NOT_SET	App config data is not set (sink only)
APP_LIB_STATE_ACCESS_DENIED	Operation is not allowed.

Definition at line 167 of file state.h.

 {
     APP_LIB_STATE_STARTED = 0,                  
     APP_LIB_STATE_STOPPED = 1,                  
     APP_LIB_STATE_NODE_ADDRESS_NOT_SET = 2,     
     APP_LIB_STATE_NETWORK_ADDRESS_NOT_SET = 4,  
     APP_LIB_STATE_NETWORK_CHANNEL_NOT_SET = 8,  
     APP_LIB_STATE_ROLE_NOT_SET = 16,            
     APP_LIB_STATE_APP_CONFIG_DATA_NOT_SET = 32, 
     APP_LIB_STATE_ACCESS_DENIED = 128           
 } app_lib_state_stack_state_e;

◆ install_quality_error_code_e

enum install_quality_error_code_e

Error codes for installation quality, if an error code is active, corrective action regarding the installation location is required.

Enumerator
APP_LIB_STATE_INSTALL_QUALITY_ERROR_NONE	No installation quality errors detected
APP_LIB_STATE_INSTALL_QUALITY_ERROR_NOROUTE	Error: Node has no route to sink
APP_LIB_STATE_INSTALL_QUALITY_ERROR_NONBORS	Error: Node does not have enough good quality neighbors
APP_LIB_STATE_INSTALL_QUALITY_ERROR_BADRSSI	Error: Node has bad RSSI to next hop neighbor

Definition at line 265 of file state.h.

 {
     APP_LIB_STATE_INSTALL_QUALITY_ERROR_NONE    = 0x00,
     APP_LIB_STATE_INSTALL_QUALITY_ERROR_NOROUTE = 0x01,
     APP_LIB_STATE_INSTALL_QUALITY_ERROR_NONBORS = 0x02,
     APP_LIB_STATE_INSTALL_QUALITY_ERROR_BADRSSI = 0x04,
 } install_quality_error_code_e;

Macro Definition Documentation

◆ APP_LIB_STATE_COST_UNKNOWN

#define APP_LIB_STATE_COST_UNKNOWN 0

Macro for cost being unknown. Used in cost component in lib_state->getNbors() service.

Definition at line 44 of file state.h.

◆ APP_LIB_STATE_DEFAULT_SCAN

#define APP_LIB_STATE_DEFAULT_SCAN 0

Macro for using with lib_state->setScanDuration() to disable custom scan duration and use stack default scan duration.

Definition at line 58 of file state.h.

◆ APP_LIB_STATE_INVALID_ROUTE_COST

#define APP_LIB_STATE_INVALID_ROUTE_COST UINT8_MAX

Macro for cost indicating "no route". Used in cost component in lib_state->getNbors() service.

Definition at line 37 of file state.h.

◆ APP_LIB_STATE_LINKREL_UNKNOWN

#define APP_LIB_STATE_LINKREL_UNKNOWN 0

Macro for link reliability being unknown. Used in link reliability component in lib_state->getNbors() service.

Definition at line 51 of file state.h.

◆ APP_LIB_STATE_NAME

#define APP_LIB_STATE_NAME 0x02f9c165

Library symbolic name.

"STATE"

Definition at line 27 of file state.h.

◆ APP_LIB_STATE_VERSION

#define APP_LIB_STATE_VERSION 0x20A

Maximum supported library version.

Definition at line 30 of file state.h.

Detailed Description

Typedefs

Data Structures

Enumerations

Macros

Typedef Documentation

◆ app_lib_state_adjust_hops_cb_f

◆ app_lib_state_get_access_cycle_f

◆ app_lib_state_get_diag_interval_f

◆ app_lib_state_get_energy_f

◆ app_lib_state_get_install_quality_f

◆ app_lib_state_get_nbors_f

◆ app_lib_state_get_route_count_f

◆ app_lib_state_get_route_f

◆ app_lib_state_get_sink_cost_f

◆ app_lib_state_get_stack_state_f

◆ app_lib_state_on_beacon_cb_f

◆ app_lib_state_on_scan_nbors_cb_f

◆ app_lib_state_route_changed_cb_f

◆ app_lib_state_scan_stop_f

◆ app_lib_state_set_adjust_hops_cb_f

◆ app_lib_state_set_energy_f

◆ app_lib_state_set_on_beacon_cb_f

◆ app_lib_state_set_on_scan_nbors_with_type_cb_f

◆ app_lib_state_set_route_cb_f

◆ app_lib_state_set_scan_dur_f

◆ app_lib_state_set_sink_cost_f

◆ app_lib_state_start_scan_nbors_f

◆ app_lib_state_start_stack_f

◆ app_lib_state_stop_stack_f

Data Structure Documentation

◆ app_lib_state_nbor_info_t

◆ app_lib_state_nbor_list_t

◆ app_lib_state_beacon_rx_t

◆ app_lib_state_hops_adjust_t

◆ app_lib_state_route_info_t

◆ app_lib_state_install_quality_t

◆ app_lib_state_t

Enumeration Type Documentation

◆ app_lib_state_beacon_type_e

◆ app_lib_state_diradv_support_e

◆ app_lib_state_nbor_type_e

◆ app_lib_state_route_state_e

◆ app_lib_state_scan_nbors_type_e

◆ app_lib_state_stack_state_e

◆ install_quality_error_code_e

Macro Definition Documentation

◆ APP_LIB_STATE_COST_UNKNOWN

◆ APP_LIB_STATE_DEFAULT_SCAN

◆ APP_LIB_STATE_INVALID_ROUTE_COST

◆ APP_LIB_STATE_LINKREL_UNKNOWN

◆ APP_LIB_STATE_NAME

◆ APP_LIB_STATE_VERSION