NV Parameters¶

Embedded SNAP nodes keep configuration parameters in physical Non-Volatile (NV) memory.

SNAPconnect emulates this type of configuration repository using a standard Python pickle file named nvparams.dat.

The following non-volatile parameters are available through the save_nv_param() and load_nv_param() API functions.

Note

Unlike in embedded SNAP nodes, SNAPconnect NV Parameter changes take effect immediately (no reboot required).

Below is a list and description of the System (Reserved) NV Parameters that apply to SNAPconnect. You can use these same constants when accessing NV parameters on an embedded node from a SNAPconnect script, even if the parameter has no meaning in the SNAPconnect context (such as querying for a node’s radio link quality threshold).

You can also define your own NV Parameters (in the range 128-254) which your script can access and modify, just like the system NV Parameters.

NV0-4 - Reserved¶

Reserved for Synapse use.

NV5 - Multicast Process Groups¶

snap.NV_GROUP_INTEREST_MASK_ID = 5¶

This is a 16-bit field controlling which multicast groups the node will respond to. It is a bit mask, with each bit representing one of 16 possible multicast groups. For example, the 0x0001 bit represents the default group, or “broadcast group.” Removing a node from that group will make the node unable to respond to Portal’s multicasts, such as global pings.

Default Value = 0x0001, which is the broadcast group

One way to think of groups is as “logical sub-channels” or as “subnets.” By assigning different nodes to different groups (or different sets of groups), you can further subdivide your network.

For example, Portal could multicast a “sleep” command to group 0x0002, and only nodes with that bit set in their Multicast Process Groups field would go to sleep. (This means nodes with their group values set to 0x0002, 0x0003, 0x0006, 0x0007, 0x000A, 0x000B, 0x000E, 0x000F, 0x0012, etc., would respond.) Note that a single node can belong to any (or even all - or none) of the 16 groups.

Group membership does not affect how a node responds to a direct RPC call. It only affects multicast requests. However, many of the infrastructure calls made “behind the scenes” in a network, such as route requests, are performed using multicasts on group 1.

NV6 - Multicast Forward Groups¶

snap.NV_GROUP_FORWARDING_MASK_ID = 6¶

This is a separate 16-bit field controlling which multicast groups will be re-transmitted (forwarded) by the node. It is a bit mask, with each bit representing one of 16 possible multicast groups. For example, the 0x0001 bit represents the default group, or “broadcast group.”

Default Value = 0x0001, so all nodes process and forward only broadcast group packets

The NV5 - Multicast Process Groups and NV6 - Multicast Forward Groups parameters are independent of each other. A node could be configured to forward a group, process a group, or both. It can process groups it does not forward, or vice versa. It can forward one set of groups over its radio interface and a different set of groups, with or without overlap, over its serial interface. As with processing groups, a node can be set to forward any combination of the 16 available groups, including none of them.

Warning

If you set your bridge node to not forward multicast commands, Portal will not be able to multicast to the rest of your network.

Note

Every interface opened in a SNAPconnect application has a forward_groups=None parameter available when you open (or listen for) the interface. This parameter restricts which multicast messages will be forwarded through that interface from the SNAPconnect instance, with the default value of None indicating that the interface will only allow multicast packets for groups that the SNAPconnect instance itself would forward. The hazard here is that if you do not explicitly set the forward_groups parameter when you open a connection, SNAPconnect will only be able to make multicast requests of nodes in groups that it would normally forward. In other words, if you want SNAPconnect to be able to initiate multicast requests to a group that it would not normally forward, you must explicitly set that group as a forwarding group when you open the interface.

NV7 - Reserved¶

Reserved for Synapse use.

NV8 – Device Name¶

snap.NV_DEVICE_NAME_ID = 8¶

Allows you to assign a name for the node, although you do not have to give your nodes explicit names. If this parameter is set to None, then the node name will default to “SNAPcom”. You do not have to give your nodes explicit names.

Default Value = None

Note

Spaces are not allowed in your Device Name. "My Node" is not a legal name, while "My_Node" is.

NV9-10 - Reserved¶

Reserved for future Synapse use.

NV11 - Feature Bits¶

snap.NV_FEATURE_BITS_ID = 11¶

These control some miscellaneous hardware settings on embedded SNAP nodes.

Feature Bit Name	Hex	Binary
Second CRC	0x0100	b0000.0001.0000.0000
Packet CRC	0x0400	b0000.0100.0000.0000

Second CRC

The Second CRC bit (0x0100) enables a second CRC packet integrity check on platforms that support it. It does not apply to data mode packets or to infrastructure packets such as message acknowledgements. While this feature bit is still supported, the CRC provided by the Packet CRC bit is recommended.

Default Value = 0

Warning

If you set this bit for the second CRC, you must set it in all nodes in your network, including Portal and any SNAPconnect applications. A node that does not have this parameter set will be able to hear and act on messages from a node that does have it set, but will not be able to communicate back to that node.

Packet CRC

