Wirepas SDK
wms_settings.h File Reference

Detailed Description

The Settings library provides access to node settings, which are stored in nonvolatile memory. When a node starts up it automatically uses these stored settings.

Settings such as node role, unique node address, network address and channel, encryption and authentication keys as well performance-related settings such as access cycle limits can be stored and recalled. Also see the State library state.h for starting and stopping the stack.

Library services are accessed via lib_settings handle.

Definition in file wms_settings.h.

Go to the source code of this file.

Typedefs

typedef uint32_t app_lib_settings_net_addr_t
 Network address type definition. More...
 
typedef uint8_t app_lib_settings_net_channel_t
 Network channel type definition. More...
 
typedef uint8_t app_lib_settings_role_t
 Node role type. More...
 
typedef bool(* app_lib_settings_is_group_cb_f) (app_addr_t group_addr)
 Callback used for determining on which multicast groups the device belongs. More...
 
typedef app_res_e(* app_lib_settings_reset_all_f) (void)
 Reset all settings to default values. More...
 
typedef app_res_e(* app_lib_settings_get_feature_lock_bits_f) (uint32_t *bits_p)
 Get feature lock bits. More...
 
typedef app_res_e(* app_lib_settings_set_feature_lock_bits_f) (uint32_t bits)
 Set feature lock bits. More...
 
typedef app_res_e(* app_lib_settings_get_feature_lock_key_f) (uint8_t *key_p)
 Check if feature lock key is set. More...
 
typedef app_res_e(* app_lib_settings_set_feature_lock_key_f) (const uint8_t *key_p)
 Set feature lock key. More...
 
typedef app_res_e(* app_lib_settings_get_node_address_f) (app_addr_t *addr_p)
 Get node address. More...
 
typedef app_res_e(* app_lib_settings_set_node_address_f) (app_addr_t addr)
 Set node address. More...
 
typedef app_res_e(* app_lib_settings_get_network_address_f) (app_lib_settings_net_addr_t *addr_p)
 Get network address. More...
 
typedef app_res_e(* app_lib_settings_set_network_address_f) (app_lib_settings_net_addr_t addr)
 Set network address. More...
 
typedef app_res_e(* app_lib_settings_get_network_channel_f) (app_lib_settings_net_channel_t *channel_p)
 Get network channel. More...
 
typedef app_res_e(* app_lib_settings_set_network_channel_f) (app_lib_settings_net_channel_t channel)
 Set network channel. More...
 
typedef app_res_e(* app_lib_settings_get_node_role_f) (app_lib_settings_role_t *role_p)
 
typedef app_res_e(* app_lib_settings_set_node_role_f) (app_lib_settings_role_t role)
 Set node role. More...
 
typedef app_res_e(* app_lib_settings_get_authentication_key_f) (uint8_t *key_p)
 Check if authentication key is set. More...
 
typedef app_res_e(* app_lib_settings_set_authentication_key_f) (const uint8_t *key_p)
 Set authentication key. More...
 
typedef app_res_e(* app_lib_settings_get_encryption_key_f) (uint8_t *key_p)
 Check if encryption key is set. More...
 
typedef app_res_e(* app_lib_settings_set_encryption_key_f) (const uint8_t *key_p)
 Set encryption key. More...
 
typedef app_res_e(* app_lib_settings_get_ac_range_f) (uint16_t *ac_min_value_p, uint16_t *ac_max_value_p)
 Get the access cycle range. More...
 
typedef app_res_e(* app_lib_settings_set_ac_range_f) (uint16_t ac_min_value, uint16_t ac_max_value)
 Set range for access cycle. More...
 
typedef app_res_e(* app_lib_settings_get_offline_scan_f) (uint16_t *max_scan_p)
 Get the maximum offline scan interval in seconds. More...
 
typedef app_res_e(* app_lib_settings_set_offline_scan_f) (uint16_t max_scan)
 Set the maximum offline scan interval in seconds. More...
 
typedef app_res_e(* app_lib_settings_get_network_channel_limits_f) (uint16_t *min_value_p, uint16_t *max_value_p)
 Get network channel range. More...
 
