NV Parameters

NV0-1 – Reserved

Reserved for Synapse use.

NV2 - MAC Address

NV_MAC_ADDR_ID = 2

The eight byte address of the SNAP node.

Not Modified on Factory Default

NV3 - Network ID

NV_NETWORK_ID = 3

The 16-bit Network Identifier of the SNAP node. The Network ID and NV4 - Channel are what determine which radios can communicate with each other in a wireless network. Radios must be set to the same channel and network ID in order to communicate over the air. Nodes communicating over a serial link pay no attention to the channel and network ID.

Network IDs can be set to any value from 0x0000 through 0xFFFF. However, 0xFFFF should generally be avoided, because it is a wildcard value which responds to all nodes and to which all nodes respond.

Factory Default Value = 0x1C2C

Note

Changes to this parameter do not take effect until the node has been rebooted. For an immediate change of the Network ID, use SNAPpy’s setNetId() function, which changes the “live” value but does not persist through a reboot.

See also

NV4 - Channel

NV_CHANNEL_ID = 4

The channel on which the SNAP node broadcasts.

The channel can be set to any value from 0 to 15. The Channel Analyzer in Portal can help you determine which channel has the least traffic on it in your environment. Some hardware platforms may restrict the broadcast power on certain channels.

Factory Default Value = 4

Note

Changes to this parameter do not take effect until the node has been rebooted. For an immediate change of the channel, use SNAPpy’s setChannel() function, which changes the “live” value but does not persist through a reboot.

See also

NV5 - Multicast Process Groups

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”.

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 Multi-cast Processed 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.

Factory Default Value = 0x0001, which is the broadcast group

Warning

Removing a node from group 0x0001 (the default/broadcast group) will make the node unable to respond to Portal’s multicasts, such as global pings.

See also

NV6 - Multicast Forward Groups

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.” By default, all nodes process and forward only group 0x0001 ( broadcast) 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.

Factory Default Value = 0x0001, which is the broadcast group

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

This parameter is ignored if NV78 - Multicast Serial Forwarded Groups is changed from its default of None. In that case, NV78 - Multicast Serial Forwarded Groups will control which packets will be forwarded over both the serial and radio interfaces for the node.

See also

NV7 - Reserved

Reserved for Synapse use.

NV8 – Device Name

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 first detected script name will determine the node name. If this parameter is blank and the node has no script loaded, it will have “Node” as its name.

Factory Default Value = None

Note

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

NV9 – Reserved

Reserved for Synapse use.

NV10 - Device Type

NV_DEVICE_TYPE_ID = 10

This is a user-definable string that can be read by scripts. This allows a single script to fill multiple roles, by giving it a way to determine what type of node it is running on. Like NV8 – Device Name, this parameter is one way to categorize your nodes.

Factory Default Value = None

NV11 - Feature Bits

NV_FEATURE_BITS_ID = 11

Settings to control miscellaneous hardware.

Feature Bit Name Hex Binary
UART0 0x0001 b0000.0000.0000.0001
Flow Control UART0 0x0002 b0000.0000.0000.0010
UART1 0x0004 b0000.0000.0000.0100
Flow Control UART1 0x0008 b0000.0000.0000.1000
Power Amplifier 0x0010 b0000.0000.0001.0000
External Power-down Output 0x0020 b0000.0000.0010.0000
Alternate Clock Source 0x0040 b0000.0000.0100.0000
DS_AUDIO 0x0080 b0000.0000.1000.0000
Second CRC 0x0100 b0000.0001.0000.0000
TX Power Levels 0x0200 b0000.0010.0000.0000
Packet CRC 0x0400 b0000.0100.0000.0000
Route Table Size 0x0800 b0000.1000.0000.0000
UART0
The UART0 bit (0x0001) enables Serial Port 0.
Flow Control UART0
The Flow Control UART0 bit (0x0002) enables hardware flow control on Serial Port 0.
UART1
The UART1 bit (0x0004) enables Serial Port 1.
Flow Control UART1
The Flow Control UART1 bit (0x0008) enables hardware flow control on Serial Port 1.
Power Amplifier

