Wirepas SDK
|
Application library for viewing and controlling stack runtime state
Library services are accessed via lib_state handle.
Definition in file wms_state.h.
Go to the source code of this file.
Typedefs | |
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 app_res_e(* | app_lib_state_get_access_cycle_f) (uint16_t *ac_value_p) |
Get current access cycle. More... | |
typedef void(* | app_lib_state_on_stack_event_cb_f) (app_lib_stack_event_e event, void *param) |
Function type stack events callback. More... | |
typedef app_res_e(* | app_lib_state_set_stack_event_cb_f) (app_lib_state_on_stack_event_cb_f cb) |
Register callback for stack events. 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_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 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_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... | |
typedef app_lib_settings_net_channel_t(* | app_lib_state_get_cluster_channel_t) (void) |
Query cluster channel (i.e. operating channel) currently in use. 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 |
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_on_scan_start_info_t |
Information on started scan. More... | |
struct | app_lib_state_neighbor_scan_info_t |
Information on neighbor scan. More... | |
struct | app_lib_state_t |
List of library functions. More... | |
Macros | |
#define | APP_LIB_STATE_NAME 0x02f9c165 |
Library symbolic name. More... | |
#define | APP_LIB_STATE_VERSION 0x20E |
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... | |
typedef app_res_e(* app_lib_state_get_access_cycle_f) (uint16_t *ac_value_p) |
Get current access cycle.
ac_value_p | Pointer to store the current access cycle value in milliseconds Updated if return code is APP_RES_OK |
Definition at line 403 of file wms_state.h.
typedef app_lib_settings_net_channel_t(* app_lib_state_get_cluster_channel_t) (void) |
Query cluster channel (i.e. operating channel) currently in use.
Definition at line 613 of file wms_state.h.
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.
qual_out | [out] The installation quality information is copied to this pointer |
Definition at line 606 of file wms_state.h.
typedef app_res_e(* app_lib_state_get_nbors_f) (app_lib_state_nbor_list_t *nbors_list) |
Get list of neighbors.
nbors_list | Pointer to store the information of list of neighbors. |
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:
Definition at line 527 of file wms_state.h.
typedef app_res_e(* app_lib_state_get_route_f) (app_lib_state_route_info_t *info) |
Get route information.
info | [out] Route information is provided here |
Definition at line 584 of file wms_state.h.
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.
cost_p | Pointer to store the current initial cost |
cost_p
is NULLExample:
Definition at line 552 of file wms_state.h.
typedef uint8_t(* app_lib_state_get_stack_state_f) (void) |
Get the stack state.
Service indicates whether the stack is running or not, and whether it can be started.
Example:
Definition at line 393 of file wms_state.h.
typedef void(* app_lib_state_on_beacon_cb_f) (const app_lib_state_beacon_rx_t *beacon) |
Function type for a beacon reception callback.
beacon | Information about received beacon |
Definition at line 330 of file wms_state.h.
typedef void(* app_lib_state_on_stack_event_cb_f) (app_lib_stack_event_e event, void *param) |
Function type stack events callback.
event | Which event generated this call |
param_p | Parameter pointer associated to the event. This pointer must be casted depending on the event. Its type is listed in app_lib_stack_event_e |
Example:
Definition at line 473 of file wms_state.h.
typedef app_res_e(* app_lib_state_scan_stop_f) (void) |
Stops ongoing scan operation before ended.
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 597 of file wms_state.h.
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.
cb | The function to be executed, or NULL to unset |
Definition at line 536 of file wms_state.h.
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
cost | Value of 0 means that connection is good and no additional penalty is sent to sink usage. Value of 254 includes maximum penalty |
Example on use:
Definition at line 573 of file wms_state.h.
typedef app_res_e(* app_lib_state_set_stack_event_cb_f) (app_lib_state_on_stack_event_cb_f cb) |
Register callback for stack events.
cb | Function to be executed when a stack event listed in app_lib_stack_event_e happens |
Definition at line 482 of file wms_state.h.
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).
Example:
Definition at line 501 of file wms_state.h.
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
"App_init()" function to start the radio operation.
Example:
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.
Definition at line 360 of file wms_state.h.
typedef app_res_e(* app_lib_state_stop_stack_f) (void) |
Stop the stack.
Example:
Definition at line 378 of file wms_state.h.
struct app_lib_state_nbor_info_t |
Neighbors info definition.
Definition at line 101 of file wms_state.h.
Data Fields | ||
---|---|---|
uint32_t | address |
Address of the neighbor node |
app_lib_settings_net_channel_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.
|
int8_t | rx_power |
Transmission power used when neighbor sending to this device
|
int8_t | tx_power |
Transmission power used when sending to neighbor.
|
uint8_t | type |
Type of the neighbor. app_lib_state_nbor_type_e |
struct app_lib_state_nbor_list_t |
Neighbors list definition.
Definition at line 150 of file wms_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 |
struct app_lib_state_beacon_rx_t |
Structure to hold the information about received beacons.
Definition at line 198 of file wms_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.
|
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_beacon_type_e. |
struct app_lib_state_hops_adjust_t |
Definition at line 232 of file wms_state.h.
Data Fields | ||
---|---|---|
app_addr_t | address | |
uint8_t | hops_left |
struct app_lib_state_route_info_t |
Structure for route information.
Definition at line 241 of file wms_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 |
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: https://developer.wirepas.com/support/solutions/articles/77000498319-radio-installation-quality-api-application-note
Definition at line 281 of file wms_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 |
struct app_lib_state_on_scan_start_info_t |
Information on started scan.
Definition at line 307 of file wms_state.h.
Data Fields | ||
---|---|---|
uint8_t | scan_type |
struct app_lib_state_neighbor_scan_info_t |
Information on neighbor scan.
Definition at line 316 of file wms_state.h.
Data Fields | ||
---|---|---|
bool | complete | |
app_lib_state_scan_type_e | scan_type |
struct app_lib_state_t |
List of library functions.
Definition at line 618 of file wms_state.h.
Data Fields | ||
---|---|---|
app_lib_state_get_access_cycle_f | getAccessCycle | |
app_lib_state_get_cluster_channel_t | getClusterChannel | |
app_lib_state_get_install_quality_f | getInstallQual | |
app_lib_state_get_nbors_f | getNbors | |
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_on_beacon_cb_f | setOnBeaconCb | |
app_lib_state_set_stack_event_cb_f | setOnStackEventCb | |
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 |
List of event generated by the stack when registering to app_lib_state_set_stack_event_cb_f.
Enumerator | |
---|---|
APP_LIB_STATE_STACK_EVENT_STACK_STOPPED | Stack has stopped. Param = NULL |
APP_LIB_STATE_STACK_EVENT_STACK_STARTED | Stack has started. Param = NULL |
APP_LIB_STATE_STACK_EVENT_SCAN_STARTED | A scan has started. Param = pointer to app_lib_state_on_scan_start_info_t |
APP_LIB_STATE_STACK_EVENT_SCAN_STOPPED | A scan has stoppedd. Param = pointer to app_lib_state_neighbor_scan_info_t |
APP_LIB_STATE_STACK_EVENT_SCRAT_XFER_STARTED | A scratchpad transfer (TX or RX) has started. It will prevent app from being scheduled for up to 30s. Param = NULL |
APP_LIB_STATE_STACK_EVENT_SCRAT_XFER_STOPPED | Scratchpad transfer is finished and app will be scheduled normaly. Param = NULL |
APP_LIB_STATE_STACK_EVENT_ROUTE_CHANGED | Route has changed. Param = pointer to app_lib_state_route_info_t |
Definition at line 410 of file wms_state.h.
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 189 of file wms_state.h.
Support type for directed advertiser, i.e. does neighbor support sending directed advertiser packets to it.
Definition at line 74 of file wms_state.h.
Neighbor type.
Definition at line 59 of file wms_state.h.
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 179 of file wms_state.h.
Scan neighbor type to specify the scans that trigger the callback.
Definition at line 89 of file wms_state.h.
Types of scans.
Enumerator | |
---|---|
SCAN_TYPE_APP_ORIGINATED | |
SCAN_TYPE_STACK_ORIGINATED |
Definition at line 295 of file wms_state.h.
Stack state flags.
Definition at line 163 of file wms_state.h.
Error codes for installation quality, if an error code is active, corrective action regarding the installation location is required.
Definition at line 259 of file wms_state.h.
#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 wms_state.h.
#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 wms_state.h.
#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 wms_state.h.
#define APP_LIB_STATE_NAME 0x02f9c165 |
#define APP_LIB_STATE_VERSION 0x20E |
Maximum supported library version.
Definition at line 30 of file wms_state.h.