typedef app_res_e(* app_lib_settings_get_ac_range_limits_f) (uint16_t *min_value_p, uint16_t *max_value_p)
 Get access cycle range. More...
 
typedef app_res_e(* app_lib_settings_set_group_query_cb_f) (app_lib_settings_is_group_cb_f cb)
 Set the callback function for multicat groups. More...
 
typedef app_res_e(* app_lib_settings_get_reserved_channels_f) (uint8_t *channels_p, size_t num_bytes)
 Get reserved channels. More...
 
typedef app_res_e(* app_lib_settings_set_reserved_channels_f) (const uint8_t *channels_p, size_t num_bytes)
 Set reserved channels. More...
 
typedef bool(* app_lib_settings_is_valid_network_address_f) (app_lib_settings_net_addr_t addr)
 Check that the network address is valid. More...
 
typedef bool(* app_lib_settings_is_valid_network_channel_f) (uint8_t channel)
 Check that the network channel is valid. More...
 
typedef bool(* app_lib_settings_is_valid_node_address_f) (app_addr_t addr)
 Check that the node address is valid. More...
 
typedef bool(* app_lib_settings_is_valid_node_role_f) (app_lib_settings_role_t role)
 Check that the node role is valid. More...
 

Data Structures

struct  app_lib_settings_t
 

Enumerations

enum  app_lib_settings_role_e {
  APP_LIB_SETTINGS_ROLE_SINK_LE = 0x00, APP_LIB_SETTINGS_ROLE_SINK_LL = 0x10, APP_LIB_SETTINGS_ROLE_HEADNODE_LE = 0x01, APP_LIB_SETTINGS_ROLE_HEADNODE_LL = 0x11,
  APP_LIB_SETTINGS_ROLE_SUBNODE_LE = 0x02, APP_LIB_SETTINGS_ROLE_SUBNODE_LL = 0x12, APP_LIB_SETTINGS_ROLE_AUTOROLE_LE = 0x42, APP_LIB_SETTINGS_ROLE_AUTOROLE_LL = 0x52,
  APP_LIB_SETTINGS_ROLE_ADVERTISER = 0x04
}
 

Macros

#define APP_LIB_SETTINGS_NAME   0x74ced676
 Library symbolic name. More...
 
#define APP_LIB_SETTINGS_VERSION   0x208
 Maximum supported library version. More...
 
#define APP_LIB_SETTINGS_AES_KEY_NUM_BYTES   16
 AES key size in bytes. More...
 

Typedef Documentation

◆ app_lib_settings_get_ac_range_f

typedef app_res_e(* app_lib_settings_get_ac_range_f) (uint16_t *ac_min_value_p, uint16_t *ac_max_value_p)

Get the access cycle range.

The values are in milliseconds. This setting is only meaningful for nodes that route data for others, i.e. sinks and headnodes.

Parameters
ac_min_value_pPointer to store the minimum current access cycle value
ac_max_value_pPointer to store the maximum current access cycle value
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if access cycle range not set, APP_RES_INVALID_NULL_POINTER if ac_min_value_p or ac_max_value_p is NULL

Example:

uint16_t min,max;
lib_settings->getAcRange(&min, &max);

Definition at line 428 of file wms_settings.h.

◆ app_lib_settings_get_ac_range_limits_f

typedef app_res_e(* app_lib_settings_get_ac_range_limits_f) (uint16_t *min_value_p, uint16_t *max_value_p)

Get access cycle range.

Return the minimum and maximum access cycle value, in milliseconds, that can be used when setting the access cycle range with the lib_settings->setAcRange() function.

Parameters
min_value_pPointer to store the minimum access cycle value allowed
max_value_pPointer to store the maximum access cycle value allowed
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_NULL_POINTER if min_value_p or max_value_p is NULL

Definition at line 558 of file wms_settings.h.

◆ app_lib_settings_get_authentication_key_f

typedef app_res_e(* app_lib_settings_get_authentication_key_f) (uint8_t *key_p)

Check if authentication key is set.

It is not possible to actually read the key from the stack. The key_p parameter is ignored.