Synapse RF100 SNAP engines with PA hardware can be identified by the “RFET” on their labels. Units without PA hardware say “RFE” instead of “RFET.”

For RF100 SNAP engines, the Power Amplifier bit (0x0010) should only be set on “RFET” units. Setting this bit on an “RFE” board will not harm the SNAP engine, but it will actually result in lower transmit power levels (a 20-40% reduction). The bit should be set for RF200 SNAP engines, as well.

In custom hardware, you may need to set this bit according to your specific hardware configuration.

Factory Default Value = Not Modified on Factory Default

External Power-down Output

The External Power-down Output bit (0x0020) should be set on units that need to power down external hardware before going to sleep and power it back up after they awake.

Factory Default Value = Not Modified on Factory Default

Alternate Clock Source

The Alternate Clock Source bit (0x0040) modifies which timer is used on SNAP modules that have multiple timers available, for increased PWM flexibility. Not available on all platforms.

Factory Default Value = Not Modified on Factory Default

See also

DS_AUDIO

The DS_AUDIO bit (0x0080) enables I2S audio communications over the SNAP network on platforms that support it. Not available on all platforms.

Factory Default Value = 0

See also

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.

Factory 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.

See also

TX Power Levels

The TX Power Levels bit (0x0200) enables ETSI, instead of FCC (US), transmit power restrictions. Not available on all platforms.

Factory Default Value = 0

See also

Refer to RF Modules

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 it 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.

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 or your SNAPconnect application with this setting to prevent generating packets that exceed the new maximum payload in your network.
  • Enabling this feature will increase the processor load of the node.

Factory Default Value = 0

Route Table Size

New in version SNAP 2.7.

The Route Table Size bit (0x0800) changes the size of the route table from 10 entries to 100 entries, allowing your node to maintain route information for more nodes so it can more easily communicate over your mesh network.

Factory Default Value = 0

Note

Between the release of SNAP 2.4.34 and SNAP 2.6, route table size was controlled by a platform-specific feature bit on nodes based on the Atmel AT128RFA1.

See also

NV12 - Default UART

NV_DEFAULT_UART_ID = 12

This controls which UART will be pre-configured for Packet Serial Mode.

Normally, the UART-related settings would be specified by the SNAPpy scripts uploaded into the node. This default setting has been implemented to handle nodes that have no scripts loaded yet, or for scripts that do not explicitly set which UART will be used for Packet Serial Mode.

Warning

These defaults are overridden when needed!

Although you can request that one or both UARTs be disabled (via the Feature Bits), and you can request that there be no Packet Serial Mode UART (by setting the Default UART parameter to 255), both of these user requests will be ignored unless there is also a valid SNAPpy script loaded into the unit. If the parameter is set to a value outside the range of UARTs on your module (other than 255), UART1 (or UART0 on modules with only one UART) will be the default.

If there is no SNAPpy script loaded, a fail-safe mechanism kicks in and forces an active Packet Serial port to be initialized on UART1 (or UART0, if so specified in this parameter), regardless of the other configuration settings. This was done to help prevent users from “locking themselves out.”

If there is a SNAPpy script loaded, then the assumption is that the script will take care of any configuration overrides needed, and the Feature Bits and Default UART setting will be honored.

Factory Default Value = 1 on platforms with two UARTs; 0 on platforms with only one UART

Serial Data Forwarding

The next three NV parameters (13-15) affect the “forwarding” of buffered-up serial data (data that has been received over one of the serial ports).

The NV13 - Buffering Timeout and NV15 - Inter-character Timeout are (as you might expect) time-related. They affect time-driven triggers that can cause serial data to be “pushed” to other parts of the system. In contrast, NV14 - Buffering Threshold is completely timing-independent and is driven solely by the quantity of data that has been received. All three of these parameters can be tuned to control when data that a SNAP node receives over a serial connection gets forwarded to other nodes. To control where the data gets forwarded to, refer to the crossConnect() and uniConnect() functions. For more information, refer the to the SNAP Users Guide.

NV13 - Buffering Timeout