The Packet CRC bit (0x0400) adds an additional CRC validation to the complete packet for every packet sent out over the air. This reduces the available packet payload, but provides an additional level of protection against receiving (and potentially acting upon) a corrupted packet. The CRC that has always been a part of SNAP packets means that there is a one in 65,536 chance that a corrupted packet might get interpreted as valid. This additional CRC should reduce the chance to less than one in four billion.

Default Value = 0

This is different from the CRC controlled by the Second CRC bit in that it includes packet (payload and header) information for RPC, data, routing and acknowledgement packets rather than just covering the RPC payload.

Enabling this CRC reduces your maximum packet payload by two bytes each:

Packet CRC Bit (Bit 10)	Max Unicast Payload	Max Multicast Payload
0	108 bytes	111 bytes
1	106 bytes	109 bytes

Warning

If you set this bit for packet-level CRC, you must set it in all nodes in your network. It is also recommended to configure Portal to match your SNAPconnect application to prevent generating packets that exceed the new maximum payload in your network.

NV12-18 - Reserved¶

Reserved for Synapse use.

NV19 - Radio Unicast Retries¶

snap.NV_SNAP_MAX_RETRIES_ID = 19¶

This lets you control the number of unicast transmit attempts.

Default Value = 8

This parameter refers to the total number of attempts that will be made to get an acknowledgement back on a unicast transmission to another node.

In some applications, there are time constraints on the “useful lifetime” of a packet. In other words, if the packet has not been successfully transferred by a certain point in time, it is no longer useful. In these situations, the extra retries are not helpful - the application will have already “given up” by the time the packet finally gets through.

By lowering this value from its default value of 8, you can tell SNAP to “give up” sooner. A value of 0 is treated the same as a value of 1; a packet gets at least one chance to be delivered no matter what.

If your connection link quality is low and it is important that every packet get through, a higher value here may help. However it may be appropriate to reevaluate your network setup to determine if it would be better to change the number of nodes in your network to either add more nodes to the mesh to forward requests, or reduce the number of nodes broadcasting to cut down on packet collisions.

NV20 - Mesh Maximum Timeout¶

snap.NV_MESH_ROUTE_AGE_MAX_TIMEOUT_ID = 20¶

This indicates the maximum time (in milliseconds) a route can “live.”

Default Value = 60000, which is one minute

Discovered mesh routes timeout after a configurable period of inactivity (see NV21 - Mesh Minimum Timeout), but this timeout sets an upper limit on how long a route will be kept, even if it is being used heavily. By forcing routes to be rediscovered periodically, the nodes will use the shortest routes possible, at the expense of some time spent rediscovering routes when the routes expire.

Note that you can set this timeout to zero (which will disable it) if you know for certain that your nodes are stationary, or have some other reason for needing to avoid periodic route re-discovery.

You can use getInfo(14) to determine the size of a node’s route table (typically 10 entries, but that can vary on some platforms), and getInfo(15) to monitor its use.

NV21 - Mesh Minimum Timeout¶

snap.NV_MESH_ROUTE_AGE_MIN_TIMEOUT_ID = 21¶

This is the minimum time (in milliseconds) a route will be kept, subject to the route table becoming full.

Default Value = 1000, which is one second

Note

In a busy mesh environment, routes may fall out of the route table before this time period has elapsed if the route table becomes full and another route is discovered.

NV22 - Mesh New Timeout¶

snap.NV_MESH_ROUTE_NEW_TIMEOUT_ID = 22¶

This is the grace period (in milliseconds) that a newly discovered route will be kept, even if it is never actually used, subject to the route table becoming full.

Default Value = 5000, which is five seconds

Note

In a busy mesh environment, routes may fall out of the route table before this time period has elapsed if the route table becomes full and another route is discovered.

NV23 - Mesh Used Timeout¶

snap.NV_MESH_ROUTE_USED_TIMEOUT_ID = 23¶

Every time a known route gets used, its timeout gets reset to this parameter. This prevents active routes from timing out as often, but allows inactive routes to go away sooner. NV21 - Mesh Minimum Timeout takes precedence over this timeout.

Default Value = 5000, which is five seconds

NV24 - Mesh Delete Timeout¶

snap.NV_MESH_ROUTE_DELETE_TIMEOUT_ID = 24¶

This timeout (in milliseconds) controls how long “expired” routes are kept around for bookkeeping purposes.

Default Value = 10000, which is ten seconds

NV25 - Mesh RREQ Retries¶

snap.NV_MESH_RREQ_TRIES_ID = 25¶

This parameter controls the total number of retries that will be made when attempting to “discover” a route (a multi-hop path) over the mesh.

Default Value = 3

NV26 - Mesh RREQ Wait Time¶

snap.NV_MESH_RREQ_WAIT_TIME_ID = 26¶

This parameter (in milliseconds) controls how long a node will wait for a response to a Route Request (RREQ) before trying again.

Default Value = 500, which is a half second

Note that subsequent retries use longer and longer timeouts (the timeout is doubled each time). This allows nodes from farther and farther away time to respond to the RREQ packet.

NV27 - Mesh Initial Hop Limit¶

snap.NV_MESH_INITIAL_HOPLIMIT_ID = 27¶

This parameter controls how far the initial “discovery broadcast” message is propagated across the mesh.