Parameters
key_pIf NULL, key is not return but return code will inform if keys are set or not. Otherwise, pointer to a ram area of 16 bytes where the key can be copied. It is updated only if return value is APP_RES_OK.
Returns
Result code, APP_RES_OK if a key set, APP_RES_INVALID_CONFIGURATION if the key is all 0xff, i.e. not set

Definition at line 344 of file wms_settings.h.

◆ app_lib_settings_get_encryption_key_f

typedef app_res_e(* app_lib_settings_get_encryption_key_f) (uint8_t *key_p)

Check if encryption key is set.

It is not possible to actually read the key from the stack. The key_p parameter is ignored.

Parameters
key_pIf NULL, key is not return but return code will inform if keys are set or not. Otherwise, pointer to a ram area of 16 bytes where the key can be copied. It is updated only if return value is APP_RES_OK.
Returns
Result code, APP_RES_OK if a key set, APP_RES_INVALID_CONFIGURATION if the key is all 0xff, i.e. not set

Definition at line 382 of file wms_settings.h.

◆ app_lib_settings_get_feature_lock_bits_f

typedef app_res_e(* app_lib_settings_get_feature_lock_bits_f) (uint32_t *bits_p)

Get feature lock bits.

Feature lock bits determine which features are permitted at runtime. A cleared bit marks that a feature is locked. Some features are governed by the stack, some checks are implemented on the application side, where applicable. Feature lock bits are active only when feature lock key is set. Feature lock bits are documented in WP-RM-100 Wirepas Mesh Dual-MCU API Reference Manual.

Parameters
bits_pPointer to store the result
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_NULL_POINTER if bits_p is NULL

Definition at line 148 of file wms_settings.h.

◆ app_lib_settings_get_feature_lock_key_f

typedef app_res_e(* app_lib_settings_get_feature_lock_key_f) (uint8_t *key_p)

Check if feature lock key is set.

If set the feature lock is locked. It is not possible to actually read the key from the stack. The key_p parameter is ignored.

Parameters
key_pA dummy parameter, reserved for future, set to NULL
Returns
Result code, APP_RES_OK if a key set, APP_RES_INVALID_CONFIGURATION if the key is all 0xff, i.e. not set
Note
Reading the actual key value is not possible, for security reasons

Definition at line 178 of file wms_settings.h.

◆ app_lib_settings_get_network_address_f

typedef app_res_e(* app_lib_settings_get_network_address_f) (app_lib_settings_net_addr_t *addr_p)

Get network address.

Parameters
addr_pPointer to store the result
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if network address not set, APP_RES_INVALID_NULL_POINTER if addr_p is NULL

Definition at line 240 of file wms_settings.h.

◆ app_lib_settings_get_network_channel_f

typedef app_res_e(* app_lib_settings_get_network_channel_f) (app_lib_settings_net_channel_t *channel_p)

Get network channel.

Parameters
channel_pPointer to store the result
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if network channel not set, APP_RES_INVALID_NULL_POINTER if channel_p is NULL

Definition at line 266 of file wms_settings.h.

◆ app_lib_settings_get_network_channel_limits_f

typedef app_res_e(* app_lib_settings_get_network_channel_limits_f) (uint16_t *min_value_p, uint16_t *max_value_p)

Get network channel range.

Return the minimum and maximum network channel value that can be used when setting the network channel with the lib_settings->setNetworkChannel() function

Parameters
min_value_pPointer to store the minimum network channel value allowed
max_value_pPointer to store the maximum network channel value allowed
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_NULL_POINTER if min_value_p or max_value_p is NULL

Definition at line 540 of file wms_settings.h.

◆ app_lib_settings_get_node_address_f

typedef app_res_e(* app_lib_settings_get_node_address_f) (app_addr_t *addr_p)

Get node address.

Parameters
addr_pPointer to store the result
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if node address not set, APP_RES_INVALID_NULL_POINTER if addr_p is NULL

Definition at line 212 of file wms_settings.h.

◆ app_lib_settings_get_node_role_f

typedef app_res_e(* app_lib_settings_get_node_role_f) (app_lib_settings_role_t *role_p)

Get node role. Utility functions app_lib_settings_get_base_role() and app_lib_settings_get_flags_role() can be used to split the node value to a base role and role flag bits, respectively.