NV_UART_DM_TIMEOUT_ID = 13

This lets you tune the overall serial receive data timeout. This value is in milliseconds and defaults to 5. This value controls the typical maximum amount of time between an initial character being received over the serial port and a packet of buffered serial data being enqueued for processing. Regardless of the number of characters buffered or the rate at which they are being buffered, each time this timeout passes, any buffered data will be queued.

Note that other factors can also trigger the queuing of the buffered serial data. In particular, see NV14 - Buffering Threshold and NV15 - Inter-character Timeout.

The larger this value is, the more buffering will take place. In transparent mode, every packet has 12-15 bytes of overhead, so sending more serial characters per packet is more efficient. Also, when using multicast transparent mode, keeping the characters together (in the same packet) improves overall reliability. The trade-off is that the larger this value is, the greater the maximum latency can be through the overall system, especially at lower baud rates.

Setting this value to zero means your system will never trigger packet processing based on this timeout. Packet processing would then only occur based on the limits set by NV14 - Buffering Threshold and NV15 - Inter-character Timeout.

If you enable both the Buffering Timeout and NV15 - Inter-character Timeout and your node transmits data as a result of the Buffering Timeout being reached, it will send any available data again on the next buffering timeout period, even if an Inter-Character Timeout period triggers a send in the meantime. In other words, when the Inter-Character Timeout triggers, it does not reset the clock for the Buffering Timeout.

Factory Default Value = 5

NV14 - Buffering Threshold

NV_UART_DM_THRESHOLD_ID = 14

This value indicates the total packet size threshold used when sending packets of data. The size defaults to 75 bytes. If no timeout limit is reached first, this parameter will cause buffered data to be enqueued when there is sufficient data to cause the packet, including header, to be at least this many bytes long. At higher serial rates, this size can be overshot between SNAP checks of the packet size. There is no guarantee that packets will necessarily be precisely this size.

Each packet of data sent includes a header, which comprises 12 bytes for multicast packets and 15 bytes for unicast packets. So the actual amount of serial data sent in each packet will be reduced by either 12 or 15 bytes, depending on whether the data is sent by multicast or unicast. Additionally, if the feature bit in NV11 - Feature Bits indicates that SNAP should be using its second CRC to prevent data corruption, the data payload will be reduced by an additional two bytes. If you want to send N bytes of data per packet, this parameter should be set to N + 12 for multicasting or N + 15 for unicasting.

The maximum SNAP packet size is 123 bytes, if the packet-level CRC isn’t enabled using the Packet CRC Bit in NV11 - Feature Bits. If the Packet CRC Bit is set, the effective maximum length is 121 bytes. If you set this parameter to a value greater than the maximum (up to 255), the system will simply substitute the maximum. If you set this parameter less than or equal to the packet header size, SNAP will construct packets with a complete header and one byte of data. If you set this parameter to a value higher than 255, the parameter will be reset to the default value of 75.

Like NV13 - Buffering Timeout and NV15 - Inter-character Timeout, larger values can result in larger (more efficient) packets, at the expense of greater latency. Also, at higher baud rates, setting this value too high can result in dropped characters if the packet buffer gets over-filled between SNAP checks.

Factory Default Value = 75

NV15 - Inter-character Timeout

NV_UART_DM_INTERCHAR_ID = 15

This lets you tune the inter-character serial receive data timeout. This value is in milliseconds and defaults to 0 (in other words, disabled).

This timeout is similar to NV13 - Buffering Timeout, but this one refers to the time between individual characters. Essentially, this timeout restarts with every received character, while the Buffering Timeout always runs to completion (as long as the NV14 - Buffering Threshold value is not exceeded). Larger inter-character timeouts can give better multicast transparent mode reliability, at the expense of greater latency.

Note that either NV13 - Buffering Timeout or NV15 - Inter-character Timeout (if enabled) can trigger the transmission of the buffered data before the NV14 - Buffering Threshold is reached. Conversely, if the timeouts are high (or disabled), to the extent that enough data is buffered to reach the Buffering Threshold before the timeouts are reached, that threshold will trigger the transmission of the buffered data before either of the timeouts are reached.

