- SNAPcore API
- Release Notes
Released April 4th, 2017
- Modified topology
vmStat()response so that it is sent using the same type of RPC that was received.
Released October 6th, 2016
- Corrected an issue which could cause an OTA upgrade to fail.
- Corrected an edge-case issue which could cause memory corruption.
- Corrected an edge-case issue in the
- Added support for new module build for EU power levels: SM220UF1_EU. Calling
tellVmStat()response will reply using a directed multicast message if it was called via directed multicast.
Released June 7th, 2016
- Corrected an issue in random backoff where modulo bias distorted the frequency distribution of time slot selection.
- Corrected an issue where memory was being overwritten during packet storms.
- Corrected an issue where RF220SU turbo bit was not being set properly by vendor bits.
- Corrected an issue where NULL pointers were being de-referenced.
- Corrected an issue where sleep return values were returning incorrect values when short wakeup pulse occurred > 8s.
- Changed the External Power Amp Feature Bit (0x0010) to be OFF by default for the ATmega128RFA1 chip build.
- Added support for new module build for EU power levels: RF220SU_EU. Calling
- Randomize initial mesh sequence number so that RREQs don’t get dropped due to duplicates after subsequent reboots.
Released March 25th, 2016
Cumulative changes made to SNAPcore since version 2.6.9 add a number of new features, as well as correcting issues encountered since the 2.6.9 release.
- Corrected an issue where very short pulses to wake a sleeping node caused the return value from the sleep command to be incorrect.
- Corrected an issue where the byte list elements could not be incremented in place.
- Corrected an issue where deleting a byte list element using subscript -1 failed.
- Corrected an issue where oversized byte lists gave an incorrect error message.
- Corrected an issue where non-integer values produced troublesome results when a third “bitmask” parameter was included
- Corrected an issue where serial traffic to a node with no script could put the node into an unresponsive state.
- Corrected an issue where unresolved iterators could result in a leaked string buffer.
- Added support to accommodate calls to C functions from SNAPpy functions.
- Added getInfo(29) for the C compiler ID and getInfo(30) for the build ID hash, in order to support the new C functionality.
errno()enumerations 22 and 23 for EXCEEDED_C_DATA_SIZE and INVALID_C_METADATA, both of which are possible if you compile a script file for one firmware version but are trying to use it with a different version. Additionally, the C functionality provides access to the errno() return values as a means to define your own error codes.
- Added new built-in function
dmCallout(), which performs similar to the
callout()built-in but uses directed multicasts rather than unicasts for the message delivery.
- Added support for new module types: SNAPstick 220, RF220SU.
- Timing for the
pulsePin()function is more accurate.
- Moved the Enlarged Route Tables Feature Bit from NV 64 (platform-specific feature bits, which it shared with the ATmega128RFA1’s “Turbo Mode”) to NV 11 (feature bits, bit 0x800). Clearing this bit provides a route table with 10 entries. Setting it provides a table with 100 entries. Changes require a node reboot.
- Updated objRepr so that str(bytelist) matches the spacing of str(tuple), with no spaces between elements, for consistency and for more concise return values and printed values.
- Updated the Collision Avoidance algorithm to begin its “random backoff” timing based on the timing of the request to send a packet rather than the time when the last packet was received. (Note that for timing-sequenced replies to directed multicasts, the random backoff provided by collision avoidance is not applied.)
- The shifting window of relevance for multicast mesh sequence numbers that prevents multiple actions on a given message have been applied to the messaging used to establish unicast mesh routes.
- Adjusted the power output levels for the new RF220SU module to match restrictions required for FCC certification.
- With the release of version 2.6.2, SNAP only supports ATMEL-based modules and boards.
July 6th, 2015
SNAP 2.6 adds a number of new features to the SNAPcore, as well as correcting issues encountered since the 2.5.6 release. With the release of version 2.6.2, SNAP no longer supports legacy modules and boards. Be aware that a change for a chip also affects any modules or boards that are based on that chip. So, ATmega128RFA1 also implies RF200, SS200, RF266, SM200, SM220 and RF220.
- Added support for “for” loops.
- Added support for string multiplication.
- Added support for “in”/”not in” for strings and tuples.
- Added getinfo() calls that report the bank and address of the SNAPpy script.
- Added NV parameters for default radio and serial port rates to support running them at non-standard rates.
- Added an NV parameter to tune collision avoidance and increase or decrease the window in which a node might respond.
- Added the ability to perform topology polling even with no SNAPpy script loaded. Note that this feature is built-in to the SNAP firmware, and is usable even if no SNAPpy script is loaded.
- Added support for directed multicast. This allows multicast instructions to be sent to a specified list of nodes, rather than broadcasting to all nodes by group.
- Added limited support for dynamic mutable lists, subject to RAM limitations of the underlying hardware. This includes support for methods to emulate Python’s byte arrays.
- The reboot() function now accepts an optional parameter that delays a reboot for a number of milliseconds. This could, for example, allow a more graceful platform restart.
- Added optional parameter to setChannel() which allows changing of Network ID as well as channel.
- Added an optional third parameter to saveNvParam() to make it easier to manipulate individual bits in a single operation.
- Altered saveNvParam() to allow encryption keys to be changed without the need for a reboot.
- Expanded the getInfo() function to tell if a script is being run for the first time.
- The number of dynamic strings was increased at the expense of packet buffers. This required the addition/modification of getInfo () commands to retrieve counts of length 1, 16, 126, and 255 byte string buffers.
- Raised the number of global variables usable in SNAPpy scripts from 128 to 255.
- Added tiny and large string buffers, allowing dynamic strings to be as small as 1 byte, and as large as 255 bytes. This reorganized available strings into “tiny,” “small,” “medium,” and “large.”
- Corrected a bug where a unit in “wildcard mode” replaced original network IDs with its own when repeating multicast packets.
- The increase in the number of public functions in SNAP Release 2.6 eliminated the issue of non-public functions causing hooks to invoke the wrong script at run time. In Release 2.6 you can safely hook a non-public function without concern about the incorrect function executing at run-time.
- SNAP 2.5.6 made SNAP nodes incompatible with Portal’s “port scan” feature. SNAP 2.6 restores compatibility, and Portal can once again “detect” the nodes.
Released February 17th, 2015
CPU_IDLE – Behind the scenes, SNAP was constantly checking the radio and serial ports looking for incoming data to be processed. Starting in this version, if SNAP has checked all of the possible sources of incoming data and found nothing to be processed, it will use the CPU’s built-in “idle” capability to wait for the next interrupt. This reduces the power consumption of SNAP nodes that are not processing a lot of traffic, which can increase battery life. Note that if your SNAP node is being kept busy (for example, your application sends a lot of radio and/or serial traffic) then you will not see much benefit from this enhancement.
type() built-in added to SNAPpy. The ability to tell (at run-time) if a variable was (for example) a String versus an Integer was added to the SNAPpy Virtual Machine. As a quick example of where this can come in handy, the loadNvParam() function can reload a previously saved value, but until now there was no easy way to verify it’s TYPE. You could do “is None” and “is not None” checks before (and you still can) but the type() function is much more versatile.
SNAP now allows you to use different multicast “packet forwarding” settings on the serial port versus the radio. In previous versions of SNAP, NV Parameter 6 controlled which multicast groups were forwarded on both the radio and the serial port. You can still choose to do that, but now there is an additional NV Parameter 78 that when set gives the serial port its own settings, and means that the multicast group bitmask in NV Parameter 6 apply only to packets forwarded over the radio. This allows you to do things like “only forward group 0x0002” packets over the radio, and only forward group 0x0004 over the serial port”. To have NV Parameter 6 control both serial and radio forwarding, let NV Parameter 78 to None.
Includes a “SNIFFER Firmware” build for the ATmega1284RFR2.
PACKET_CRC – similar to the previous RPC_CRC feature introduced in SNAP 2.4.19, the PACKET_CRC feature added an additional software CRC to the radio packets. This was added to address issues with “packet storms” seen out in the field. Like RPC_CRC, enabling PACKET_CRC costs you two bytes of packet space (the additional CRC takes up two bytes). You can enable both CRCs if you wish, but this will cost you 4 bytes of packet space total. Here is how PACKET_CRC differs from RPC_CRC:
Aspect PACKET_CRC RPC_CRC Enabled by Feature Bit (look at NV #11) 0x0400 0x0100 Applies to All packet types, including RPC packets RPC packets only (both unicast and multicast) Calculated from The entire packet, including the header The packet payload only Applied to packets sent or received Over the radio only Radio and Serial (both)
I2C_RESTART – Prior to version 2.4.37, SNAP could only work with devices that used the “I2C_START, I2C_STOP, I2C_START, I2C_STOP” hardware handshake sequence for back-to-back commands (for example, an i2cWrite() to specify the data to read, followed by an i2cRead() to capture that data). Some I2C devices instead use a “I2C_START, I2C_RESTART, I2C_STOP” hardware handshake sequence. SNAP version 2.4.37 introduces an optional trailing parameter to the i2cWrite() function. When the optional parameter is provided and its value is True, SNAP will end the i2cWrite() command such that the beginning of an I2C_RESTART is created. The following i2cRead() will complete the I2C_RESTART (instead of generating an I2C_START). When the optional parameter is omitted, or is provided but its value is False, then the normal I2C_STOP sequence is generated. This enhancement allows SNAP to work with a wider range of I2C device.
SNAP has always had a “line mode” for HOOK_STDIN, but if you received too many characters before the receipt of a Carriage Return or Line Feed character, the system would print an error message and discard the data. Now even if you have specified “line mode” which technically means “don’t send the data until you get a CR or LF” the system will push what it has received so far if the buffer fills up. This makes the feature more useful. To support this new behavior, an new getStat() option has been added, getStat(18). By calling this function, your SNAPpy script can check and see why the HOOK_STDIN handler has been called.
The SM220 was the first SNAP Module to boast two onboard antennas – a “meandering F” and a “U.FL” connector. Support for software controlled antenna selection was added in this version (refer to NV Parameter 64).
The hardware inside the ATMEL radios includes “trim capacitors” that can be selectively enabled. You can now specify an alternate radio trim setting via an NV Parameter (#63 – NV_ALT_RADIO_TRIM_ID) to take advantage of this hardware capability. Most customers will never need to use this, but if for some reason your units are running higher in frequency then you can change this NV Parameter from its default value of 0 to enable 1-15 steps of additional capacitance (which will lower the radio frequency). The hardware does not have the ability to adjust the frequency in the other direction. (You cannot use the internal trim to raise the frequency.)
Sleep mode 2 (sleep(2, ticks)) added. This new sleep mode uses the “MAC Symbol Counter” inside the radio as a timebase, and provides finer-grained sleep durations.
The “moveable I2C” feature was back-ported from the STM32W108xB version of SNAP. Now if you need to connect an I2C peripheral to a different pair of pins, just specify the alternate SCL and SDA pins in the i2cInit() function call. These two new parameters are optional, you do not have to change your existing scripts unless you want to leverage this new capability. Calling the i2cInit() function without the new optional parameters causes the original pin assignments to be used.
- The behavior of the “is” clause in SNAPpy was changed to more closely match what full “desktop” Python does.
- Now if you call initUart() on a UART that is being used by the Packet Serial feature, the Packet Serial state machine gets re-initialized too. (There were users who were changing their serial port baud rates on the fly and getting poor results.)
- Robustness of the NV Parameters storage area when performing “page swaps” in the presence of power outages or system resets was improved.
- Replaced the original software-based implementation of AES-128 with one that utilized the internal “crypto engine” of the ATmega128xxx processors. This enhancement applied to all of the ATMEL chips.
- The getLq() built-in was changed to return a “snapshotted” value taken at the time the radio packet was received, instead of returning a “live” reading. This brings the ATMEL platforms in line with the rest of the SNAP platforms.
- Overall current consumption was reduced slightly by removing the initialization of some unused hardware. The “go to sleep” and “wake back up” code paths were also optimized for speed.
- Fixed an issue with calling SNAPpy functions with too many parameters that in certain situations could lead to string buffer leaks.
- Corrected issue with SNAPpy script upload with RF100 and MC1321x.
- Reduced txPwr() levels for “worldwide” from 4 to 2 in SM220.
- It was noticed that the chip was sometimes pausing for about 10 milliseconds at a 5 milliamp current draw before fully entering sleep mode. Since many SNAP applications are battery powered, this short period of higher power consumption was removed. A version of the “DMX” variant of SNAP for the SM220 module was created and added to the set of firmware images.
- Comparison of SNAPpy integers (signed 16-bit) was improved. Prior to this version, a comparison like “20000 > -12768” would return False instead of True due to 16-bit wrap-around. This has been corrected. Note that this might require changes to your existing SNAPpy scripts if you were relying on the previous (incorrect) behavior.
- The Manufacturing Date was not being preserved through a Factory Default (fixed)
- In an exhaustive review of the SNAPpy Virtual Machine, numerous “dynamic string leaks” were identified and corrected.
- The default Feature Bits for the RF266 were changed from “enable both UARTs” (this is the default used by all other ATMEL-based platforms) to “enable UART1 only”. This was done because the first UART (UART0) is not brought out to any of the RF266 pins.
- It was discovered that the internal FLASH of the ’RFR2 chips was not 100% compatible with the FLASH of the original ’RFA1 chip. This required the FLASH “write” routines to be re-written, resulting in the ’RFR2 chips gaining their own unique Boot Loader. The ’RFR2 chips boasted an internal feature ATMEL dubbed “SRT – Smart Radio Technology.” This was supposed to enable a 5 milliamp “radio receive” mode. A lot of effort went into this, but we were unable to get the chips to reliably enter and stay in this mode. (You will likely see some current savings on a ’RFR2 but not as much as we had hoped).
- It was discovered that the sleep() function could wake up early due to the internal MAC Symbol Counter rolling over, as well as the internal 1 millisecond clock interrupt occurring. Both of these issues were corrected, so that the unit would remain asleep for the requested duration. As part of the above sleep() work, the sleep software was recalibrated for higher accuracy (the test case for this work was a 12 hour sleep duration).