Parameters
role_pPointer to store the result
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_CONFIGURATION if node role not set, APP_RES_INVALID_NULL_POINTER if role_p is NULL

Definition at line 301 of file wms_settings.h.

◆ app_lib_settings_get_offline_scan_f

typedef app_res_e(* app_lib_settings_get_offline_scan_f) (uint16_t *max_scan_p)

Get the maximum offline scan interval in seconds.

The maximum offline scan interval determines the maximum interval between two scans for neighbors when device has no route to a sink.

Parameters
max_scan_pPointer to store the scanning interval value
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is not running, APP_RES_INVALID_NULL_POINTER if max_scan_p is NULL

Definition at line 495 of file wms_settings.h.

◆ app_lib_settings_get_reserved_channels_f

typedef app_res_e(* app_lib_settings_get_reserved_channels_f) (uint8_t *channels_p, size_t num_bytes)

Get reserved channels.

Get a bit array of reserved channels, or channels that are marked to be avoided by the Wirepas Mesh protocol. Each set bit marks a channel that is to be avoided. The LSB of the first byte is channel 1, the LSB of the next byte is channel 8 and so forth.

Parameters
channels_pPointer to store the reserved channels bit array Each set bit marks the channel as reserved LSB of first byte is channel 1, MSB of first byte is channel 7, LSB of second byte is channel 8, an so on etc
num_bytesNumber of bytes pointed by channels_p
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_NULL_POINTER if channels_p is NULL, APP_RES_INVALID_VALUE if last reserved channel does not fit in num_bytes
Note
channels_p bit array can be longer than the maximum reserved channel. Remaining channels are marked as not reserved

Definition at line 617 of file wms_settings.h.

◆ app_lib_settings_is_group_cb_f

typedef bool(* app_lib_settings_is_group_cb_f) (app_addr_t group_addr)

Callback used for determining on which multicast groups the device belongs.

As an argument, the stack sets the address of the multicast group. If device belongs to that group, callback function returns true. If not, callback returns false.

This callback is called when device receives multicast packet. The return value is then determined whether data shall be received by standard means (i.e. data reception callback, see lib_data->setDataReceivedCb)

Parameters
group_addrGroup address (with APP_ADDR_MULTICAST bitmask set)
Returns
true: is in multicast group, false: is not in multicast group
Note
Keep the function execution time moderately short, i.e. do not execute any time-consuming operations directly in this callback!

Usage: see documentation of lib_settings->registerGroupQuery.

Definition at line 112 of file wms_settings.h.

◆ app_lib_settings_is_valid_network_address_f

typedef bool(* app_lib_settings_is_valid_network_address_f) (app_lib_settings_net_addr_t addr)

Check that the network address is valid.

Parameters
addrThe network address to check.
Returns
True if network address is valid.

Definition at line 669 of file wms_settings.h.

◆ app_lib_settings_is_valid_network_channel_f

typedef bool(* app_lib_settings_is_valid_network_channel_f) (uint8_t channel)

Check that the network channel is valid.

Parameters
channelThe network channel to check.
Returns
True if network channel is valid.

Definition at line 677 of file wms_settings.h.

◆ app_lib_settings_is_valid_node_address_f

typedef bool(* app_lib_settings_is_valid_node_address_f) (app_addr_t addr)

Check that the node address is valid.

Parameters
addrThe node address to check.
Returns
True if node address is valid.

Definition at line 685 of file wms_settings.h.

◆ app_lib_settings_is_valid_node_role_f

typedef bool(* app_lib_settings_is_valid_node_role_f) (app_lib_settings_role_t role)

Check that the node role is valid.

Parameters
roleThe node role to check.
Returns
True if node role is valid.

Definition at line 693 of file wms_settings.h.

◆ app_lib_settings_net_addr_t

typedef uint32_t app_lib_settings_net_addr_t

Network address type definition.

All nodes on the network must have the same network address.

Definition at line 53 of file wms_settings.h.

◆ app_lib_settings_net_channel_t

Network channel type definition.

All nodes on the network must have the same network channel.

Definition at line 60 of file wms_settings.h.