Factory Default Value = 0

NV16 - Carrier Sense

NV_CARRIER_SENSE_ID = 16

This instructs the radio to “listen before you transmit.”

Setting this value to True will cause the node to perform a Clear Channel Assessment. Basically, this means that the node will briefly listen before transmitting anything and will postpone sending the packet if some other node is already talking. This results in fewer collisions (which means more packets make it through), but the “listening” step adds a delay to the time it takes to send each packet. In an especially noisy environment, this setting could substantially delay or prevent your packet’s transmission, even if the radio noise comes from an RF source other than other SNAP nodes.

Carrier Sense applies to all packets transmitted over the air.

If the probability of collisions is low in your network(you don’t have much traffic), and you need the maximum throughput possible, then leave this value at its default setting of False. If the probability of collisions is high in your network (you have a lot of nodes talking a lot of the time), then you can try setting this parameter to True and see if it helps your particular application.

Factory Default Value = False

See also

NV17 - Collision Detect

NV_COLLISION_DETECT_ID = 17

This instructs the radio to “listen after you transmit.”

Setting this value to True will cause the node to perform a Clear Channel Assessment after sending a multicast packet, in an effort to determine whether some other node has “stepped on” its transmission. This will catch some (but not all) collisions. If the node detects that some other node was transmitting at the same time, or if there was a sufficiently high noise floor from another RF source, then the node will resend the multicast packet. This results in more multicast packets making it through, but there is a throughput penalty.

Collision Detect applies only to multicast (and directed multicast) packets. For unicast packets, SNAP relies on the acknowledgements and retries to account for noisy environments.

The same criteria given for NV16 - Carrier Sense apply to this one. You can try setting this parameter to True and see if it helps your application. If not, set it back to False.

Factory Default Value = False

See also

NV18 - Collision Avoidance

NV_COLLISION_AVOIDANCE_ID = 18

This lets you control use of “random jitter” to try and reduce collisions. This setting defaults to True. The SNAP protocol uses a “random jitter” technique to reduce the number of collisions.

Before responding to a multicast packet, SNAP does a small random delay. This random delay, either 0, 4, 8, 12 or 16 milliseconds by default, reduces the number of collisions but increases packet latency. You can tune the delay characteristics using NV91 - CSMA Timeslot Settings.

If you set this parameter to False, then this initial delay will not be used. This reduces latency (some extremely time critical applications need this option) but increases the chances of an over-the-air collision. You should only change this parameter from its default setting of True if there is something else about your application that reduces the chances of collision. For example, some applications operate in a “command/response” fashion, where only one node at a time will be trying to respond anyway.

This parameter does not affect response time for directed multicasts or for unicasts.

Factory Default Value = True

NV19 - Radio Unicast Retries

NV_SNAP_MAX_RETRIES_ID = 19

This lets you control the number of unicast transmit attempts.

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 re-evaluate your network setup to determine if it would be better to either add more nodes to the mesh to forward requests or reduce the number of nodes broadcasting to cut down on packet collisions.

Factory Default Value = 8

NV20 - Mesh Maximum Timeout

NV_MESH_ROUTE_AGE_MAX_TIMEOUT_ID = 20

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