Default Value = 2

If your nodes are geographically distributed such that they are always more than 1 hop away from their logical peers, then you can increase this parameter. Consequently, if most of your nodes are within direct radio range of each other, having this parameter at the default setting of 2 will use less radio bandwidth.

SNAPconnect does not support disabling mesh discovery by setting this value to 0. A value of 0 will be treated as if you had set the initial hop limit to the default value of 2.

This parameter should remain less than or equal to NV28 - Mesh Maximum Hop Limit.

NV28 - Mesh Maximum Hop Limit¶

snap.NV_MESH_MAX_HOPLIMIT_ID = 28¶

To cut down on needless broadcast traffic during mesh networking operation (thus saving both power and bandwidth), you can choose to lower this value to the maximum number of physical hops across your network.

Default Value = 5

Tip

If your network is larger than 5 hops, you will need to raise this parameter.

NV29 - Reserved¶

Reserved for Synapse use.

NV30 - Mesh Override¶

snap.NV_MESH_OVERRIDE_ID = 30¶

This is used to limit a node’s level of participation within the mesh network.

Default Value = 0

When set to the default value of 0, the node will fully participate in the mesh networking. This means that not only will it make use of mesh routing, but it will also “volunteer” to route packets for other nodes.

Setting this value to 1 will cause the node to stop volunteering to route packets for other nodes. It will still freely use the entire mesh for its own purposes (subject to other nodes’ willingness to route packets for it).

This feature was added to better support nodes that spend most of their time “sleeping.” If a node is likely to spend most of its time asleep, there may be no point in it becoming part of routes for other nodes while it is (briefly) awake.

This can also be useful if some nodes are externally powered, while others are battery-powered. Assuming sufficient radio coverage (all the externally powered nodes can “hear” all of the other nodes), then the Mesh Override can be set to 1 in the battery powered nodes, extending their battery life at the expense of reducing the “redundancy” in the overall mesh network.

Note

Enabling this feature on your bridge node means Portal will no longer be able to communicate with the rest of your network, regardless of how everything else is configured. No nodes in your network (except for your bridge node) will be able to receive commands or information from Portal or send commands or information to Portal.

NV31-49 - Reserved¶

Reserved for Synapse use.

NV50 - Enable Encryption¶

snap.NV_AES128_ENABLE_ID = 50¶

Control whether encryption is enabled, and what type of encryption is in use for firmware that supports multiple forms. The options for this field are:

ENCRYPTION_TYPE_NONE =	Use no encryption. (This is the default setting.)
ENCRYPTION_TYPE_AES128 =	Use AES-128 encryption if supported.
ENCRYPTION_TYPE_BASIC =	Use Basic encryption.

NV51 - Encryption Key¶

snap.NV_CRYPTO_KEY = 51¶

The encryption key used by either AES-128 encryption or Basic encryption, if enabled. This NV Parameter is a string with default value of “”. If you are enabling encryption, you must specify an encryption key. Your encryption key should be complex and difficult to guess, and it should avoid repeated characters when possible.

Default Value = ````

An encryption key must be exactly 16 bytes (128 bits) long to be valid. This parameter has no effect unless NV50 - Enable Encryption is also set to enable encryption.

Even if NV50 - Enable Encryption is set for AES-128 encryption and NV51 - Encryption Key has a valid encryption key, SNAPconnect will fail with an exception if you do not have the PyCrypto Python library installed.

NV52 - Lockdown¶

snap.NV_LOCKDOWN_FLAGS_ID = 52¶

If this parameter is set to 2, the system is put into a “lockdown” mode, where NV Parameters may not be changed remotely. If it is set to 0 (or never set at all), NV Parameters may be changed (even remotely).

Default Value = 0

Values other than 0 or 2 are reserved for future use and should not be used on a SNAPconnect node.

NV53-54 - Reserved¶

Reserved for Synapse use.

NV55 - Alternate Encryption Key¶

snap.NV_ALTERNATE_KEY_ID = 55¶

This NV parameter is only in SNAPconnect. It is like NV51 - Encryption Key in form and function. It represents a second (“alternate”) encryption key that can be used in special circumstances.

Default Value = ````

For example, you could be running a fully encrypted network using key “encryption_key_1” when a new node is added with encryption key “KEY2(ENCRYPTION)”. By saving the second key in NV55 - Alternate Encryption Key and proper use of the add_rpc_func(), rpc_use_alternate_key(), and rpc_alternate_key_used() functions, you can perform multicast interactions with the new node while still continuing to interact fully (both multicast and unicast) with the old nodes. This gives you a way to reprogram the new node to switch over to using the first key without having to pause communications to the rest of the network.

NV56-127 - Reserved¶

Reserved for Synapse use.

NV128-254 - User Defined¶

These are user-defined NV Parameters and can be used for whatever purpose you choose, just as with embedded SNAP nodes. Unlike embedded SNAP nodes, however, SNAPconnect lets you store any pickleable object in an NV parameter, rather than just a string, Boolean, integer, or None.

NV255 - Reserved¶

Reserved for future Synapse use.

Constants and Enumerations

Authentication Realms