◆ app_lib_settings_reset_all_f

typedef app_res_e(* app_lib_settings_reset_all_f) (void)

Reset all settings to default values.

  • Feature lock bits: not set
  • Node address: not set
  • Network address: not set
  • Network channel: not set
  • Node role: autorole le
  • Authentication key: not set
  • Encryption key: not set
  • Access cycle range: Minimum value according to profile. Max value 8000 ms.
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is running

Definition at line 130 of file wms_settings.h.

◆ app_lib_settings_role_t

typedef uint8_t app_lib_settings_role_t

Node role type.

List of possible roles are defined in app_lib_settings_role_e

Definition at line 88 of file wms_settings.h.

◆ app_lib_settings_set_ac_range_f

typedef app_res_e(* app_lib_settings_set_ac_range_f) (uint16_t ac_min_value, uint16_t ac_max_value)

Set range for access cycle.

Set the access cycle range that this node uses to serve its neighbors. This setting is only meaningful for nodes that route data for others, i.e. sinks and headnodes.

Normally the stack chooses a suitable access cycle automatically, between 2, 4 or 8 seconds, depending on the amount of network traffic. Some applications may need to further limit the access cycle durations in use.

The values are in milliseconds. Function lib_settings->getAcRangeLimits() can also be used to query the limits. Default range is min. 2000 ms, max. 8000 ms.

Valid values are:

ValueDescription
20002 seconds
40004 seconds
80008 seconds

If value is not set, or maximum > minimum, the stack chooses an appropriate access cycle based on the amount of network traffic. If maximum = minimum, the user can force the access cycle to a specific duration. Range is not set by default. Only a factory reset can restore range back to the unset state.

Example:

lib_settings->setAcRange(2000, 2000); // Fix access cycle to 2s
Parameters
ac_min_valueMinimum access cycle value to set
ac_max_valueMaximum access cycle value to set
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if ac_min_value or ac_max_value is invalid
Note
This setting is not possible when device role has flag APP_LIB_SETTINGS_ROLE_FLAG_LL mode set. Instead, those devices always have automatic access cycle selection enabled.

Definition at line 479 of file wms_settings.h.

◆ app_lib_settings_set_authentication_key_f

typedef app_res_e(* app_lib_settings_set_authentication_key_f) (const uint8_t *key_p)

Set authentication key.

key_p must point to APP_LIB_SETTINGS_AES_KEY_NUM_BYTES bytes. By default, no authentication key is set.

A key of all 0xff (hex) bytes is considered an unset key. Setting such a key disables encryption and authentication.

Parameters
key_pPointer to AES-128 key, APP_LIB_SETTINGS_AES_KEY_NUM_BYTES bytes
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is running, APP_RES_INVALID_NULL_POINTER if key_p is NULL
Note
Note that both the encryption and authentication keys must be set for the encryption or authentication to be enabled. It is NOT enough to set just one key.

Definition at line 366 of file wms_settings.h.

◆ app_lib_settings_set_encryption_key_f

typedef app_res_e(* app_lib_settings_set_encryption_key_f) (const uint8_t *key_p)

Set encryption key.

key_p must point to APP_LIB_SETTINGS_AES_KEY_NUM_BYTES bytes. By default, no encryption key is set.

A key of all 0xff (hex) bytes is considered an unset key. Setting such a key disables encryption and authentication.

Parameters
key_pPointer to AES-128 key, APP_LIB_SETTINGS_AES_KEY_NUM_BYTES bytes
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is running, APP_RES_INVALID_NULL_POINTER if key_p is NULL
Note
Note that both the encryption and authentication keys must be set for the encryption or authentication to be enabled. It is NOT enough to set just one key.

Definition at line 404 of file wms_settings.h.

◆ app_lib_settings_set_feature_lock_bits_f

typedef app_res_e(* app_lib_settings_set_feature_lock_bits_f) (uint32_t bits)

Set feature lock bits.

See lib_settings->getFeatureLockBits() for a description of feature lock bits. A cleared bit marks a feature locked. Reserved bits must remain set.

Parameters
bitsFeature lock bits
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if an unsupported lock bit is set to 0