Discovered mesh routes timeout after a configurable period of inactivity (see NV23 - Mesh Used 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.

Factory Default Value = 0xEA60, which is one minute

NV21 - Mesh Minimum Timeout

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.

Factory Default Value = 1000, which is one second

NV22 - Mesh New Timeout

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.

Factory Default Value = 5000, which is five seconds

NV23 - Mesh Used Timeout

NV_MESH_ROUTE_USED_TIMEOUT_ID = 23

This is how many additional milliseconds of “life” a route gets whenever it is used.

Every time a known route gets used, its timeout gets reset to this parameter. This prevents active routes from timing out as often, but it allows inactive routes to go away sooner.

Factory Default Value = 5000, which is five seconds

Note

NV24 - Mesh Delete Timeout

NV_MESH_ROUTE_DELETE_TIMEOUT_ID = 24

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

Factory Default Value = 10000, which is ten seconds

NV25 - Mesh RREQ Retries

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.

Factory Default Value = 3

NV26 - Mesh RREQ Wait Time

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 a second time.

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.

Factory Default Value = 500, which is a half second

NV27 - Mesh Initial Hop Limit

NV_MESH_INITIAL_HOPLIMIT_ID = 27

This parameter controls how far the initial “discovery broadcast” message is propagated across the mesh. 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 1 will use less radio bandwidth.

If you set this parameter to 0, SNAP will make an initial attempt to talk directly to the destination node, on the assumption it is within direct radio range. (It will not attempt to communicate over any serial connection.) If the destination node does not acknowledge the message, and your Radio Unicast Retries and Mesh Routing Maximum Hop Limit are not set to zero, normal mesh discovery attempts will occur (including attempting routes over the serial connection).

This means you can eliminate the overhead and latency required of mesh routing in environments where all your nodes are within direct radio range of each other. However, it also means that if the Mesh Routing Initial Hop Limit is set to zero and there are times when mesh routing is necessary, those messages will suffer an additional latency penalty as the initial broadcast must time out before route requests happen.

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

Also, although Portal is “one hop farther away” than all other SNAP nodes on your network (they are on the other side of a “bridge” node), the SNAP code knows this and will automatically give a “bonus hop” to this parameter’s value when using it to find nodes with addresses in the reserved Portal address range of 00.00.01 - 00.00.0F. So, you can leave this parameter at its default setting of 1 (one hop) even if you use Portal.

Factory Default Value = 1

NV28 - Mesh Maximum Hop Limit

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.

Factory Default Value = 5

NV29 - Mesh Sequence Number

NV_MESH_SEQUENCE_NUMBER_ID = 29

Reserved for future use.

NV30 - Mesh Override

NV_MESH_OVERRIDE_ID = 30

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

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 the mesh’s willingness to be used).

This feature was added to better support nodes that spend most of their time “sleeping.” If a node is going to be 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 (as they broadcast fewer route requests and packets destined for other nodes) at the expense of reducing the “redundancy” in the overall mesh network.

Factory Default Value = 0

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 - Mesh LQ Threshold

NV_MESH_PENALTY_LQ_THRESHOLD_ID = 31

This allows for penalizing hops with poor link quality when establishing a mesh route. Hops that have a link quality worse than (i.e. a higher value than) the specified threshold will be counted as two hops instead of one. This allows the nodes to choose (for example) a three-hop route with good link quality over a two-hop route with poor link quality. The default threshold setting of 127 is the highest valid value, so that no “one hop penalty” will ever be applied.

Factory Default Value = 127

See also

NV32 - Mesh Rejection LQ Threshold

NV_MESH_REJECTION_LQ_THRESHOLD_ID = 32

This allows for rejecting hops with poor link quality when establishing a mesh route. Hops that have a link quality worse than (i.e. a higher value than) the specified threshold will be rejected as the node performs route requests. The default threshold setting of 127 is the highest valid value, so that all routes will be considered for mesh routing.

Factory Default Value = 127

See also

NV33 - Noise Floor

NV_CS_CD_LEVEL_ID = 33

The Carrier Sense and Collision Detect features work by checking the current ambient signal level before broadcasting (for Carrier Sense) and immediately after broadcasting (for Collision Detect), to determine whether some other node is broadcasting. In an environment with a lot of background noise, the noise floor can trigger false positives for these features, preventing the node from broadcasting or causing it to endlessly rebroadcast packets. On platforms that do not allow pokes (or radioPokes) to adjust the noise floor level, NV33 - Noise Floor can be used to define the signal strength that must be encountered to trigger the Carrier Sense and Collision Detect features. The parameter is in negative dBm, with a range from 0 to 127. If this parameter is not discussed in the section relating to your platform, refer to your platform’s processor data sheet to determine the pokes (or radioPokes) appropriate to adjust the noise floor level.

Factory Default Value = Platform Specific or None if not used by the platform

See also

NV34-38 – Reserved

Reserved for Synapse use.

NV39 - Radio LQ Threshold

NV_SNAP_LQ_THRESHOLD_ID = 39

This allows for ignoring packets with poor link quality. Link quality values range from a theoretical 0 (perfect signal, 0 attenuation) to a theoretical 127 (127 dBm “down”).

If you lower this parameter from its default value of 127, you are in effect defining an “acceptance criteria” on all received packets. If a packet comes in with a link quality worse (higher) than the specified threshold, then the packet will be completely ignored. This gives you the option to ignore other nodes that are “on the edge” of radio range. The idea is that you want other (closer) nodes to take care of communicating to that node.

Warning

If you set this parameter too low, your node may not accept any packets.

Factory Default Value = 127

NV40 - SNAPpy CRC

NV_SNAPPY_CRC_ID = 40

This is the 16-bit Cyclic Redundancy Check (CRC) of the currently loaded SNAPpy script. Most users will not need to write to this NV parameter. If you do change it from its automatically calculated value, you will make the SNAP node think its copy of the SNAPpy script is invalid, and it will not use it.

Not Modified on Factory Default

NV41 - Platform

NV_SYS_PLATFORM_ID = 41

This parameter makes it easier to write scripts that work on more than one type of SNAP node. Set this string parameter to some label that identifies your hardware platform.

New RF100 SNAP engines from Synapse will come with “RF100” in this parameter. Older RF100 engines may have had “RFEngine” here. If you are working with SNAP-compatible radios or engines from another source, the parameter might not be loaded with any meaningful value. Furthermore, like most other NV parameters, the value can be changed. To make use of this field, it is the responsibility of the user to ensure that the value in the parameter is meaningful and consistent across your collection of nodes.

To take advantage of the Platform value in your script, you must include the following line: 11 from synapse.snapsys import * When a script is loaded into a node, the script is compiled for the node. At compile time the platform variable is loaded with the contents of NV41 - Platform, which you can use to control which other SNAPpy modules get imported or what other code will be compiled. Because the variable is available at compile time (rather than only at run time), the compiler can optimize its code generation for the platform you are using, decreasing the code size and increasing the amount of space available for more complex scripts. The pinWakeup.py script, itself imported by the NewPinWakeupTest.py script, provides an example of this. See the “Cross-Platform Coding and Easy Pin Numbering” section in the SNAP Users Guide for examples of how to make use of the platform variable. If you do not import the synapse.snapsys module, the platform variable will not be defined.

Not Modified on Factory Default

NV42-49 – Reserved

Reserved for Synapse use.

NV50 - Enable Encryption

NV_CRYPTO_TYPE = 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:

0 = Use no encryption. (This is the default setting.)
1 = Use AES-128 encryption if you have firmware that supports it.
2 = Use Basic encryption.

If you set this parameter to a value that indicates encryption should be used, but either an invalid encryption key is specified (in NV51 - Encryption Key) or your firmware does not support the encryption mode specified, your transmissions will not be encrypted.

SNAP versions before 2.4 did not include the option for Basic encryption, and nodes upgraded from those firmware versions may contain False or True for this parameter. Those values correspond to 0 and 1 respectively and will continue to function correctly. Basic encryption is not as secure as AES-128 encryption, but it is available in all nodes starting with release 2.4.

If encryption is enabled and a valid encryption key is specified, all communication from the node will be encrypted, whether it is sent over the air or over a serial connection. Likewise, the node will expect that all communication to it is encrypted, and will be unable to respond to unencrypted requests from other nodes. If you have a node that you cannot contact because of a forgotten or otherwise unknown encryption key, you will have to reset the factory parameters on the node to reestablish contact with it.

Even with a valid encryption key, encryption is not enabled until the node is rebooted. See the Encryption section in the SNAP Users Guide for more details.

Factory Default Value = 0

NV51 - Encryption Key

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 None. 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.