Definition at line 163 of file wms_settings.h.

◆ app_lib_settings_set_feature_lock_key_f

typedef app_res_e(* app_lib_settings_set_feature_lock_key_f) (const uint8_t *key_p)

Set feature lock key.

Lock or unlock the feature lock. key_p must point to APP_LIB_SETTINGS_AES_KEY_NUM_BYTES bytes. The feature lock key is not an AES-128 key, but it is guaranteed to be the same size as an AES-128 key.

Feature lock key can only be set when the feature lock is unlocked. Unlocking is done by setting the key using the same key as when locking it. A key of all 0xff (hex) bytes is considered an unset key. Setting such a key does not lock the feature lock.

Parameters
key_pPointer to key, APP_LIB_SETTINGS_AES_KEY_NUM_BYTES bytes
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if a key is set and trying to unlock with a wrong key, APP_RES_INVALID_NULL_POINTER if key_p is NULL

Definition at line 200 of file wms_settings.h.

◆ app_lib_settings_set_group_query_cb_f

typedef app_res_e(* app_lib_settings_set_group_query_cb_f) (app_lib_settings_is_group_cb_f cb)

Set the callback function for multicat groups.

The callback is called when stack needs to determine on which multicast groups the device belongs to. If callback is not defined, device does not belong to any multicast groups.

Parameters
cbThe function to be executed, or NULL to unset
Returns
Result code, always APP_RES_OK

Example on use:

// 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);
}
void App_init(const app_global_functions_t * functions)
{
lib_settings->registerGroupQuery(group_query_cb);
// ...
lib_state->startStack();
}

Definition at line 591 of file wms_settings.h.

◆ app_lib_settings_set_network_address_f

typedef app_res_e(* app_lib_settings_set_network_address_f) (app_lib_settings_net_addr_t addr)

Set network address.

There is no default network address.

  • Parameters
    addrNetwork address to set
    Returns
    Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if addr is invalid, APP_RES_INVALID_STACK_STATE if stack is running
    Note
    Function must be called with a valid network address before the stack can be started

Definition at line 255 of file wms_settings.h.

◆ app_lib_settings_set_network_channel_f

typedef app_res_e(* app_lib_settings_set_network_channel_f) (app_lib_settings_net_channel_t channel)

Set network channel.

Different radio architectures have different number of channels available. Function lib_settings->getNetworkChannelLimits() can be used to determine the minimum and maximum channel number available. There is no default network channel.

Parameters
channelNetwork channel to set
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if channel is invalid, APP_RES_INVALID_STACK_STATE if stack is running
Note
Function must be called with a valid network channel before the stack can be started.

Definition at line 286 of file wms_settings.h.

◆ app_lib_settings_set_node_address_f

typedef app_res_e(* app_lib_settings_set_node_address_f) (app_addr_t addr)

Set node address.

There is no default node address.

Parameters
addrOwn node address to set
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if addr is invalid, APP_RES_INVALID_STACK_STATE if stack is running
Note
Function must be called with a valid node address before the stack can be started.

Definition at line 228 of file wms_settings.h.

◆ app_lib_settings_set_node_role_f

typedef app_res_e(* app_lib_settings_set_node_role_f) (app_lib_settings_role_t role)

Set node role.

Default node role is headnode with the autorole flag set.

Code example:

void App_init(const app_global_functions_t * functions)
{
// Configure node as Headnode, low-latency
// This call force the role, and prevent RemoteAPI to change it
lib_settings->setNodeRole(APP_LIB_SETTINGS_ROLE_HEADNODE_LL);
...
}
Parameters
roleNew role
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if role is invalid, APP_RES_INVALID_STACK_STATE if stack is running

Definition at line 328 of file wms_settings.h.

◆ app_lib_settings_set_offline_scan_f

typedef app_res_e(* app_lib_settings_set_offline_scan_f) (uint16_t max_scan)

Set the maximum offline scan interval in seconds.

The maximum offline scan interval determines how often a node scans for neighbors when it has no route to a sink. Value is automatically limited to a valid range. The default value, before calling lib_settings->setOfflineScan() is 600 seconds (10 minutes) for Low Energy Mode and 30 seconds for Low Latency Mode.