An encryption key must be exactly 16 bytes (128 bits) long to be valid. You can specify your key as a series of keyboard-accessible characters, such as My!Password? 123 (note that there is a space between the question mark and the “1”), as a series of escaped hexadecimal character representations , such as \xD5\xAA\x96\x84\x94\x66\x97\x88\xF0\xAD\x10\x12\x91\x07\x86\xBA (note that none of these characters is directly representable as a standard ASCII character), as a string containing “escaped” characters using the backslash, such as \'\"\\\n\r\t\b\f\f\b\t\r\n\\\"\', or as any combination of the above.

When using escaped characters, it is possible that Portal will display them differently from how you entered them. For example, \0 is shown as \x00, \v is shown as \x0b, \" will display as ", and \' will display as ' if there is not also a " in your encryption key. Also, any characters you specify as escaped hexadecimal characters that fall into the range of “printable” ASCII characters (or simple escaped characters, such as \t) will be shown as those characters rather than the escaped hexadecimal value.

When escaping hexadecimal characters, the input is not case-sensitive. If you use a single backslash before a character that does not represent an escapable character, Portal will accept the two characters as two separate characters rather than one escaped character. Thus, \\h would be two characters and would be rendered on the screen as \h, as Portal adds the backslash to escape the backslash you entered.

Changes to this parameter (as with most NV parameters) have no effect until the node is rebooted. However, beginning with release 2.6, you can specify -51 (negative 51) as the NV parameter in a saveNvParam() call, and your encryption key will be saved (in NV51 - Encryption Key) and will be applied immediately without requiring a reboot. (Calling loadNvParam(-51) remains invalid.) Setting this parameter to an invalid encryption key using -51 as the NV parameter will disable encryption.

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, communications will not be encrypted unless the node is loaded with a SNAP firmware image that supports AES-128 encryption. Firmware images supporting AES-128 encryption will have “AES” in their filenames.

Refer to getInfo() for how to determine whether your firmware supports AES encryption.

Factory Default Value = None, which provides no encryption

NV52 - Lockdown

NV_LOCKDOWN_FLAGS_ID = 52

If this parameter is 0 (or never set at all), access to the node is unrestricted, and you can freely upload new scripts. If you set this parameter to 1 and the node is rebooted, then the system enters a “lockdown” mode where over-the-air script erasure or upload is not allowed.

Values other than 0 or 1 are reserved for future use and should not be used.

While in “lockdown” mode, you also cannot write to NV52 - Lockdown over the air. (In other words, you cannot bypass the lockdown by remotely turning it off.)

Even in this mode, you can still perform all operations (including script upload or erasure) over the local Packet Serial link (assuming one is available). The lockdown only applies to over-the-air access. If you have disabled your UARTs and set this parameter, you will have to make a serial connection and use Portal to reset your factory parameters to regain control of your node.

Factory Default Value = 0

NV53-62 – Reserved

Reserved for Synapse use.

NV63 - Alternate Radio Trim

NV_ALT_RADIO_TRIM_ID = 63

Usage is platform specific.

Not Modified on Factory Default

See also

NV64 - Vendor-Specific Settings

NV_VENDOR_SETTINGS_ID = 64

Similar in concept to NV11 - Feature Bits, this field is reserved for non-standard settings.

Not Modified on Factory Default

See also

NV65 - Clock Regulator

NV_CLOCK_REGULATOR_ID = 65

In platforms that have sleep modes that do not use a crystal, this parameter allows you to adjust the regulation of the internal timer that controls sleep durations. The parameter does not apply to all platforms. See the platform-specific section for your platform to determine how to best adjust this value, if necessary. This value has no effect on sleep timings that are crystal-controlled.

See also

NV66 - Radio Calibration Data

NV_RADIO_CALIBRATION_ID = 66

In platforms that require extra calibration data for proper radio operation, this parameter is used to store this calibration data. The parameter does not apply to all platforms. See the platform-specific section for your platform to determine how to best adjust this value, if necessary.

See also

NV67-69 – Reserved

Reserved for Synapse use.

NV70 - Transmit Power Limit

NV_TX_POWER_LIMIT_ID = 70