Valid offline scan values:

ValueDescription
20Minimum: 20 seconds
600Maximum: 3600 seconds (1 hour)

To manually start a neighbor scan, function startScanNbors() in the State library (state.h) can be used.

Parameters
max_scanMinimum maximum scanning interval value
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if max_scan is invalid

Definition at line 523 of file wms_settings.h.

◆ app_lib_settings_set_reserved_channels_f

typedef app_res_e(* app_lib_settings_set_reserved_channels_f) (const uint8_t *channels_p, size_t num_bytes)

Set reserved channels.

Mark channels as reserved, or to be avoided by the Wirepas Mesh protocol. Each set bit marks a channel that is to be avoided. The LSB of the first byte is channel 1, the LSB of the next byte is channel 8 and so forth. The channels_p bit array may be shorter than the number of channels. In that case, the remaining channels are marked as not reserved. The bit array may be longer too, provided that the highest bit set in it corresponds to a valid channel number (see section 3.6.4.27), i.e. extra zeros are ignored.

A node may still transmit on a reserved channel if it has a neighbor that has not been configured to avoid the channel. For best results, all nodes in a network should be configured to have the same reserved channels. Reserving the network channel will result in undefined behavior.

The reserved channels array is not stored in permanent memory. To reserve channels, function lib_settings->setReservedChannels() has to be called in App_init() before the stack is started.

Parameters
channelsPointer to bit array to load the reserved channels Each set bit marks the channel as reserved LSB of first byte is channel 1, MSB of first byte is channel 7, LSB of second byte is channel 8, an so on
num_bytesNumber of bytes pointed by channels_p
Returns
Result code, APP_RES_OK if successful, APP_RES_INVALID_NULL_POINTER if channels_p is NULL, APP_RES_INVALID_STACK_STATE if stack is running, APP_RES_INVALID_VALUE if a bit in channels_p is set for a channel larger than the maximum channel number
Note
channels_p bit array can be shorter than the maximum number of channels. Remaining channels are marked as not reserved
In the current implementation, reserved channels are not stored in persistent memory. Application must call setReservedChannels() in App_init()

Definition at line 659 of file wms_settings.h.


Data Structure Documentation

◆ app_lib_settings_t

struct app_lib_settings_t

The function table returned from app_open_library_f

Definition at line 698 of file wms_settings.h.

Data Fields
app_lib_settings_get_ac_range_f getAcRange
app_lib_settings_get_ac_range_limits_f getAcRangeLimits
app_lib_settings_get_authentication_key_f getAuthenticationKey
app_lib_settings_get_encryption_key_f getEncryptionKey
app_lib_settings_get_feature_lock_bits_f getFeatureLockBits
app_lib_settings_get_feature_lock_key_f getFeatureLockKey
app_lib_settings_get_network_address_f getNetworkAddress
app_lib_settings_get_network_channel_f getNetworkChannel
app_lib_settings_get_network_channel_limits_f getNetworkChannelLimits
app_lib_settings_get_node_address_f getNodeAddress
app_lib_settings_get_node_role_f getNodeRole
app_lib_settings_get_offline_scan_f getOfflineScan
app_lib_settings_get_reserved_channels_f getReservedChannels
app_lib_settings_is_valid_network_address_f isValidNetworkAddress
app_lib_settings_is_valid_network_channel_f isValidNetworkChannel
app_lib_settings_is_valid_node_address_f isValidNodeAddress
app_lib_settings_is_valid_node_role_f isValidNodeRole
app_lib_settings_set_group_query_cb_f registerGroupQuery
app_lib_settings_reset_all_f resetAll
app_lib_settings_set_ac_range_f setAcRange
app_lib_settings_set_authentication_key_f setAuthenticationKey
app_lib_settings_set_encryption_key_f setEncryptionKey
app_lib_settings_set_feature_lock_bits_f setFeatureLockBits
app_lib_settings_set_feature_lock_key_f setFeatureLockKey
app_lib_settings_set_network_address_f setNetworkAddress
app_lib_settings_set_network_channel_f setNetworkChannel
app_lib_settings_set_node_address_f setNodeAddress
app_lib_settings_set_node_role_f setNodeRole
app_lib_settings_set_offline_scan_f setOfflineScan
app_lib_settings_set_reserved_channels_f setReservedChannels

Enumeration Type Documentation

◆ app_lib_settings_role_e

Enumerator
APP_LIB_SETTINGS_ROLE_SINK_LE 

Sink in Low Energy mode

APP_LIB_SETTINGS_ROLE_SINK_LL 

Sink in Low Latency mode

APP_LIB_SETTINGS_ROLE_HEADNODE_LE 

Headnode in Low Energy mode

APP_LIB_SETTINGS_ROLE_HEADNODE_LL 

Headnode in Low Latency mode

APP_LIB_SETTINGS_ROLE_SUBNODE_LE 

Subnode in Low Energy mode

APP_LIB_SETTINGS_ROLE_SUBNODE_LL 

Subnode in Low Latency mode

APP_LIB_SETTINGS_ROLE_AUTOROLE_LE 

Autorole in Low Energy mode

APP_LIB_SETTINGS_ROLE_AUTOROLE_LL 

Autorole Low Latency mode

APP_LIB_SETTINGS_ROLE_ADVERTISER 

Advertiser (implicitly Low Energy)

Definition at line 62 of file wms_settings.h.

Macro Definition Documentation

◆ APP_LIB_SETTINGS_AES_KEY_NUM_BYTES

#define APP_LIB_SETTINGS_AES_KEY_NUM_BYTES   16

AES key size in bytes.

This macro can be used as a buffer size for storing or copying a 128-bit AES key, or the 16-byte feature lock key. The feature lock key is not an AES-128 key, but it is guaranteed to be the same size as an AES-128 key.

Examples
provisioning_proxy/app.c.

Definition at line 44 of file wms_settings.h.

◆ APP_LIB_SETTINGS_NAME

#define APP_LIB_SETTINGS_NAME   0x74ced676

Library symbolic name.

"SETTIN"

Definition at line 32 of file wms_settings.h.

◆ APP_LIB_SETTINGS_VERSION

#define APP_LIB_SETTINGS_VERSION   0x208

Maximum supported library version.

Definition at line 35 of file wms_settings.h.

APP_LIB_SETTINGS_ROLE_SUBNODE_LE
@ APP_LIB_SETTINGS_ROLE_SUBNODE_LE
Definition: wms_settings.h:72
APP_LIB_SETTINGS_ROLE_ADVERTISER
@ APP_LIB_SETTINGS_ROLE_ADVERTISER
Definition: wms_settings.h:80
APP_LIB_SETTINGS_ROLE_HEADNODE_LE
@ APP_LIB_SETTINGS_ROLE_HEADNODE_LE
Definition: wms_settings.h:68
app_lib_settings_role_e
app_lib_settings_role_e
Definition: wms_settings.h:62
app_global_functions_t
List of global functions, passed to App_entrypoint()
Definition: wms_app.h:157
APP_LIB_SETTINGS_ROLE_SINK_LL
@ APP_LIB_SETTINGS_ROLE_SINK_LL
Definition: wms_settings.h:66
APP_LIB_SETTINGS_ROLE_AUTOROLE_LE
@ APP_LIB_SETTINGS_ROLE_AUTOROLE_LE
Definition: wms_settings.h:76
app_addr_t
uint32_t app_addr_t
Definition: wms_app.h:228
APP_LIB_SETTINGS_ROLE_SINK_LE
@ APP_LIB_SETTINGS_ROLE_SINK_LE
Definition: wms_settings.h:64
APP_LIB_SETTINGS_ROLE_SUBNODE_LL
@ APP_LIB_SETTINGS_ROLE_SUBNODE_LL
Definition: wms_settings.h:74
APP_LIB_SETTINGS_ROLE_HEADNODE_LL
@ APP_LIB_SETTINGS_ROLE_HEADNODE_LL
Definition: wms_settings.h:70
APP_LIB_SETTINGS_ROLE_AUTOROLE_LL
@ APP_LIB_SETTINGS_ROLE_AUTOROLE_LL
Definition: wms_settings.h:78