The Transmit Power Limit is a string that specifies, channel by channel, the maximum power level that can be transmitted on each channel. The units for the setting match those for the txPwr() function, ranging from 0 through 17 (with 17 being the highest power). They represent a cap, or governor, limiting how high the output can be on the specified channel, possibly reducing the specified power if txPwr() is set higher than the channel setting specified here.

The value in the parameter is a string 16 bytes long, where the first byte represents the maximum power on channel 0, the second byte represents the maximum power on channel 1, and the 16th byte represents the maximum power on channel 15. For example, if you wanted to crank up the power to the maximum possible on all channels, you would use:

saveNvParam(70,'\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11\x11')

This parameter is only implemented on MC1321x-based hardware. It does not override any system-set maximum power levels specified for government regulatory acceptance.

NV71-77 – Reserved

Reserved for Synapse use.

NV78 - Multicast Serial Forwarded Groups

NV_GROUP_SERIAL_FORWARDING_MASK_ID = 78

This is a 16-bit field controlling which multicast groups will be re-transmitted (forwarded) by the node over its serial connection. 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,” while 0x0003 indicates that messages will be forwarded to groups 1 and 2.

If this field is set to its default value of None, SNAP will use NV6 - Multicast Forward Groups to determine how packets will be re-transmitted over both radio and serial interfaces. If this field is set to any integer value, the multicast group(s) represented by the integer bitmask will have associated packets forwarded over the serial interface, and NV6 - Multicast Forward Groups will apply only toward multicast packets forwarded over the node’s radio interface.

By default, all nodes process and forward only group 1 (broadcast) packets.

Please note that, apart from the dependency when this parameter is set to None, NV5 - Multicast Process Groups, NV6 - Multicast Forward Groups, and NV78 - Multicast Serial Forwarded Groups 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 serially forward any combination of the 16 available groups, including none of them (by setting the field to zero, rather than None).

Factory Default Value = None

Note

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

NV79 – Reserved

Reserved for Synapse use.

NV80 - Default UART0 Rate

NV_UART0_BAUDRATE_ID = 80

New in version SNAP 2.6.

This parameter specifies the serial connection speed that will be applied to UART 0 for packet serial communications when the node boots. The valid values match those you would specify for a connection speed using the initUart() command. The default serial rate is 38,400 symbols per second.

Factory Default Value = 38400

NV81 - Default UART1 Rate

NV_UART1_BAUDRATE_ID = 81

New in version SNAP 2.6.

This parameter specifies the serial connection speed that will be applied to UART 1 for packet serial communications when the node boots. The valid values match those you would specify for a connection speed using the initUart() command. The default serial rate is 38,400 symbols per second.

Factory Default Value = 38400

NV82-89 – Reserved

Reserved for Synapse use.

NV90 - Default Radio Rate

NV_RADIO_RATE_ID = 90

New in version SNAP 2.6.

This parameter specifies which radio rate the node will use by default on reboot, in the absence of being set by the script. The valid values match those you would specify for the radio rate using the setRadioRate() command.

Factory Default Value = 0, which corresponds to 250 Kbps for 2.4 GHz devices

NV91 - CSMA Timeslot Settings

NV_CSMA_TIMESLOT_SETTINGS_ID = 91

New in version SNAP 2.6.

The Carrier Sense Multiple Access Timeslot Settings parameter lets you fine-tune the nature of the delay that will be applied to responses to multicasts, based on the status of NV18 - Collision Avoidance.

This new feature, introduced in SNAP version 2.6, takes an integer as the setting. The high byte is the number of time slots from which receiving nodes can select for their responses. The low byte sets the width of each timeslot in milliseconds. Setting either the high byte or low byte too large can cause communication problems, as messages can time out before they can be sent. But making small adjustments to the parameters can be effective if you expect especially large return messages or if you have a large number of responding nodes in your network.

Factory Default Value = 0x0404

NV92-127 – Reserved

Reserved for Synapse use.

NV128-254

These are user-defined NV parameters, and can be used for whatever purpose you choose. Factory defaulting a node’s NV parameters resets all of these parameters to None.

NV255 – Reserved

Reserved for Synapse use.